ai-install-guard 0.1.0 → 0.3.0

package/hooks/register.tsx

@@ -1,14 +1,18 @@
 import type { EngineInterface, Register } from 'claude-code'
 import { atom, update } from 'claude-code'
 
-import { decisionFor, forgetDecisions, loadDecisions, loadLastView, MAX_REPORT_CHARS, saveLastView } from './guard/decisions'
-import { drawPane, REPORT_TEXT } from './guard/pane'
-import { PANE_ID, scanningView, viewOf } from './guard/view'
+import { BROWSE_NOTE, judge } from './gate/gate'
+import { readPluginArgs, readShellCommand } from './gate/requests'
+import { expandHome } from './gate/resolve'
+import { badgeFor } from './guard/badge'
+import { forgetDecisions, loadDecisions, loadLastView, loadReport } from './guard/decisions'
+import { drawPane } from './guard/pane'
+import { showScan } from './guard/run'
+import { PANE_ID } from './guard/view'
 import { modHost } from './mod-host'
 import type { Host } from './scan/host'
-import { formatReport } from './scan/report'
+import { looksRemote, parseRemote, type RemoteSpec } from './scan/remote'
 import { safeLine } from './scan/safe-text'
-import { scanFolder } from './scan/scan'
 
 // Claude Code reads every state reference from the file that uses it, so each
 // module declares its own atom for the pane's view.
@@ -17,26 +21,36 @@ const viewAtom = atom({ plugin: 'ai-install-guard', key: 'view' } as const, null
 const USAGE = [
   'Usage:',
   '  /guard scan <path>            Scan a local plugin, mod or skill folder without installing it',
-  '  /guard scan --details <path>  The same, with the full report as text',
+  '  /guard scan <repository>      Fetch one commit of a repository and scan it: https://host/owner/repo,',
+  '                                github:owner/repo or owner/repo, with an optional @ref',
+  '      --ref <branch|tag|commit>   The commit to scan (the default branch otherwise)',
+  '      --path <folder>             A folder inside the repository',
+  '      --details                   The full report as text',
   '  /guard report                 Reopen the last report',
+  '  /guard badge                  A README badge for the last scan (Safe to install or Review what it can do)',
   '  /guard list                   Your approved and rejected versions',
   '  /guard forget <name>          Forget decisions about a name, so it is judged again',
 ].join('\n')
 
-export const register: Register = on => {
+export const register: Register = (on, options) => {
+  // Off unless you turn it on: the lookups send package and plugin names out.
+  const lookups = options.outsideLookups === true
+
   on('session.start', async ($, e, next) => {
     await $.command.register({
       name: 'guard',
       description: 'Scan a plugin, mod, skill or MCP server without installing it',
-      argumentHint: 'scan <path> | report | list | forget <name>',
+      argumentHint: 'scan <path | repository> | report | badge | list | forget <name>',
     })
     return next(e)
   })
 
   on('command.run', { command: 'guard' }, async ($, e) => {
-    const { sub, rest, details } = splitArgs(e.args)
-    if (sub === 'scan' && rest !== '') return { text: await scan($, rest, details) }
+    const { sub, rest, details, ref, path, error } = splitArgs(e.args)
+    if (error !== undefined) return { text: `AI Install Guard: ${error}\n\n${USAGE}` }
+    if (sub === 'scan' && rest !== '') return { text: await scan($, rest, details, { ref, path }, lookups) }
     if (sub === 'report') return { text: await reopen($) }
+    if (sub === 'badge') return { text: await badge($) }
     if (sub === 'list') return { text: await list($) }
     if (sub === 'forget' && rest !== '') {
       const count = (await forgetDecisions($, rest)).length
@@ -45,6 +59,33 @@ export const register: Register = on => {
     return { text: USAGE }
   }).catch(() => ({ text: 'AI Install Guard: the command failed before it could answer.' }))
 
+  // Gate A: the person's own /plugin install and /plugin marketplace add. An
+  // install is answered in the command's place, so nothing installs, until
+  // the person approves that exact version.
+  on('command.run', { command: 'plugin' }, async ($, e, next) => {
+    const reading = readPluginArgs(e.args)
+    if (reading.kind === 'pass') {
+      if (reading.browse) $.ui.toast(BROWSE_NOTE)
+      return next(e)
+    }
+    const judged = await judge($, reading, { origin: 'command', args: e.args, label: reading.label }, lookups)
+    if (judged.kind === 'hold') return { text: judged.text }
+    if (judged.note !== undefined) $.ui.toast(judged.note)
+    return next(e)
+  }).catch(($, e, next) => (next.called ? next(e) : { text: 'AI Install Guard stopped this install: it failed before it could check it, so nothing was installed.' }))
+
+  // Gate B: Claude installing a plugin or adding a marketplace with the claude
+  // command. The command is refused, with a reason Claude reads, until the
+  // person approves that exact version in the pane.
+  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
+    const reading = readShellCommand(e.command)
+    if (reading.kind === 'pass') return next(e)
+    const judged = await judge($, reading, { origin: 'tool', args: e.command, label: reading.label }, lookups)
+    if (judged.kind === 'hold') return { deny: judged.text }
+    if (judged.note !== undefined) $.ui.toast(judged.note)
+    return next(e)
+  }).catch(($, e, next) => (next.called ? next(e) : { deny: 'AI Install Guard stopped this command: it may install a plugin or add a marketplace, and the guard failed before it could check it. Nothing was installed.' }))
+
   on('ui.render', { component: 'Pane', requestId: PANE_ID }, ($, e) => drawPane($, e))
 }
 
@@ -54,57 +95,43 @@ export const register: Register = on => {
  * findings stay in the pane. Where no pane can show (a headless run), or with
  * --details, the answer is the full text report.
  */
-async function scan($: EngineInterface, target: string, details: boolean): Promise<string> {
+async function scan($: EngineInterface, target: string, details: boolean, flags: { ref?: string; path?: string }, lookups: boolean): Promise<string> {
   const host = modHost($)
-  const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
-  // Until this scan's report is stored, Copy report has nothing to copy, never
-  // the previous scan's report.
-  await $.store.delete(REPORT_TEXT).catch(() => undefined)
-  await update($, viewAtom, () => scanningView(target, 'approve'))
-  $.ui.status(`AI Install Guard: scanning ${safeLine(target)}`)
-  try {
-    const report = await scanFolder(host, target, await expandHome(host, target), {
-      // Stage names can carry a candidate's own words (a plugin's name).
-      onStage: stage => update($, viewAtom, current => (current === null ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
-    })
-    // A tree you already decided on shows that decision, not the buttons
-    // again, unless it now judges worse than when you approved it.
-    const earlier = report.inventory === undefined ? undefined : await decisionFor($, report.inventory.treeHash, report.verdict.kind).catch(() => undefined)
-    const view = earlier === undefined ? viewOf(report, 'approve') : { ...viewOf(report, 'approve'), decision: earlier.decision, decidedAt: earlier.decidedAt }
-    const text = formatReport(report, { details: true })
-    // The report text is stored before the pane shows the verdict, so Copy
-    // report always copies this scan's report. It is held well inside the
-    // store's limit; a failed write leaves Copy with nothing, not old text.
-    const stored = text.length > MAX_REPORT_CHARS ? `${text.slice(0, MAX_REPORT_CHARS)}\n… the report was cut here to fit the store` : text
-    await $.store.set(REPORT_TEXT, stored).catch(() => undefined)
-    await update($, viewAtom, () => view)
-    await saveLastView($, view).catch(() => undefined)
-    $.ui.toast(`AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}`)
-    // Where no pane shows, the answer is the whole report: findings and advice.
-    if (!opened.isPlaced || details) return text
-    return `AI Install Guard: ${report.verdict.recommendation} for ${safeLine(target)}. The report is in the pane; /guard report reopens it.`
-  } catch (error) {
-    const reason = `Could not verify ${safeLine(target)}: ${safeLine(reasonOf(error))}`
-    await $.store.set(REPORT_TEXT, reason).catch(() => undefined)
-    // The pane, and the report /guard report reopens, show this failure: never
-    // a scanning pane, and never an older verdict in its place.
-    const failed = { ...scanningView(target, 'approve'), stage: '', verdict: { kind: 'unverified' as const, recommendation: 'Could not verify', reasons: [reason], counts: { pass: 0, warn: 0, fail: 0, info: 0 } } }
-    await update($, viewAtom, () => failed).catch(() => undefined)
-    await saveLastView($, failed).catch(() => undefined)
-    return reason
-  } finally {
-    $.ui.status(undefined)
-  }
+  const shown = await showScan(
+    $,
+    target,
+    async () => {
+      const spec = await remoteSpecFor(host, target, flags)
+      return spec === undefined ? { folder: await expandHome(host, target) } : { remote: spec }
+    },
+    { action: 'approve', lookups },
+  )
+  if (shown.kind === 'failed') return shown.reason
+  // Where no pane shows, the answer is the whole report: findings and advice.
+  if (!shown.placed || details) return shown.text
+  return `AI Install Guard: ${shown.report.verdict.recommendation} for ${safeLine(target)}. The report is in the pane; /guard report reopens it.`
 }
 
 async function reopen($: EngineInterface): Promise<string> {
   const view = await loadLastView($)
   if (view === undefined) return 'AI Install Guard: no report yet. Run /guard scan <path>.'
-  await update($, viewAtom, () => ({ ...view, confirming: false }))
+  await update($, viewAtom, () => ({ ...view, confirming: false, deciding: false }))
   const opened = await $.ui.open({ id: PANE_ID, title: 'AI Install Guard', focus: true }).catch(() => ({ isPlaced: false }))
   if (opened.isPlaced) return `AI Install Guard: reopened the report for ${safeLine(view.target)}.`
-  const text = await $.store.get(REPORT_TEXT)
-  return typeof text === 'string' ? text : 'AI Install Guard: the last report is no longer stored.'
+  return (await loadReport($, view.scanId)) ?? 'AI Install Guard: the last report is no longer stored.'
+}
+
+async function badge($: EngineInterface): Promise<string> {
+  const view = await loadLastView($)
+  const made = badgeFor(view)
+  if ('refusal' in made) return `AI Install Guard: ${made.refusal}`
+  return [
+    `AI Install Guard: a README badge for ${view?.target ?? 'the last scan'} at ${made.pin}. Paste it near the top of your README:`,
+    '',
+    made.markdown,
+    '',
+    'It names the exact version that was scanned. A change to your code needs a new scan and a new badge; the guard checks a badge against its own scan and never trusts it.',
+  ].join('\n')
 }
 
 async function list($: EngineInterface): Promise<string> {
@@ -119,36 +146,51 @@ async function list($: EngineInterface): Promise<string> {
 }
 
 /**
- * `scan --details "my folder"` → `{ sub: 'scan', details: true, rest: 'my folder' }`.
- * `--details` counts only as its own token right after the subcommand, so a
- * quoted path that contains it is left whole.
+ * `scan --details --ref v1 "my folder"` → `{ sub: 'scan', details: true, ref: 'v1', rest: 'my folder' }`.
+ * Options count only as their own tokens right after the subcommand, so a
+ * quoted path that contains one is left whole.
  */
-export function splitArgs(args: string): { sub: string; rest: string; details: boolean } {
+export function splitArgs(args: string): { sub: string; rest: string; details: boolean; ref?: string; path?: string; error?: string } {
   const trimmed = args.trim()
   const space = trimmed.search(/\s/)
   const sub = space === -1 ? trimmed : trimmed.slice(0, space)
   let rest = space === -1 ? '' : trimmed.slice(space).trim()
-  const details = /^--details(?:\s|$)/.test(rest)
-  if (details) rest = rest.slice('--details'.length).trim()
-  return { sub: sub.toLowerCase(), rest: unquote(rest), details }
-}
-
-function unquote(text: string): string {
-  return /^(["']).*\1$/.test(text) ? text.slice(1, -1) : text
+  let details = false
+  let ref: string | undefined
+  let path: string | undefined
+  for (;;) {
+    const option = /^(--details|--ref|--path)(?:\s+|$)/.exec(rest)
+    if (option === null) break
+    rest = rest.slice(option[0].length)
+    if (option[1] === '--details') {
+      details = true
+      continue
+    }
+    const value = /^("[^"]*"|'[^']*'|\S+)\s*/.exec(rest)
+    if (value === null || (value[1] as string).startsWith('--')) return { sub: sub.toLowerCase(), rest: '', details, error: `${option[1]} needs a value` }
+    rest = rest.slice(value[0].length)
+    if (option[1] === '--ref') ref = unquote(value[1] as string)
+    else path = unquote(value[1] as string)
+  }
+  return { sub: sub.toLowerCase(), rest: unquote(rest), details, ref, path }
 }
 
-async function expandHome(host: Host, path: string): Promise<string> {
-  if (path !== '~' && !path.startsWith('~/')) {
-    return path
-  }
-  const { exitCode, stdout } = await host.run(['printenv', 'HOME'])
-  const home = stdout.trim()
-  if (exitCode !== 0 || home === '') {
-    throw new Error('could not find the home folder')
+/**
+ * The remote source `target` names, or undefined for a local folder. A bare
+ * owner/repo is a folder when one exists by that name and no --ref or --path
+ * says otherwise.
+ */
+async function remoteSpecFor(host: Host, target: string, flags: { ref?: string; path?: string }): Promise<RemoteSpec | undefined> {
+  const shape = looksRemote(target)
+  const asked = flags.ref !== undefined || flags.path !== undefined
+  if (shape === 'local') {
+    if (asked) throw new Error('--ref and --path apply to a repository, not to a folder')
+    return undefined
   }
-  return home + path.slice(1)
+  if (shape === 'maybe' && !asked && (await host.stat(target).catch(() => undefined)) !== undefined) return undefined
+  return parseRemote(target, { ref: flags.ref, subdir: flags.path })
 }
 
-function reasonOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
+function unquote(text: string): string {
+  return /^(["']).*\1$/.test(text) ? text.slice(1, -1) : text
 }

package/hooks/scan/checks/code.ts

@@ -21,6 +21,7 @@ import {
   WRITE_SHELL,
 } from './patterns'
 import { basename, extension, findAll, findFirst, spanKinds, type Match, type SpanKind } from './text'
+import { describePrograms, programsIn, type ProgramUse } from './programs'
 import { row, worse, type CheckResult, type Evidence, type Status } from './types'
 
 const GROUP = 'code' as const
@@ -159,6 +160,7 @@ const ANSI = /\u001b\[[0-9;?]{0,40}[A-Za-z]|\u001b\][^\u0007\u001b]{0,1000}\u000
 
 function hiddenCheck(ctx: ScanContext): CheckResult {
   const evidence: Evidence[] = []
+  let foundLone = false
   for (const file of ctx.files) {
     const text = file.isText ? ctx.text(file.path) : undefined
     if (text === undefined) continue
@@ -172,10 +174,24 @@ function hiddenCheck(ctx: ScanContext): CheckResult {
     for (const match of findAll(text, VARIATION_SUPPLEMENT, 3)) {
       evidence.push({ file: file.path, line: match.line, excerpt: `${[...match.text].length} invisible variation selectors in a row (a way to smuggle data)`, status: cap('fail') })
     }
-    const bidi = findAll(text, BIDI, 5)
-    for (const match of bidi) {
+    // In code a control that is all of a string, with nothing after it, is
+    // only a warning, and only in a language the tokenizer knows. Failures
+    // are found first, so no number of such strings can crowd out a real one.
+    const language = isCode ? (ctx.interpreters.get(file.path) ?? languageOf(file.path, text)) : 'other'
+    let kinds: ((index: number) => SpanKind) | undefined
+    const kindAt = (index: number): SpanKind => (kinds ??= spanKinds(text, language))(index)
+    const lone = (index: number): boolean => language !== 'other' && isLoneInString(text, index, kindAt)
+    for (const match of findAll(text, BIDI, 5, index => !lone(index))) {
       evidence.push({ file: file.path, line: match.line, excerpt: `bidirectional control ${codePoints(match.text)}: text may read differently than it runs`, status: cap(isCode ? 'fail' : 'warn') })
     }
+    if (language !== 'other') {
+      for (const match of findAll(text, BIDI, 3, lone)) {
+        const status = cap('warn')
+        if (status === 'warn') foundLone = true
+        const excerpt = `bidirectional control ${codePoints(match.text)} is all of a string: it cannot reorder code there, but the string looks empty; write it as ${escapeFor(match, file.path, text, language)}`
+        evidence.push({ file: file.path, line: match.line, excerpt, status })
+      }
+    }
     const zero = findAll(text, ZERO_WIDTH, 50)
     if (zero.length > 0 && (isCode || isMarkdown(file.path))) {
       const first = zero[0] as (typeof zero)[number]
@@ -191,12 +207,52 @@ function hiddenCheck(ctx: ScanContext): CheckResult {
       id: 'code.hidden-characters',
       group: GROUP,
       title: 'Hidden characters',
-      advice: 'Invisible tag characters carry text the model reads and you do not see. Bidirectional controls make code read differently than it runs. Neither belongs in a plugin.',
+      advice: `Invisible tag characters carry text the model reads and you do not see. Bidirectional controls make code read differently than it runs. Neither belongs in a plugin.${
+        foundLone ? " A plugin that needs a direction mark, as one for right-to-left text does, should write it as an escape such as '\\u200f', never the raw character, which makes its string look empty." : ''
+      }`,
     },
     evidence,
   )
 }
 
+/**
+ * Whether the bidirectional control at `index` is all of a one-line string,
+ * as in `const RLM = '\u200f'`, with nothing after it on its line but blanks,
+ * `;`, `,` or a comment. What it can reorder runs to the end of its line, and
+ * there that is no code; what comes before it does not move.
+ */
+function isLoneInString(text: string, index: number, kindAt: (index: number) => SpanKind): boolean {
+  const quote = text[index - 1]
+  if ((quote !== "'" && quote !== '"') || text[index + 1] !== quote) return false
+  if (kindAt(index - 1) !== 'string' || kindAt(index) !== 'string' || kindAt(index + 1) !== 'string') return false
+  // The quote must open the string: what comes before it is no string, and no
+  // `}`, which may close a template's `${...}` and leave the quote as its text.
+  if (index >= 2 && (kindAt(index - 2) === 'string' || text[index - 2] === '}')) return false
+  // Only LF ends the line here. U+2028 and U+2029 end a JavaScript line, but
+  // editors often show them inline and U+2028 ends no bidi paragraph, so code
+  // after one can still be reordered: that fails.
+  for (let i = index + 2; i < text.length && text[i] !== '\n'; i += 1) {
+    const char = text[i]
+    if (char === ' ' || char === '\t' || char === ';' || char === ',') continue
+    // Only a CR that ends the line: a lone one ends a line too, and code may follow it.
+    if (char === '\r' && (i + 1 === text.length || text[i + 1] === '\n')) continue
+    const kind = kindAt(i)
+    if (kind !== 'comment' && kind !== 'trailing-comment') return false
+  }
+  return true
+}
+
+/** `'\u200f'` for a lone control, as its language writes the escape. */
+function escapeFor(match: Match, path: string, text: string, language: Language): string {
+  const hex = (match.text.codePointAt(0) as number).toString(16).padStart(4, '0')
+  if (language !== 'shell') return `${text[match.index - 1]}\\u${hex}${text[match.index - 1]}`
+  // fish reads the escape bare. Other shells differ (sh has no such escape,
+  // and bash before 4.2 not in $'...'), but every printf takes octal bytes.
+  if ((interpreterOf(text) || extension(path)) === 'fish') return `\\u${hex}`
+  const octal = [...new TextEncoder().encode(match.text)].map(byte => `\\${byte.toString(8)}`).join('')
+  return `"$(printf '${octal}')"`
+}
+
 /** Tag characters U+E0020..U+E007E mirror printable ASCII. */
 export function decodeTags(text: string): string {
   let out = ''
@@ -213,6 +269,9 @@ function codePoints(text: string): string {
 
 function execCheck(ctx: ScanContext): CheckResult {
   const evidence: Evidence[] = []
+  const uses: ProgramUse[] = []
+  let buildsCode = 0
+  let downloads = 0
   for (const file of codeFiles(ctx)) {
     // Code files, and anything live code runs or loads whatever its name.
     if (!isCodeFile(file.path, file.text) && !LIVE_ROLES.has(file.role)) continue
@@ -227,18 +286,35 @@ function execCheck(ctx: ScanContext): CheckResult {
       evidence.push(...evidenceFor(file, pattern, inModule ? 'fail' : 'warn', match => `${what}: ${match.excerpt}`, 3))
     }
     evidence.push(...evidenceFor(file, DOWNLOAD_AND_RUN, 'fail', match => `downloads or decodes code and runs it: ${match.excerpt}`, 3))
+    // The summary counts live code only: tests and docs are only reported.
+    if (isLive(file.role)) {
+      const keep = (index: number) => !['comment', 'regex', 'trailing-comment'].includes(file.kindAt(index))
+      uses.push(...programsIn(file.path, file.text, file.language, keep))
+      // The same language rules as the evidence, each place counted once.
+      const fromText = file.language === 'js' ? [CODE_FROM_TEXT] : file.language === 'python' ? [PYTHON_CODE_FROM_TEXT] : file.language === 'shell' ? [SHELL_EVAL] : [CODE_FROM_TEXT, PYTHON_CODE_FROM_TEXT, SHELL_EVAL]
+      buildsCode += new Set(fromText.flatMap(pattern => findAll(file.text, pattern, 50, keep).map(match => match.line))).size
+      downloads += findAll(file.text, DOWNLOAD_AND_RUN, 50, keep).length
+    }
   }
   return row(
     {
       id: 'code.execution',
       group: GROUP,
       title: 'Running programs and building code at run time',
-      advice: 'Inside a mod this is a red flag: mods reach the machine only through $. In a script, check that each command it runs is one its purpose needs.',
+      advice:
+        'Check that each program fits what it says it does. Shells, compilers and programs chosen while it runs can do anything, so look at those first. Inside a mod any of this is a red flag: a mod reaches your machine only through Claude Code.',
+      summary: summaryOrFallback(describePrograms(uses, { buildsCode, downloads }), evidence),
     },
     evidence,
   )
 }
 
+/** A row that found something but could not name it still says so in words. */
+function summaryOrFallback(summary: string[], evidence: readonly Evidence[]): string[] {
+  if (summary.length > 0 || !evidence.some(item => item.status === 'warn' || item.status === 'fail')) return summary
+  return ['Starts other programs; which ones could not be read from the code']
+}
+
 function obfuscationCheck(ctx: ScanContext): CheckResult {
   const evidence: Evidence[] = []
   for (const file of codeFiles(ctx)) {
@@ -402,12 +478,36 @@ function denseLine(text: string): Match | undefined {
 
 function credentialsCheck(ctx: ScanContext): CheckResult {
   const evidence: Evidence[] = []
+  const secrets = new Set<string>()
+  const places = new Set<string>()
+  const files = new Set<string>()
+  const sending = new Set<string>()
   for (const file of codeFiles(ctx)) {
-    if (file.role === 'hook-script') continue
+    // Hook scripts and MCP configuration are judged where their target is
+    // known: the hooks check, and mcp.credentials with the server's host.
+    if (file.role === 'hook-script' || file.role === 'mcp-config') continue
     const sends = [NETWORK_CODE, NETWORK_COMMAND, COLLECTION_HOST].some(pattern => active(file, pattern, 1).length > 0)
     const lead = sends ? 'with network code in the same file: ' : ''
-    evidence.push(...evidenceFor(file, CREDENTIAL_PATH, sends ? 'fail' : 'warn', match => `${lead}${match.excerpt}`, 3))
-    evidence.push(...evidenceFor(file, SECRET_ENV, sends ? 'fail' : 'warn', match => `${lead}reads ${secretName(match)}`, 3))
+    const paths = evidenceFor(file, CREDENTIAL_PATH, sends ? 'fail' : 'warn', match => `${lead}${match.excerpt}`, 3)
+    const names = evidenceFor(file, SECRET_ENV, sends ? 'fail' : 'warn', match => `${lead}reads ${secretName(match)}`, 3)
+    evidence.push(...paths, ...names)
+    if (!isLive(file.role)) continue
+    for (const match of active(file, CREDENTIAL_PATH, 20)) places.add(match.text.trim().replace(/\/$/, ''))
+    // A dump of the whole environment (JSON.stringify(process.env), printenv) is every secret at once.
+    for (const match of active(file, SECRET_ENV, 20)) secrets.add(/process\.env|os\.environ|printenv|\benv\b/.test(match.text) ? 'all your environment variables' : secretName(match))
+    if (paths.length + names.length > 0) {
+      files.add(file.path)
+      if (sends) sending.add(file.path)
+    }
+  }
+  const summary: string[] = []
+  const things = [...secrets, ...places]
+  if (things.length > 0) {
+    summary.push(`Reads ${things.slice(0, 5).join(', ')}${things.length > 5 ? ` and ${things.length - 5} more` : ''}${sending.size > 0 ? ', in code that can also reach the network' : ''}`)
+    if (secrets.size > 0) summary.push(`Secrets from your environment: ${[...secrets].join(', ')}`)
+    if (places.size > 0) summary.push(`Credential files and stores: ${[...places].join(', ')}`)
+    if (sending.size > 0) summary.push(`Worth a look: ${[...sending].slice(0, 4).join(', ')} can also send data over the network`)
+    summary.push(`In ${files.size} file${files.size === 1 ? '' : 's'}: ${[...files].slice(0, 4).join(', ')}${files.size > 4 ? ` and ${files.size - 4} more` : ''}`)
   }
   return row(
     {
@@ -415,6 +515,7 @@ function credentialsCheck(ctx: ScanContext): CheckResult {
       group: GROUP,
       title: 'Credentials and secrets read by code',
       advice: 'Code that reads your keys, tokens or browser data and can reach the network can steal them. Do not install it unless that is plainly its job.',
+      summary,
     },
     evidence,
   )
@@ -506,7 +607,8 @@ function domainsCheck(ctx: ScanContext): CheckResult {
       const authority = /\/\/([^/?#]{0,300})/.exec(match.text)?.[1] ?? ''
       const hasUserInfo = authority.includes('@')
       const host = (/(\[[0-9a-fA-F:]+\]|[A-Za-z0-9.-]+)/.exec(authority.slice(authority.lastIndexOf('@') + 1))?.[1] ?? '').toLowerCase()
-      if (host === '') continue
+      // A one-word host (https://x) is a placeholder, not a place on the internet.
+      if (host === '' || (!host.includes('.') && !host.startsWith('['))) continue
       if (hasUserInfo) evidence.push(judged(file, match, 'warn', `an address whose real host hides after "@": ${host}`))
       if (/^(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0|example\.(?:com|org|net))$/.test(host)) continue
       if (!hosts.has(host)) hosts.set(host, { file: file.path, line: match.line })