ai-install-guard 0.1.0 → 0.3.0

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

package/hooks/scan/checks/mod.ts

@@ -1,4 +1,6 @@
-import type { ModuleInfo, ModuleUse, ScanContext } from './context'
+import { isLive, type ModuleInfo, type ModuleUse, type ScanContext } from './context'
+import { describePrograms, type ProgramUse } from './programs'
+import { spanKinds } from './text'
 import { row, type CheckResult, type Evidence, type Status } from './types'
 import type { ValidatorReport } from './validator'
 
@@ -105,28 +107,23 @@ export function modChecks(ctx: ScanContext, validator: ValidatorReport | undefin
     ...dedupe(info.events).map(use => ({ use, kind: 'event' as const, capability: eventCapability(use) })),
     ...dedupe(info.calls).map(use => ({ use, kind: 'call' as const, capability: callCapability(use.name) })),
   ])
-  const explained = explanationsOf(ctx)
-  // The README must spell the call or event out as a name of its own; a wildcard is never explained.
-  const explainedCache = new Map<string, boolean>()
-  const isExplained = (name: string): boolean => {
-    const cached = explainedCache.get(name)
-    if (cached !== undefined) return cached
-    const answer = explains(name)
-    explainedCache.set(name, answer)
+  // A call is explained when the README (or the manifest's description)
+  // names it as a name of its own, not after a negation ("never calls
+  // process.run"), on a line or table row that says something about it: at
+  // least three words besides the name. A wildcard is never explained. The
+  // words are kept to quote beside the call, marked as the candidate's.
+  const sources: { where: Explanation['where']; text: string }[] = [
+    { where: 'README', text: (ctx.readme?.text ?? '').replace(/<!--[\s\S]{0,20000}?-->/g, ' ') },
+    { where: 'description', text: typeof ctx.manifest?.description === 'string' ? ctx.manifest.description : '' },
+  ]
+  const explanationCache = new Map<string, Explanation | undefined>()
+  const explanationFor = (name: string): Explanation | undefined => {
+    if (explanationCache.has(name)) return explanationCache.get(name)
+    const answer = findExplanation(name, sources)
+    explanationCache.set(name, answer)
     return answer
   }
-  const explains = (name: string): boolean => {
-    if (name.length < 5 || !/^[a-z]+\.[a-zA-Z.]+$/.test(name)) return false
-    const escaped = name.replace(/\./g, '\\.')
-    const mention = new RegExp(`(?<![\\w.$])${escaped}(?![\\w])`, 'gi')
-    // A mention right after a negation ("we never call process.run",
-    // "no process.run") says it does not use the call, so it explains nothing.
-    for (const found of explained.matchAll(mention)) {
-      const before = explained.slice(Math.max(0, (found.index ?? 0) - 40), found.index).split(/[.!?|\n]/).pop() ?? ''
-      if (!/\b(?:never|not|no|without|don['’]t|doesn['’]t|won['’]t|cannot|can['’]t)\b(?:\W+\w+){0,3}\W*$/i.test(before)) return true
-    }
-    return false
-  }
+  const isExplained = (name: string): boolean => explanationFor(name) !== undefined
 
   const inventory: Evidence[] = uses.map(({ use, kind, capability }) => ({
     file: use.file,
@@ -148,7 +145,8 @@ export function modChecks(ctx: ScanContext, validator: ValidatorReport | undefin
         status: explainedHere ? 'warn' : 'fail',
       })
     } else if (capability.risk === 'medium') {
-      medium.push({ file: use.file, line: use.line > 0 ? use.line : undefined, excerpt, status: 'warn' })
+      // Still a warning when explained: network access always deserves a look.
+      medium.push({ file: use.file, line: use.line > 0 ? use.line : undefined, excerpt: isExplained(use.name) ? `${excerpt} (the README names it)` : excerpt, status: 'warn' })
     }
   }
   const allCalls = new Set(modules.flatMap(info => info.calls.map(call => call.name)))
@@ -194,6 +192,7 @@ export function modChecks(ctx: ScanContext, validator: ValidatorReport | undefin
         group: GROUP,
         title: 'High-risk capabilities',
         advice: 'Running programs, writing files, deciding tool permissions, judging other plugins or changing the system prompt is what a mod needs to take over a session. Install only if its purpose needs it and its README says why.',
+        summary: capabilitySummary(uses.filter(item => item.capability.risk === 'high'), explanationFor, ctx, modules, allCalls.has('fs.read') && allCalls.has('http.fetch')),
       },
       high,
       'fail',
@@ -204,6 +203,7 @@ export function modChecks(ctx: ScanContext, validator: ValidatorReport | undefin
         group: GROUP,
         title: 'Network, environment and prompt access',
         advice: 'Check every address it talks to and every variable it reads against what it says it does.',
+        summary: capabilitySummary(uses.filter(item => item.capability.risk === 'medium'), explanationFor, ctx, modules, false),
       },
       medium,
     ),
@@ -250,17 +250,21 @@ function eventCapability(use: ModuleUse): Capability {
     if (SENSITIVE_COMMANDS.has(command)) return { risk: 'high', plain: `intercepts /${command}` }
     return { risk: 'low', plain: `answers /${command}` }
   }
+  // A tool hook narrowed to one tool is described as that tool's, still high risk.
+  if (use.name === 'tool.call' || use.name === 'tool.check') {
+    const tool = /\btool\s*:\s*['"`]([\w.-]{1,64})['"`]/.exec(use.detail ?? '')?.[1]
+    if (tool !== undefined) {
+      return use.name === 'tool.call'
+        ? { risk: 'high', plain: `sees every ${tool} call and can deny, rewrite or answer it` }
+        : { risk: 'high', plain: `decides whether ${tool} calls are allowed, so it can auto-approve them` }
+    }
+  }
   if (Object.hasOwn(EVENTS, use.name)) return EVENTS[use.name] as Capability
   const namespace = use.name.split('.')[0] ?? ''
   return Object.hasOwn(NAMESPACES, namespace) ? (NAMESPACES[namespace] as Capability) : { risk: 'low', plain: 'an event this scanner does not know' }
 }
 
 /** Lowercased names the README or description spells out, such as `process.run`. */
-function explanationsOf(ctx: ScanContext): string {
-  // Only what a reader sees: HTML comments are hidden when the README renders.
-  const visible = (ctx.readme?.text ?? '').replace(/<!--[\s\S]{0,20000}?-->/g, ' ')
-  return [visible, typeof ctx.manifest?.description === 'string' ? ctx.manifest.description : ''].join('\n\n').toLowerCase()
-}
 
 /** Adds what Claude Code's own validator saw and the source scan missed. */
 function withValidator(info: ModuleInfo, validator: ValidatorReport | undefined): ModuleInfo {
@@ -288,3 +292,92 @@ function dedupe(uses: readonly ModuleUse[]): ModuleUse[] {
 }
 
 export type { Status }
+
+/** Where a call is explained, and the words that explain it. */
+type Explanation = { where: 'README' | 'description'; quote: string }
+
+const NEGATION = /\b(?:never|not|no|without|don['’]t|doesn['’]t|won['’]t|cannot|can['’]t)\b(?:\W+\w+){0,3}\W*$/i
+
+function findExplanation(name: string, sources: readonly { where: Explanation['where']; text: string }[]): Explanation | undefined {
+  if (name.length < 5 || !/^[a-z]+\.[a-zA-Z.]+$/.test(name)) return undefined
+  const escaped = name.replace(/\./g, '\\.')
+  const mentions = new RegExp(`(?<![\\w.$])${escaped}(?![\\w])`, 'gi')
+  const mention = new RegExp(`(?<![\\w.$])${escaped}(?![\\w])`, 'i')
+  for (const { where, text } of sources) {
+    for (const line of text.split('\n')) {
+      for (const found of line.matchAll(mentions)) {
+        const index = found.index ?? 0
+        const before = line.slice(Math.max(0, index - 40), index).split(/[.!?|]/).pop() ?? ''
+        if (NEGATION.test(before)) continue
+        // A table row: every cell but the one that is only the call's name;
+        // a reason cell that repeats the name is still the reason.
+        const cells = line.trim().startsWith('|') ? line.split('|').map(cell => cell.trim()).filter(cell => cell !== '' && !/^:?-+:?$/.test(cell)) : [line]
+        const plain = (text: string) => text.replace(/[`*_]/g, '').replace(/\s+/g, ' ').trim()
+        const words = cells.filter(cell => plain(cell).toLowerCase() !== name.toLowerCase()).map(plain).join(' ')
+        const said = plain((cells.length > 1 ? words : line).replace(mentions, ''))
+        if ((said.match(/[A-Za-z]{3,}/g) ?? []).length < 3) continue
+        const quote = cells.length > 1 ? words : line.replace(/[`*_]/g, '').replace(/\s+/g, ' ').trim()
+        return { where, quote: quote.length > 220 ? `${quote.slice(0, 219)}…` : quote }
+      }
+    }
+  }
+  return undefined
+}
+
+/**
+ * A capability row in plain words: what the mod can do and whether its
+ * README says why, the README's own words for it (marked as the
+ * candidate's), then the programs it starts when it runs any.
+ */
+function capabilitySummary(
+  uses: readonly { use: ModuleUse; kind: 'event' | 'call'; capability: Capability }[],
+  explanationFor: (name: string) => Explanation | undefined,
+  ctx: ScanContext,
+  modules: readonly ModuleInfo[],
+  readsAndSends: boolean,
+): string[] | undefined {
+  const names = [...new Set(uses.map(item => item.use.name))]
+  if (names.length === 0) return undefined
+  const plain = [...new Set(uses.map(item => item.capability.plain))]
+  const told = names.every(name => explanationFor(name) !== undefined)
+  const lines = [`${plain.join('; ').replace(/^./, char => char.toUpperCase())}${told ? '; its README says why' : '; its README does not say why'}`]
+  if (readsAndSends) lines.push('Reads files and sends requests, so it could send your files out')
+  // The reasons come before the program list, so a long list cannot push them out of view.
+  for (const name of names.slice(0, 2)) {
+    const explanation = explanationFor(name)
+    if (explanation !== undefined) lines.push(`${explanation.where === 'README' ? 'The README says' : 'Its description says'} about ${name} (its words, not checked): "${explanation.quote}"`)
+  }
+  // Programs only for a mod that calls processes itself; hooking another's
+  // process.run starts nothing.
+  if (uses.some(item => item.kind === 'call' && /^process(?:\.|$)/.test(item.use.name))) {
+    // Only the modules that reach for processes, and the files they import.
+    const files = new Set(modules.filter(info => info.calls.some(call => /^process(?:\.|$)/.test(call.name))).flatMap(info => [info.entry, ...info.files]))
+    const described = describePrograms(programsOfModule(ctx, files), { buildsCode: 0, downloads: 0 }).filter(line => !line.startsWith('In '))
+    lines.push(...(described.length > 0 ? described.slice(0, 4) : ['Which programs it starts could not be read from its code']))
+  }
+  return lines
+}
+
+/**
+ * The programs a mod's own files start with a literal name, as in
+ * `.run(['git', ...])` or `['run'](['git'])`, outside comments, patterns and
+ * strings. A name built while it runs (`${tool}`) is a program chosen then.
+ */
+function programsOfModule(ctx: ScanContext, files: ReadonlySet<string>): ProgramUse[] {
+  const uses: ProgramUse[] = []
+  for (const path of files) {
+    if (!/\.(?:[cm]?[jt]sx?)$/.test(path)) continue
+    const text = ctx.text(path)
+    if (text === undefined) continue
+    const kindAt = spanKinds(text, 'js')
+    for (const match of text.matchAll(/(?:\.(?:run|spawn)|\[\s*(["'])(?:run|spawn)\1\s*\])\s*\(\s*\[\s*(["'`])([^"'`\s]{1,100})\2/g)) {
+      const kind = kindAt(match.index ?? 0)
+      if (kind !== 'code') continue
+      const raw = match[3] as string
+      const dynamic = match[2] === '`' && raw.includes('${')
+      uses.push({ name: dynamic ? raw.slice(0, 60) : (raw.split(/[\\/]/).pop() ?? '').replace(/\.exe$/i, '').toLowerCase(), file: path, dynamic })
+      if (uses.length >= 500) return uses
+    }
+  }
+  return uses
+}

package/hooks/scan/checks/patterns.ts

@@ -13,19 +13,20 @@ export const DOWNLOAD_AND_RUN =
   /\b(?:curl|wget)\b[^\n|]{0,500}\|\s*(?:sudo\s+)?(?:\/[\w.\/-]*\/)?(?:env\s+)?(?:ba|z|da|k)?sh\b|\b(?:curl|wget)\b[^\n|]{0,500}\|\s*(?:sudo\s+)?(?:\/[\w.\/-]*\/)?(?:env\s+)?(?:python[23]?|node|perl|ruby|php)\b|\b(?:ba|z)?sh\s+-c\s+["']?\$\(\s*(?:curl|wget)|(?:\b(?:source|(?:ba|z|da|k)?sh)|(?:^|(?<=[\s;&|(]))\.)\s+<\(\s*(?:curl|wget)|\bbase64\s+(?:-d|--decode|-D)\b[^\n|]{0,500}\|\s*(?:sudo\s+)?(?:\/[\w.\/-]*\/)?(?:env\s+)?(?:ba|z|da)?sh\b|\bpython[23]?\s+-c\s+["'][^"'\n]{0,500}urllib|\beval\s+["']?\$\(\s*(?:curl|wget|echo|base64)/
 
 /**
- * Fetching and running a package that is not pinned to an exact version:
+ * Fetching and running a package that is not pinned to an exact version
+ * (npx, npm exec, pnpm dlx, yarn dlx, bunx, uvx, pipx run):
  * no version, a tag (@latest, @next) or a range (@^1.2) all count. An exact
  * x.y.z, with any prerelease (-rc-1) or build (+5) part, is a pin.
  */
 export const UNPINNED_RUNNER =
-  /\b(?:npx|bunx|pnpx)\s+(?:-{1,2}[\w-]+\s+){0,5}(?!-)(?:@[\w.-]+\/)?[\w.-]+(?:@(?!\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?(?![\w.+-]))[^\s`'"();&|]*)?(?![@\w./-])|\b(?:uvx|pipx\s+run)\s+(?!\S+(?:==|@)\d)/
+  /\b(?:npx|bunx|pnpx|npm\s+exec|pnpm\s+dlx|yarn\s+dlx|bun\s+x)\s+(?:-{1,2}[\w-]+(?:=\S+)?\s+){0,5}(?!-)(?:@[\w.-]+\/)?[\w.-]+(?:@(?!\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?(?![\w.+-]))[^\s`'"();&|]*)?(?![@\w./-])|\b(?:uvx|pipx\s+run)\s+(?!\S+(?:==|@)\d)/
 
 /** Shell `eval` and piping into a shell. */
 export const SHELL_EVAL = /(?:^|[\s;&|(])eval\s|\|\s*(?:sudo\s+)?(?:\/[\w.\/-]*\/)?(?:env\s+)?(?:ba|z|da|k)?sh\s*(?:$|[;&|)])/m
 
 /** Places that hold credentials. */
 export const CREDENTIAL_PATH =
-  /\.ssh(?:\/|\b)|\bid_(?:rsa|dsa|ecdsa|ed25519)\b|\.aws\/(?:credentials|config)\b|\.(?:netrc|git-credentials|pypirc)\b|\.npmrc\b|\.docker\/config\.json|\.kube\/config\b|\.config\/gh\/hosts|\.gnupg\b|\.claude\/\.credentials|Library\/Keychains|\bsecurity\s+(?:find|dump)-(?:generic|internet)-password|\bdump-keychain\b|\bLogin Data\b|Cookies\.binarycookies|\/Google\/Chrome\/|\.mozilla\/firefox|BraveSoftware|Microsoft\/Edge\//
+  /\.ssh(?:\/|\b)|\bid_(?:rsa|dsa|ecdsa|ed25519)\b|\.aws\/(?:credentials|config)\b|\.(?:netrc|git-credentials|pypirc)\b|\.npmrc\b|\.docker\/config\.json|\.kube\/config\b|\.config\/gh\/hosts|\.gnupg\b|\.claude\/\.credentials|Library\/Keychains|\bsecurity\s+(?:find|dump)-(?:generic|internet)-password|\bdump-keychain\b|\bLogin Data\b|Cookies\.binarycookies|(?:Application Support|\.config)\/(?:Google\/Chrome|google-chrome|chromium|BraveSoftware|Microsoft Edge)\b|\/(?:Google\/Chrome|Chromium|BraveSoftware\/Brave-Browser|Microsoft\/Edge)\/User Data\b|\.mozilla\/firefox/
 
 /** Environment variables that hold secrets, and dumps of the whole environment. */
 export const SECRET_ENV =

package/hooks/scan/checks/programs.ts

@@ -0,0 +1,150 @@
+// Turns "this code runs programs" into what a person can judge: which
+// programs, what each one is for, and which deserve a closer look.
+
+/** One place code starts a program. `dynamic` when the program is a variable. */
+export type ProgramUse = { name: string; file: string; dynamic: boolean }
+
+type Kind = { label: string; risky: boolean }
+
+// Written as patterns, which the guard's own scan reads as inert, not as
+// names of tools it runs.
+// Written as patterns with an escape, which the guard's own scan reads as
+// inert rather than as names of tools it runs.
+const KINDS: readonly { match: RegExp; kind: Kind }[] = [
+  { match: /^(?:sh|bash|zsh|dash|ksh|fish|csh|tcsh|cmd|powershell|pwsh)(?:\.exe)?$/, kind: { label: 'a shell, which can run any command', risky: true } },
+  { match: /^(?:swiftc|swift|gcc|g\+\+|clang|clang\+\+|cc|c\+\+|rustc|cargo|go|javac|make|cmake|tsc|esbuild)(?:\.exe)?$/, kind: { label: 'builds code, which can then run', risky: true } },
+  { match: /^(?:node|python|python3|deno|bun|ruby|perl|php|java)(?:\.exe)?$/, kind: { label: 'runs other scripts', risky: false } },
+  { match: /^(?:curl|wget|ssh|scp|sftp|rsync|nc|ncat|netcat|socat|ftp|telnet)(?:\.exe)?$/, kind: { label: 'talks to the network', risky: true } },
+  { match: /^(?:npm|npx|pnpm|pnpx|yarn|bunx|pip|pip3|pipx|uv|uvx|brew|apt|apt-get|gem)(?:\.exe)?$/, kind: { label: 'installs or fetches packages', risky: true } },
+  { match: /^(?:sudo|doas|su)(?:\.exe)?$/, kind: { label: 'runs as administrator', risky: true } },
+  { match: /^(?:security)(?:\.exe)?$/, kind: { label: 'reads the macOS keychain', risky: true } },
+  { match: /^(?:osascript)(?:\.exe)?$/, kind: { label: 'controls other apps', risky: true } },
+  { match: /^(?:launchctl|systemctl|crontab|schtasks)(?:\.exe)?$/, kind: { label: 'sets up background jobs', risky: true } },
+  { match: /^(?:ffmpeg|ffprobe|ffplay|sox|magick|convert|identify|exiftool|gm|vips)(?:\.exe)?$/, kind: { label: 'video, audio and image tools', risky: false } },
+  { match: /^(?:whisper|whisper-cli|whisper-cpp)(?:\.exe)?$/, kind: { label: 'speech to text', risky: false } },
+  { match: /^(?:git|gh)(?:\.exe)?$/, kind: { label: 'git', risky: false } },
+  { match: /^(?:rm|rmdir|del|shred)(?:\.exe)?$/, kind: { label: 'deletes files', risky: false } },
+  {
+    match: /^(?:cp|mv|mkdir|chmod|chown|ln|tar|unzip|zip|gzip|gunzip|touch|cat|ls|find|xargs|sed|awk|grep|head|tail|sort|which|du|df)$/,
+    kind: { label: 'file housekeeping', risky: false },
+  },
+  { match: /^(?:open|xdg-open|start|explorer)(?:\.exe)?$/, kind: { label: 'opens files or links', risky: false } },
+  { match: /^(?:chrome|google-chrome|chromium|chromium-browser|firefox|playwright)(?:\.exe)?$/, kind: { label: 'a web browser', risky: false } },
+]
+
+const KIND_OF = { get: (name: string): Kind | undefined => KINDS.find(entry => entry.match.test(name))?.kind }
+
+const JS_CALLS =
+  /(?<![\w$.])(?:execFileSync|execFile|spawnSync|spawn|execSync|exec|fork)\s*\(\s*(?:(["'`])([^"'`\n]{1,200})|([A-Za-z_$][\w$.]{0,80}))|\b(?:child_process|childProcess|cp)\.(execFileSync|execFile|spawnSync|spawn|execSync|exec|fork)\s*\(\s*(?:(["'`])([^"'`\n]{1,200})|([A-Za-z_$][\w$.]{0,80}))|\bBun\.spawn(?:Sync)?\s*\(\s*\[\s*(["'`])([^"'`\n]{1,200})|\bnew\s+Deno\.Command\s*\(\s*(["'`])([^"'`\n]{1,200})|\bDeno\.run\s*\(\s*\{\s*cmd\s*:\s*\[\s*(["'`])([^"'`\n]{1,200})/g
+
+const PY_CALLS =
+  /\bsubprocess\.(?:run|call|Popen|check_output|check_call|getoutput|getstatusoutput)\s*\(\s*(?:\[\s*[rbfu]?(["'])([^"'\n]{1,200})|\[\s*([A-Za-z_][\w.]{0,80})|[rbfu]?(["'])([^"'\n]{1,200})|([A-Za-z_][\w.]{0,80}))|\bos\.(?:system|popen)\s*\(\s*[rbfu]?(["'])([^"'\n]{1,200})|\bpty\.spawn\s*\(\s*(?:\[\s*)?[rbfu]?(["'])([^"'\n]{1,200})|\bos\.(?:spawn|exec)[a-z]{0,4}\s*\(\s*(?:os\.P_\w+\s*,\s*)?(?:[rbfu]?(["'])([^"'\n]{1,200})|([A-Za-z_][\w.]{0,80}))/g
+
+/** The programs a file starts, from its calls; `keep` drops matches in comments. */
+export function programsIn(path: string, text: string, language: 'js' | 'python' | 'shell' | 'other', keep: (index: number) => boolean): ProgramUse[] {
+  const uses: ProgramUse[] = []
+  const patterns = language === 'js' ? [JS_CALLS] : language === 'python' ? [PY_CALLS] : language === 'shell' ? [] : [JS_CALLS, PY_CALLS]
+  for (const pattern of patterns) {
+    for (const match of text.matchAll(new RegExp(pattern.source, pattern.flags))) {
+      if (uses.length >= 500) return uses
+      const index = match.index ?? 0
+      if (!keep(index)) continue
+      const groups = match.slice(1)
+      // The literal is the group after a quote; a variable has no quote before it.
+      let literal: string | undefined
+      let variable: string | undefined
+      for (let i = 0; i < groups.length; i += 1) {
+        const value = groups[i]
+        if (value === undefined) continue
+        if (/^["'`]$/.test(value)) {
+          literal = groups[i + 1]
+          break
+        }
+        if (/^(?:execFileSync|execFile|spawnSync|spawn|execSync|exec|fork)$/.test(value)) continue
+        variable = value
+        break
+      }
+      if (literal !== undefined) {
+        // A shell command line (execSync, os.system, a string to subprocess)
+        // starts with its program; a list or execFile names the program alone.
+        const call = /(\w+)\s*\(\s*\[?\s*[rbfu]?["'`]?$/.exec(match[0].slice(0, match[0].length - literal.length))?.[1] ?? ''
+        const listForm = /\(\s*\[/.test(match[0])
+        const isLine = !listForm && (/^(?:execSync|exec|system|popen|getoutput|getstatusoutput)$/.test(call) || match[0].startsWith('subprocess.'))
+        const raw = (isLine ? literal.trim().split(/\s+/)[0] : literal) ?? ''
+        // A name built while it runs (`${tool}`, f"{tool}") is a program chosen at run time.
+        const fString = /[^\w]f["']$|^f["']/.test(match[0].slice(0, match[0].length - literal.length).slice(-2))
+        if (raw.includes('${') || (fString && raw.includes('{'))) {
+          uses.push({ name: raw.slice(0, 60), file: path, dynamic: true })
+          continue
+        }
+        const name = normalise(raw)
+        if (name !== '') uses.push({ name, file: path, dynamic: false })
+      } else if (variable !== undefined) {
+        // The running interpreter itself is node or python, not an unknown program.
+        const itself = variable === 'process.execPath' ? 'node' : variable === 'sys.executable' ? 'python' : undefined
+        uses.push({ name: itself ?? variable, file: path, dynamic: itself === undefined })
+      }
+    }
+  }
+  return uses
+}
+
+function normalise(program: string): string {
+  const base = program.replace(/^["']|["']$/g, '').split(/[\\/]/).pop() ?? ''
+  return base.replace(/\.exe$/i, '').toLowerCase().slice(0, 60)
+}
+
+function plural(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? '' : 's'}`
+}
+
+/**
+ * The plain-language lines for a row about running programs: a headline, then
+ * the programs worth a look, then the rest by what they are for.
+ */
+export function describePrograms(uses: readonly ProgramUse[], extra: { buildsCode: number; downloads: number }): string[] {
+  const counts = new Map<string, number>()
+  const files = new Set<string>()
+  const dynamic = new Map<string, number>()
+  for (const use of uses) {
+    files.add(use.file)
+    if (use.dynamic) dynamic.set(use.name, (dynamic.get(use.name) ?? 0) + 1)
+    else counts.set(use.name, (counts.get(use.name) ?? 0) + 1)
+  }
+  const byCount = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+  const risky = byCount.filter(([name]) => KIND_OF.get(name)?.risky === true)
+  const ordered = [...risky, ...byCount.filter(([name]) => KIND_OF.get(name)?.risky !== true)]
+
+  const parts: string[] = []
+  if (extra.downloads > 0) parts.push('downloads code and runs it')
+  if (extra.buildsCode > 0) parts.push('builds code from text and runs it')
+  if (ordered.length > 0) {
+    const names = ordered.slice(0, 6).map(([name]) => name)
+    parts.push(`starts ${names.join(', ')}${ordered.length > 6 ? ` and ${ordered.length - 6} more` : ''}`)
+  }
+  if (dynamic.size > 0) parts.push('starts programs chosen while it runs')
+  if (parts.length === 0) return []
+  const headline = parts.join('; ')
+  const lines = [headline.charAt(0).toUpperCase() + headline.slice(1)]
+
+  const lookAt: string[] = []
+  if (extra.downloads > 0) lookAt.push(`downloads code and runs it (${plural(extra.downloads, 'place')})`)
+  if (extra.buildsCode > 0) lookAt.push(`builds code from text and runs it, as eval does (${plural(extra.buildsCode, 'place')})`)
+  for (const [name, count] of risky) lookAt.push(`${name}: ${KIND_OF.get(name)?.label} (${plural(count, 'place')})`)
+  if (dynamic.size > 0) lookAt.push(`a program named by ${[...dynamic.keys()].slice(0, 4).join(', ')}, chosen while it runs (${plural([...dynamic.values()].reduce((a, b) => a + b, 0), 'place')})`)
+  if (lookAt.length > 0) lines.push(`Worth a look: ${lookAt.join('; ')}`)
+
+  const groups = new Map<string, string[]>()
+  for (const [name, count] of byCount) {
+    const kind = KIND_OF.get(name)
+    if (kind?.risky === true) continue
+    const label = kind?.label ?? 'other programs'
+    groups.set(label, [...(groups.get(label) ?? []), `${name} (${count})`])
+  }
+  for (const [label, names] of groups) lines.push(`${label.charAt(0).toUpperCase()}${label.slice(1)}: ${names.join(', ')}`)
+  if (files.size > 0) {
+    const list = [...files].sort()
+    lines.push(`In ${plural(list.length, 'file')}: ${list.slice(0, 4).join(', ')}${list.length > 4 ? ` and ${list.length - 4} more` : ''}`)
+  }
+  return lines
+}