ai-install-guard 0.0.0 → 0.2.0

package/hooks/scan/checks/mod.ts

@@ -0,0 +1,374 @@
+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'
+
+const GROUP = 'mod' as const
+
+type Risk = 'high' | 'medium' | 'low'
+
+type Capability = { risk: Risk; plain: string }
+
+/** What each `$` call lets a mod do, by `noun.method`, then by `noun.*`. */
+const CALLS: Record<string, Capability> = {
+  'process.run': { risk: 'high', plain: 'runs programs on your machine' },
+  'process.spawn': { risk: 'high', plain: 'starts programs on your machine and streams their output' },
+  'fs.write': { risk: 'high', plain: 'writes files anywhere it can reach' },
+  'fs.read': { risk: 'low', plain: 'reads files' },
+  'fs.list': { risk: 'low', plain: 'lists folders' },
+  'fs.stat': { risk: 'low', plain: 'looks up files' },
+  'fs.exists': { risk: 'low', plain: 'checks whether files exist' },
+  'fs.ancestors': { risk: 'low', plain: 'looks for files in parent folders' },
+  'http.fetch': { risk: 'medium', plain: 'sends requests over the network' },
+  'env.get': { risk: 'medium', plain: 'reads environment variables' },
+  'env.set': { risk: 'medium', plain: 'sets environment variables for the session' },
+  'model.complete': { risk: 'medium', plain: 'calls the model on your account' },
+  'model.fork': { risk: 'medium', plain: 'asks the model about the whole conversation' },
+  'agent.spawn': { risk: 'medium', plain: 'starts subagents' },
+  'agent.register': { risk: 'low', plain: 'adds a subagent type' },
+  'tool.call': { risk: 'medium', plain: 'calls tools itself (Bash, Write, ...)' },
+  'tool.register': { risk: 'low', plain: 'adds a tool the model can call' },
+  'prompt.submit': { risk: 'medium', plain: 'sends prompts as if you typed them' },
+  'prompt.fill': { risk: 'low', plain: 'types into your prompt box' },
+  'command.run': { risk: 'medium', plain: 'runs slash commands, which can include /plugin' },
+  'command.register': { risk: 'low', plain: 'adds a slash command' },
+  'config.set': { risk: 'high', plain: 'changes your settings' },
+  'settings.write': { risk: 'high', plain: 'changes your settings' },
+  'settings.read': { risk: 'medium', plain: 'reads your settings' },
+  'session.append': { risk: 'medium', plain: 'adds messages the model reads' },
+  'session.messages': { risk: 'medium', plain: 'reads the conversation' },
+  'store.get': { risk: 'low', plain: 'reads its own saved data' },
+  'store.set': { risk: 'low', plain: 'saves its own data' },
+  'store.delete': { risk: 'low', plain: 'deletes its own saved data' },
+  'store.keys': { risk: 'low', plain: 'lists its own saved data' },
+  'state.get': { risk: 'low', plain: 'reads session values' },
+  'state.set': { risk: 'low', plain: 'sets its own session values' },
+}
+
+const NOUNS: Record<string, Capability> = {
+  process: { risk: 'high', plain: 'runs programs' },
+  fs: { risk: 'low', plain: 'uses the file system' },
+  http: { risk: 'medium', plain: 'uses the network' },
+  env: { risk: 'medium', plain: 'uses environment variables' },
+  model: { risk: 'medium', plain: 'calls the model' },
+  settings: { risk: 'medium', plain: 'uses your settings' },
+  config: { risk: 'medium', plain: 'uses your settings' },
+  ui: { risk: 'low', plain: 'draws in the interface' },
+  clock: { risk: 'low', plain: 'uses timers' },
+  audio: { risk: 'low', plain: 'plays sounds' },
+  store: { risk: 'low', plain: 'keeps its own data' },
+  state: { risk: 'low', plain: 'keeps session values' },
+  session: { risk: 'low', plain: 'reads session details' },
+  plugin: { risk: 'low', plain: 'reads its own plugin details' },
+}
+
+/** What hooking each event lets a mod do. */
+const EVENTS: Record<string, Capability> = {
+  'tool.call': { risk: 'high', plain: 'sees every tool call and can deny, rewrite or answer it' },
+  'tool.check': { risk: 'high', plain: 'decides whether tool calls are allowed, so it can auto-approve them' },
+  'plugin.register': { risk: 'high', plain: 'judges other plugins as they load and can refuse them' },
+  'prompt.compose': { risk: 'high', plain: 'changes the system prompt' },
+  '*': { risk: 'high', plain: 'hooks every event' },
+  'prompt.submit': { risk: 'medium', plain: 'sees and can rewrite every prompt you send' },
+  'prompt.mention': { risk: 'medium', plain: 'sees and can rewrite @-mentions' },
+  'tool.describe': { risk: 'medium', plain: 'rewrites the tool descriptions the model reads' },
+  'session.append': { risk: 'medium', plain: 'sees and can rewrite every message the conversation keeps' },
+  'session.receive': { risk: 'medium', plain: 'sees and can drop messages delivered to the session' },
+  'skill.prompt': { risk: 'medium', plain: 'rewrites skill prompts' },
+  'config.set': { risk: 'medium', plain: 'can block or change settings changes' },
+  'agent.offer': { risk: 'low', plain: 'decides which subagent types the model sees' },
+  'session.start': { risk: 'low', plain: 'runs when a session starts' },
+  'session.end': { risk: 'low', plain: 'runs when a session ends' },
+  'ui.render': { risk: 'low', plain: 'draws in the interface' },
+  'ui.press': { risk: 'low', plain: 'reacts to its own buttons' },
+}
+
+const NAMESPACES: Record<string, Capability> = {
+  classic: { risk: 'medium', plain: 'sees classic hook events' },
+  telemetry: { risk: 'medium', plain: 'sees telemetry' },
+  turn: { risk: 'low', plain: 'follows each turn' },
+  ui: { risk: 'low', plain: 'draws in the interface' },
+  fs: { risk: 'medium', plain: "sees and can change other plugins' file access" },
+  process: { risk: 'medium', plain: "sees and can change other plugins' processes" },
+  http: { risk: 'medium', plain: "sees and can change other plugins' network calls" },
+  model: { risk: 'medium', plain: "sees and can change other plugins' model calls" },
+}
+
+/** Built-in commands whose interception matters: installs, settings, permissions. */
+const SENSITIVE_COMMANDS = new Set(['plugin', 'plugins', 'config', 'permissions', 'mcp', 'hooks', 'login', 'logout', 'model', 'agents', 'memory', 'install', 'sandbox'])
+
+const COSMETIC = /\b(?:themes?|colou?r(?:s|ful|scheme)?|palette|fonts?|status ?line|statusline|spinners?|banners?|emoji|appearance|cosmetic|look and feel|sounds?|animations?|ascii art|greetings?|quotes? of the day|fortune|wallpaper|decorat\w*)\b/i
+
+export function modChecks(ctx: ScanContext, validator: ValidatorReport | undefined): CheckResult[] {
+  if (ctx.modules.length === 0) return []
+  const modules = ctx.modules.map(info => withValidator(info, validator))
+  const uses = modules.flatMap(info => [
+    ...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) })),
+  ])
+  // 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 isExplained = (name: string): boolean => explanationFor(name) !== undefined
+
+  const inventory: Evidence[] = uses.map(({ use, kind, capability }) => ({
+    file: use.file,
+    line: use.line > 0 ? use.line : undefined,
+    excerpt: `${kind === 'event' ? 'hooks' : 'calls'} ${use.name}${use.detail === undefined ? '' : ` ${use.detail}`}: ${capability.plain}`,
+    status: 'info',
+  }))
+
+  const high: Evidence[] = []
+  const medium: Evidence[] = []
+  for (const { use, kind, capability } of uses) {
+    const excerpt = `${kind === 'event' ? 'hooks' : 'calls'} ${use.name}: ${capability.plain}`
+    if (capability.risk === 'high') {
+      const explainedHere = isExplained(use.name)
+      high.push({
+        file: use.file,
+        line: use.line > 0 ? use.line : undefined,
+        excerpt: explainedHere ? `${excerpt} (the README names it)` : excerpt,
+        status: explainedHere ? 'warn' : 'fail',
+      })
+    } else if (capability.risk === 'medium') {
+      // 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)))
+  if (allCalls.has('fs.read') && allCalls.has('http.fetch')) {
+    const explainedHere = isExplained('http.fetch') && isExplained('fs.read')
+    high.push({
+      file: modules[0]?.entry ?? '-',
+      excerpt: `reads files and sends requests: it can send your files out${explainedHere ? ' (the README names both)' : ''}`,
+      status: explainedHere ? 'warn' : 'fail',
+    })
+  }
+  for (const info of modules) {
+    for (const url of dedupe(info.urls)) medium.push({ file: url.file, line: url.line, excerpt: `network address in the module: ${url.name}`, status: 'info' })
+    for (const name of dedupe(info.envNames)) medium.push({ file: name.file, line: name.line, excerpt: `reads the environment variable ${name.name}`, status: 'warn' })
+  }
+
+  const description = [ctx.manifest?.description, ctx.manifest?.name, proseOf(ctx.readme?.text ?? '').slice(0, 800)].filter(item => typeof item === 'string').join('\n')
+  const cosmetic = COSMETIC.exec(description)
+  const strongest = uses.find(item => item.capability.risk === 'high')
+  const mismatch: Evidence[] =
+    cosmetic !== null && strongest !== undefined
+      ? [{
+          file: strongest.use.file,
+          line: strongest.use.line > 0 ? strongest.use.line : undefined,
+          excerpt: `describes itself as "${cosmetic[0]}" but ${strongest.kind === 'event' ? 'hooks' : 'calls'} ${strongest.use.name}`,
+          status: 'fail',
+        }]
+      : []
+
+  return [
+    {
+      id: 'mod.uses',
+      group: GROUP,
+      title: 'Events it hooks and calls it makes',
+      status: 'info',
+      severity: 'none',
+      evidence: inventory,
+      advice: 'This is everything the mod can do through Claude Code. Compare it with what it says it does.',
+    },
+    row(
+      {
+        id: 'mod.high-risk',
+        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',
+    ),
+    row(
+      {
+        id: 'mod.medium-risk',
+        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,
+    ),
+    row(
+      {
+        id: 'mod.mismatch',
+        group: GROUP,
+        title: 'Capabilities match its description',
+        advice: 'A cosmetic mod has no reason to run programs or decide permissions. Treat the mismatch as hostile.',
+      },
+      mismatch,
+      'fail',
+    ),
+  ]
+}
+
+/** A README's prose: no code, links, images, badges, HTML or URLs. */
+function proseOf(markdown: string): string {
+  return markdown
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ')
+    .replace(/<[^>\n]+>/g, ' ')
+    .replace(/!?\[([^\]\n]*)\]\([^)\n]*\)/g, (_, label: string) => (label.includes('[') ? ' ' : label))
+    .replace(/\bhttps?:\/\/\S+/g, ' ')
+}
+
+function callCapability(name: string): Capability {
+  if (name.endsWith('.*')) {
+    // The noun kept whole, its methods called later: judged by its riskiest one.
+    const noun = name.slice(0, -2)
+    const methods = Object.entries(CALLS).filter(([key]) => key.startsWith(`${noun}.`)).map(([, value]) => value)
+    const worst = methods.find(item => item.risk === 'high') ?? methods.find(item => item.risk === 'medium') ?? methods[0]
+    if (worst !== undefined) return { risk: worst.risk, plain: `keeps $.${noun} to call later: ${worst.plain}` }
+  }
+  if (Object.hasOwn(CALLS, name)) return CALLS[name] as Capability
+  const noun = name.split('.')[0] ?? ''
+  return Object.hasOwn(NOUNS, noun) ? (NOUNS[noun] as Capability) : { risk: 'low', plain: 'a call this scanner does not know' }
+}
+
+function eventCapability(use: ModuleUse): Capability {
+  if (use.name === 'command.run') {
+    const command = /command\s*:\s*['"`]([^'"`]+)['"`]/.exec(use.detail ?? '')?.[1]
+    if (command === undefined) return { risk: 'high', plain: 'sees and can answer every slash command, /plugin included' }
+    if (SENSITIVE_COMMANDS.has(command)) return { risk: 'high', plain: `intercepts /${command}` }
+    return { risk: 'low', plain: `answers /${command}` }
+  }
+  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`. */
+
+/** Adds what Claude Code's own validator saw and the source scan missed. */
+function withValidator(info: ModuleInfo, validator: ValidatorReport | undefined): ModuleInfo {
+  if (validator?.ran !== true) return info
+  const normalize = (path: string): string => path.replace(/^\.\//, '')
+  const report = validator.modules.find(item => normalize(item.module) === normalize(info.declaredAs))
+  if (report === undefined) return info
+  const known = new Set([...info.events.map(use => use.name), ...info.calls.map(use => use.name)])
+  const extra = (names: string[]): ModuleUse[] =>
+    names
+      .map(name => name.replace(/\{.*\}$/, ''))
+      .filter(name => !known.has(name))
+      .map(name => ({ name, file: info.entry, line: 0 }))
+  return { ...info, events: [...info.events, ...extra(report.hooks)], calls: [...info.calls, ...extra(report.calls)] }
+}
+
+function dedupe(uses: readonly ModuleUse[]): ModuleUse[] {
+  const seen = new Set<string>()
+  return uses.filter(use => {
+    const key = `${use.name}|${use.detail ?? ''}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+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

@@ -0,0 +1,107 @@
+// Detection patterns shared by the checks. They are written as escaped
+// regular expressions so the guard's own source does not match its rules.
+
+/** A network tool at the start of a shell command or after a separator. */
+export const NETWORK_COMMAND = /(?:^|[\s;&|(`'"])(?:curl|wget|nc|ncat|netcat|socat|telnet|ssh|scp|sftp|rsync|ftp|tftp|nslookup)(?=\s|$)/
+
+/** Network access in source code. */
+export const NETWORK_CODE =
+  /\bfetch\s*\(|\bXMLHttpRequest\b|\bhttps?\.(?:request|get)\s*\(|\brequire\s*\(\s*['"](?:node:)?(?:http|https|net|dgram|tls|dns)['"]\s*\)|\bfrom\s+['"](?:node:)?(?:http|https|net|dgram|tls|dns)['"]|\baxios\b|\bundici\b|\brequests\.(?:get|post|put|patch|request|Session)\b|\burllib\b|\bhttpx\b|\bsocket\.(?:socket|create_connection)\b|\bnew\s+WebSocket\b|\$\s*\.\s*http\s*\.\s*fetch\b|\bdns\.(?:lookup|resolve\w*)\s*\(/
+
+/** Downloading code and running it, or decoding text and running it. */
+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
+ * (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|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|(?: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 =
+  /\b(?:ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|CLAUDE_CODE_OAUTH_TOKEN|OPENAI_API_KEY|GITHUB_TOKEN|GH_TOKEN|GITLAB_TOKEN|NPM_TOKEN|NODE_AUTH_TOKEN|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|AZURE_CLIENT_SECRET|GOOGLE_APPLICATION_CREDENTIALS|SLACK_BOT_TOKEN|SLACK_TOKEN|STRIPE_SECRET_KEY|HF_TOKEN|HUGGING_FACE_HUB_TOKEN)\b|\bJSON\.stringify\s*\(\s*process\.env\s*\)|\bObject\.(?:entries|keys|values)\s*\(\s*process\.env\s*\)|\bjson\.dumps\s*\(\s*(?:dict\s*\(\s*)?os\.environ|(?:^|[\s;&|])printenv[ \t]*(?:$|[|>;&])|(?:^|[\s;&|])env[ \t]*\|/m
+
+/** Places whose change persists past the session or grants itself more. */
+export const PERSISTENCE_TARGET =
+  /(?<![\w$)\]])\.(?:bashrc|bash_profile|bash_login|profile|zshrc|zprofile|zshenv|zlogin)\b|\bconfig\.fish\b|\bcrontab\b|\/etc\/cron|\bLaunchAgents\b|\bLaunchDaemons\b|\blaunchctl\s+(?:load|bootstrap|submit)\b|\bsystemctl\s+(?:--user\s+)?enable\b|\/etc\/systemd\/|\.config\/systemd\/|\.git\/hooks\b|\bcore\.hooksPath\b|\/etc\/profile\b|\.config\/autostart\b|CurrentVersion\\+Run\b/
+
+/** Claude Code settings and permission switches. */
+export const CLAUDE_SETTINGS =
+  /\.claude\/settings(?:\.local)?\.json|\bbypassPermissions\b|--dangerously-skip-permissions|\bdangerouslySkipPermissions\b|\benableAllProjectMcpServers\b|\benabledMcpjsonServers\b|"defaultMode"\s*:\s*"(?:bypassPermissions|acceptEdits)"|\bskipDangerousModePermissionPrompt\b|\bpermissions\s*(?:\.|\[\s*['"])\s*allow\b/
+
+/** Claude Code folders that load what is written into them. */
+export const CLAUDE_LOAD_DIR = /\.claude\/(?:skills|plugins|agents|commands|hooks)\b|\bCLAUDE\.md\b/
+
+/** Writing a file from a shell command: a redirect, tee, cp, mv and the like. */
+export const WRITE_SHELL =
+  /(?<![<>=!-])(?:\d?>>?|&>>?)(?!&)\s*["']?(?!\/dev\/null)[~$\/.\w]|\btee\s+(?:-a\s+)?["']?[~$\/.\w]|(?:^|[\s;&|])(?:cp|mv|install|ln|rsync)\s+\S|\bsed\s+-i\b/
+
+/** Writing a file from JavaScript or Python. */
+export const WRITE_CODE =
+  /\b(?:writeFile|appendFile|createWriteStream|writeFileSync|appendFileSync|copyFile|copyFileSync|renameSync|symlinkSync|cpSync)\s*\(|\bBun\.write\s*\(|\bDeno\.writeTextFile\s*\(|\$\s*\.\s*fs\s*\.\s*write\b|\bopen\s*\([^\n]{0,300}?,\s*(?:mode\s*=\s*)?['"](?:w|a|x|r\+|w\+|a\+)b?['"]|\.open\s*\(\s*(?:mode\s*=\s*)?['"](?:w|a|x|r\+|w\+|a\+)b?['"]|\.write_(?:text|bytes)\s*\(|\bshutil\.(?:copy\w*|move)\s*\(|\bos\.(?:rename|replace|symlink)\s*\(/
+
+/** Running programs from code. */
+export const PROCESS_CODE =
+  /\brequire\s*\(\s*['"](?:node:)?child_process['"]\s*\)|\bfrom\s+['"](?:node:)?child_process['"]|\b(?:execSync|execFileSync|spawnSync|execFile)\s*\(|\bchild_process\b|\bBun\.spawn(?:Sync)?\s*\(|\bDeno\.(?:run|Command)\b/
+
+export const PYTHON_PROCESS = /\bsubprocess\.(?:run|call|Popen|check_output|check_call|getoutput|getstatusoutput)\b|\bos\.(?:system|popen|spawn\w*|exec[lv]p?e?)\s*\(|\bpty\.spawn\s*\(/
+
+/** Building code from text at run time. */
+export const CODE_FROM_TEXT = /\beval\s*\(|\bnew\s+Function\s*\(|\bvm\.(?:runIn\w*Context|Script|compileFunction)\b|\bimport\s*\(\s*['"`]https?:/
+
+export const PYTHON_CODE_FROM_TEXT = /(?:^|[^.\w])(?:exec|eval|compile)\s*\(|\b__import__\s*\(|\b(?:pickle|marshal|dill|cloudpickle)\.loads?\s*\(/
+
+/** Decoding text into bytes or code. */
+export const DECODE = /\batob\s*\(|\bBuffer\.from\s*\([^)\n]{0,300}['"](?:base64|hex)['"]|\bbase64\.(?:b64decode|b32decode|a85decode|decodebytes)\b|\bbase64\s+(?:-d|--decode|-D)\b|\bcodecs\.decode\s*\(|\bbytes\.fromhex\s*\(/
+
+/** Hosts often used to collect stolen data. */
+export const COLLECTION_HOST =
+  /\b(?:webhook\.site|requestbin\.(?:com|net)|pipedream\.net|[\w-]{1,63}\.ngrok(?:-free)?\.(?:io|app|dev)|transfer\.sh|pastebin\.com|paste\.ee|hastebin\.com|discord(?:app)?\.com\/api\/webhooks|api\.telegram\.org|burpcollaborator\.net|oast\.(?:fun|me|pro|live|site|online)|interact\.sh|[\w-]{1,63}\.trycloudflare\.com|hooks\.slack\.com)\b/i
+
+/** Known key formats. Evidence names the kind and place, never the value. */
+export const SECRET_KEYS: readonly { kind: string; pattern: RegExp }[] = [
+  { kind: 'AWS access key ID', pattern: /\b(?:AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/ },
+  { kind: 'AWS secret access key', pattern: /\baws_?secret_?access_?key\b['"]?\s*[:=]\s*['"]?[A-Za-z0-9/+=]{40}(?![A-Za-z0-9/+=])/i },
+  { kind: 'GitHub token', pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,255}\b|\bgithub_pat_[A-Za-z0-9_]{22,255}\b/ },
+  { kind: 'Slack token', pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,255}\b/ },
+  { kind: 'Slack webhook', pattern: /https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]{1,40}\/B[A-Za-z0-9]{1,40}\/[A-Za-z0-9]{1,64}/ },
+  { kind: 'private key', pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/ },
+  { kind: 'Anthropic API key', pattern: /\bsk-ant-(?:api|admin|oat)\d{2}-[A-Za-z0-9_-]{20,255}/ },
+  { kind: 'OpenAI API key', pattern: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{16,200}T3BlbkFJ[A-Za-z0-9_-]{16,200}/ },
+  { kind: 'Google API key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { kind: 'Stripe live key', pattern: /\b(?:sk|rk)_live_[0-9a-zA-Z]{24,255}\b/ },
+  { kind: 'npm token', pattern: /\bnpm_[A-Za-z0-9]{36}\b/ },
+  { kind: 'SendGrid key', pattern: /\bSG\.[\w-]{22}\.[\w-]{43}\b/ },
+  { kind: 'Hugging Face token', pattern: /\bhf_[A-Za-z0-9]{34,255}\b/ },
+]
+
+/** A secret variable given a value in text: `ANTHROPIC_API_KEY=...`, `"GITHUB_TOKEN": "..."`. */
+const SECRET_ASSIGNMENT =
+  /\b((?:[A-Z][A-Z0-9]*_)*(?:API_KEY|AUTH_TOKEN|OAUTH_TOKEN|ACCESS_KEY|SECRET_ACCESS_KEY|SECRET_KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE_KEY))(['"]?\s*[:=]\s*['"]?)([^\s'"`,;]{6,})/g
+
+/**
+ * Replaces anything that looks like a key or a secret's value with
+ * `[redacted <kind>]`. Every excerpt a report shows passes through it, so a
+ * line quoted for another reason cannot print a key.
+ */
+export function redactSecrets(text: string): string {
+  let out = text
+  for (const { kind, pattern } of SECRET_KEYS) {
+    out = out.replace(new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`), `[redacted ${kind}]`)
+  }
+  return out
+    .replace(SECRET_ASSIGNMENT, (_, name: string, separator: string) => `${name}${separator}[redacted]`)
+    // A password in a URL: https://user:secret@host keeps the user, hides the secret.
+    .replace(/(\b[a-z][a-z0-9+.-]{1,20}:\/\/[^\s:/@]{1,100}:)[^\s@/]{1,200}@/gi, '$1[redacted]@')
+}

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