ai-install-guard 0.1.0 → 0.2.0

package/hooks/register.tsx

@@ -1,14 +1,16 @@
 import type { EngineInterface, Register } from 'claude-code'
 import { atom, update } from 'claude-code'
 
+import { badgeFor } from './guard/badge'
 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 { modHost } from './mod-host'
 import type { Host } from './scan/host'
+import { looksRemote, parseRemote, type RemoteSpec } from './scan/remote'
 import { formatReport } from './scan/report'
 import { safeLine } from './scan/safe-text'
-import { scanFolder } from './scan/scan'
+import { scanFolder, scanRemote } 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 +19,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
@@ -54,7 +66,7 @@ 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
@@ -63,13 +75,16 @@ async function scan($: EngineInterface, target: string, details: boolean): Promi
   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), {
+    const options = {
+      lookups,
       // 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),
-    })
+      onStage: (stage: string) => update($, viewAtom, current => (current === null ? current : { ...current, stage: safeLine(stage) })).then(() => undefined),
+    }
+    const spec = await remoteSpecFor(host, target, flags)
+    const report = spec === undefined ? await scanFolder(host, target, await expandHome(host, target), options) : await scanRemote(host, target, spec, options)
     // 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 earlier = report.inventory === undefined ? undefined : await decisionFor($, { treeHash: report.inventory.treeHash, sha: report.source?.sha }, 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
@@ -107,6 +122,19 @@ async function reopen($: EngineInterface): Promise<string> {
   return typeof text === 'string' ? text : '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> {
   const decisions = await loadDecisions($)
   if (decisions.length === 0) return 'AI Install Guard: no decisions yet.'
@@ -119,18 +147,49 @@ 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 }
+  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 }
+}
+
+/**
+ * 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
+  }
+  if (shape === 'maybe' && !asked && (await host.stat(target).catch(() => undefined)) !== undefined) return undefined
+  return parseRemote(target, { ref: flags.ref, subdir: flags.path })
 }
 
 function unquote(text: string): string {

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 })

package/hooks/scan/checks/mcp.ts

@@ -0,0 +1,271 @@
+import type { McpServer, ScanContext } from './context'
+import { COLLECTION_HOST, CREDENTIAL_PATH, DOWNLOAD_AND_RUN, NETWORK_COMMAND, SECRET_ENV, UNPINNED_RUNNER } from './patterns'
+import { capEvidence, row, type CheckResult, type Evidence, type Status } from './types'
+
+const GROUP = 'mcp' as const
+
+/** Words in a variable's name that say nothing about whose credential it is. */
+const GENERIC_WORDS = new Set(['api', 'key', 'keys', 'token', 'tokens', 'auth', 'oauth', 'secret', 'access', 'session', 'client', 'bot', 'app', 'personal', 'private', 'password', 'credentials', 'application', 'hub', 'code'])
+
+/** Short or product names in a variable, and the service they belong to. */
+const SERVICE_WORDS: Record<string, string> = { gh: 'github', hf: 'huggingface', hugging: 'huggingface', face: 'huggingface', claude: 'anthropic', node: 'npm' }
+
+/** The domains each service's keys belong on. A host must be one of them or below one. */
+const SERVICE_DOMAINS: Record<string, readonly string[]> = {
+  github: ['github.com', 'githubcopilot.com', 'githubusercontent.com', 'ghe.com'],
+  gitlab: ['gitlab.com'],
+  anthropic: ['anthropic.com', 'claude.ai', 'claude.com'],
+  openai: ['openai.com'],
+  aws: ['amazonaws.com', 'aws.amazon.com', 'aws.dev'],
+  google: ['googleapis.com', 'google.com'],
+  azure: ['azure.com', 'microsoft.com', 'windows.net', 'azure.net'],
+  slack: ['slack.com'],
+  stripe: ['stripe.com'],
+  huggingface: ['huggingface.co'],
+  npm: ['npmjs.org', 'npmjs.com'],
+}
+
+/** A `${NAME}` or `$NAME` reference to an environment variable. */
+const ENV_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]{0,100})(?::-[^}]{0,200})?\}|\$([A-Za-z_][A-Za-z0-9_]{0,100})/g
+
+/** An address anywhere in a command line, a shell script's included. */
+const ADDRESS = /\b(?:https?|wss?):\/\/[^\s'"`<>)]{1,500}/gi
+
+/** Container options that take the next argument as their value. */
+const VALUE_FLAGS = new Set([
+  '-a', '--attach', '-e', '--env', '--env-file', '-v', '--volume', '--mount', '-l', '--label', '--label-file', '--name', '-p', '--publish', '--network', '--net',
+  '-w', '--workdir', '--entrypoint', '-u', '--user', '--platform', '--pull', '-h', '--hostname', '--cpus', '-m', '--memory', '--add-host', '--device', '--cap-add',
+  '--cap-drop', '--restart', '--log-driver', '--log-opt', '--security-opt', '--tmpfs', '--ulimit', '--gpus', '--shm-size', '--runtime', '--ipc', '--pid', '--uts',
+  '--userns', '--cgroupns', '--dns', '--expose', '--group-add', '--cidfile', '--stop-signal', '--stop-timeout', '--health-cmd', '--memory-swap', '--cpuset-cpus',
+])
+
+/** Group 5: what each MCP server runs or talks to, and what it is handed. */
+export function mcpChecks(ctx: ScanContext): CheckResult[] {
+  if (ctx.mcpServers.length === 0) return []
+  return [inventoryCheck(ctx.mcpServers), launchCheck(ctx.mcpServers), remoteCheck(ctx.mcpServers), credentialsCheck(ctx.mcpServers)]
+}
+
+function place(server: McpServer, excerpt: string, status: Status): Evidence {
+  return { file: server.file, line: server.line, excerpt: `${server.name}: ${excerpt}`, status }
+}
+
+function commandLine(server: McpServer): string {
+  return [server.command ?? '', ...server.args].join(' ').trim()
+}
+
+/**
+ * Every remote address a server talks to or is given: its own URL, and any
+ * address in its arguments (inside a shell script too), environment and
+ * headers. Local ones are left out. All are judged; the rows cap what they list.
+ */
+function remoteUrls(server: McpServer): { url: URL; given: boolean }[] {
+  const found: { url: URL; given: boolean }[] = []
+  const texts = [
+    ...(server.url === undefined ? [] : [{ text: server.url, given: false }]),
+    ...[...server.args, ...Object.values(server.env), ...Object.values(server.headers)].map(text => ({ text, given: true })),
+  ]
+  for (const { text, given } of texts) {
+    for (const match of text.matchAll(ADDRESS)) {
+      // Bounded work for a config written to exhaust it.
+      if (found.length >= 500) return found
+      try {
+        const url = new URL(match[0])
+        if (!isLocal(url.hostname)) found.push({ url, given })
+      } catch {
+        continue
+      }
+    }
+  }
+  return found
+}
+
+function isLocal(host: string): boolean {
+  return /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\]|::1|0\.0\.0\.0)$/i.test(host)
+}
+
+function inventoryCheck(servers: readonly McpServer[]): CheckResult {
+  const evidence = servers.map(server => {
+    const what = server.url !== undefined ? `${server.type ?? 'http'} server at ${server.url}` : `runs ${commandLine(server) || '(no command)'}`
+    const env = Object.keys(server.env)
+    return place(server, `${what}${env.length > 0 ? `; environment: ${env.slice(0, 10).join(', ')}` : ''}`, 'info')
+  })
+  return row(
+    {
+      id: 'mcp.servers',
+      group: GROUP,
+      title: 'MCP servers it adds',
+      advice: 'Each MCP server runs as a program on your machine or talks to a server elsewhere, and Claude can call every tool it offers.',
+    },
+    capEvidence(evidence, 30, 'info'),
+    'info',
+  )
+}
+
+function launchCheck(servers: readonly McpServer[]): CheckResult {
+  const evidence: Evidence[] = []
+  for (const server of servers) {
+    if (server.command === undefined) continue
+    const line = commandLine(server)
+    const program = baseName(server.command)
+    if (DOWNLOAD_AND_RUN.test(line)) {
+      evidence.push(place(server, `downloads code and runs it: ${line}`, 'fail'))
+      continue
+    }
+    if (UNPINNED_RUNNER.test(line)) {
+      evidence.push(place(server, `fetches a package that is not pinned to an exact version each time it starts: ${line}`, 'warn'))
+    } else if (/^(?:npx|bunx|pnpx|uvx|pipx|npm|pnpm|yarn|bun|deno)$/.test(program)) {
+      evidence.push(place(server, `fetches or runs a package when it starts; the package is not part of this scan: ${line}`, 'info'))
+    }
+    if (runsInlineScript(program, server.args)) evidence.push(place(server, `runs an inline shell script: ${line}`, 'warn'))
+    if (/^(?:docker|podman|nerdctl)$/.test(program) && server.args.includes('run')) {
+      const image = containerImage(server.args)
+      if (image === undefined) evidence.push(place(server, `runs a container whose image could not be told apart: ${line}`, 'warn'))
+      else if (!/@sha256:[0-9a-f]{64}$/.test(image)) evidence.push(place(server, `runs the container image ${image}, not pinned by digest`, 'warn'))
+    }
+  }
+  return row(
+    {
+      id: 'mcp.launch',
+      group: GROUP,
+      title: 'How each server starts',
+      advice: 'A server that downloads code when it starts runs whatever is published then, not what was scanned. Prefer an exact version or a digest.',
+    },
+    capEvidence(evidence, 30),
+  )
+}
+
+/** A shell given a script as text: -c (alone or with other letters, -ec), /c, -Command. */
+function runsInlineScript(program: string, args: readonly string[]): boolean {
+  if (/^(?:ba|z|da|k|fi)?sh$/.test(program)) return args.some(arg => /^-[A-Za-z]*c[A-Za-z]*$/.test(arg))
+  if (/^cmd(?:\.exe)?$/.test(program)) return args.some(arg => /^\/[ck]$/i.test(arg))
+  if (/^(?:powershell|pwsh)(?:\.exe)?$/.test(program)) return args.some(arg => /^-(?:c|command|e|ec|enc|encodedcommand)$/i.test(arg))
+  return false
+}
+
+/** The image a `docker run` starts: the first argument after `run` that is not an option or its value. */
+function containerImage(args: readonly string[]): string | undefined {
+  let index = args.indexOf('run') + 1
+  while (index < args.length) {
+    const arg = args[index] as string
+    if (arg === '--') return args[index + 1]
+    if (!arg.startsWith('-')) return arg
+    index += !arg.includes('=') && VALUE_FLAGS.has(arg) ? 2 : 1
+  }
+  return undefined
+}
+
+function remoteCheck(servers: readonly McpServer[]): CheckResult {
+  const evidence: Evidence[] = []
+  for (const server of servers) {
+    for (const { url, given } of remoteUrls(server)) {
+      const host = url.hostname.toLowerCase()
+      const via = given ? ' (an address in its configuration)' : ''
+      if (url.protocol === 'http:' || url.protocol === 'ws:') {
+        evidence.push(place(server, `talks to ${host}${via} without encryption`, 'fail'))
+      } else if (COLLECTION_HOST.test(`${host}${url.pathname}`)) {
+        evidence.push(place(server, `talks to ${host}${via}, a host often used to collect data`, 'fail'))
+      } else if (/^\d{1,3}(?:\.\d{1,3}){3}$|^\[/.test(host)) {
+        evidence.push(place(server, `talks to a raw IP address${via}: ${host}`, 'warn'))
+      } else {
+        evidence.push(place(server, `talks to a remote server${via}: ${host}`, 'warn'))
+      }
+    }
+  }
+  return row(
+    {
+      id: 'mcp.remote',
+      group: GROUP,
+      title: 'Remote servers',
+      advice: 'A remote server sees what Claude sends its tools and can change its tools at any time. Check that each host belongs to the publisher.',
+    },
+    capEvidence(evidence, 30),
+  )
+}
+
+function credentialsCheck(servers: readonly McpServer[]): CheckResult {
+  const evidence: Evidence[] = []
+  for (const server of servers) {
+    const urls = remoteUrls(server)
+    const line = commandLine(server)
+    const runner = server.command !== undefined && UNPINNED_RUNNER.test(line)
+    // A command that reads a credential file, and can send it somewhere.
+    if (server.command !== undefined && CREDENTIAL_PATH.test(line)) {
+      const sends = urls.length > 0 || NETWORK_COMMAND.test(line)
+      evidence.push(place(server, `${sends ? 'reads a credential file and talks to the network' : 'reads a credential file'}: ${line}`, sends ? 'fail' : 'warn'))
+    }
+    const handed = new Map<string, string>()
+    for (const [key, value] of [...Object.entries(server.env), ...Object.entries(server.headers)]) {
+      for (const name of referencedVariables(value)) handed.set(name, key)
+      if (SECRET_ENV.test(key)) handed.set(key, key)
+    }
+    for (const arg of server.args) for (const name of referencedVariables(arg)) if (!handed.has(name)) handed.set(name, 'its arguments')
+    for (const name of referencedVariables(server.url ?? '')) handed.set(name, 'url')
+    for (const [name, via] of handed) {
+      if (!SECRET_ENV.test(name)) continue
+      if (urls.length > 0) {
+        for (const { url } of urls) {
+          const host = url.hostname.toLowerCase()
+          evidence.push(
+            belongsTo(name, host)
+              ? place(server, `sends ${name} (in ${via}) to ${host}`, 'warn')
+              : place(server, `sends ${name} (in ${via}) to ${host}, which is not the service it belongs to`, 'fail'),
+          )
+        }
+      } else if (runner) {
+        evidence.push(place(server, `hands ${name} (in ${via}) to a package fetched when it starts, which this scan cannot read`, 'warn'))
+      } else {
+        evidence.push(place(server, `is given ${name} (in ${via})`, 'info'))
+      }
+    }
+  }
+  return row(
+    {
+      id: 'mcp.credentials',
+      group: GROUP,
+      title: 'Secrets given to servers',
+      advice: 'A server given a key can use it as you. A key sent to a host that is not its own service is a common way to steal it.',
+    },
+    capEvidence(evidence, 30),
+  )
+}
+
+function referencedVariables(text: string): string[] {
+  const names: string[] = []
+  for (const match of text.matchAll(ENV_REFERENCE)) {
+    const name = match[1] ?? match[2]
+    if (name !== undefined) names.push(name)
+  }
+  return names
+}
+
+/**
+ * Whether a key named `name` belongs on `host`: the host is one of its
+ * service's own domains or below one. For a service with no list, the
+ * service's word must be the host's own name (notion for mcp.notion.so), not
+ * any label: github.evil.example is evil.example's.
+ */
+function belongsTo(name: string, host: string): boolean {
+  const labels = host.split('.')
+  for (const word of vendorWords(name)) {
+    const domains = SERVICE_DOMAINS[word]
+    if (domains !== undefined) {
+      if (domains.some(domain => host === domain || host.endsWith(`.${domain}`))) return true
+    } else if (labels.length >= 2 && labels[labels.length - 2] === word) {
+      return true
+    }
+  }
+  return false
+}
+
+/** The words of a variable's name that name a service: GITHUB_TOKEN gives github. */
+function vendorWords(name: string): string[] {
+  return name
+    .toLowerCase()
+    .split('_')
+    .map(word => SERVICE_WORDS[word] ?? word)
+    .filter(word => word.length >= 3 && !GENERIC_WORDS.has(word))
+}
+
+function baseName(command: string): string {
+  return (command.split(/[\\/]/).pop() ?? command).toLowerCase()
+}