ai-install-guard 0.1.0 → 0.2.0

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,
     ),
@@ -256,11 +256,6 @@ function eventCapability(use: ModuleUse): Capability {
 }
 
 /** 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 +283,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
+}

package/hooks/scan/checks/prompts.ts

@@ -25,7 +25,8 @@ const INJECTION: readonly RegExp[] = [
 /** Text that talks to a security scanner instead of to a person. */
 const SCANNER_ADDRESS: readonly RegExp[] = [
   /\bnote\s+(?:to|for)\s+(?:the\s+|any\s+)?(?:security\s+|ai\s+|automated\s+)?(?:scanners?|reviewers?|auditors?|analy[sz]ers?)\b/i,
-  /\b(?:security\s+)?(?:scanners?|reviewers?|auditors?|analy[sz]ers?|llms?|language\s+models?|ai\s+(?:assistants?|models?|reviewers?))\b[^\n]{0,80}?\b(?:report|mark|classify|treat|consider|rate|flag|score)\b[^\n]{0,40}?\b(?:safe|pass(?:ed|ing)?|clean|benign|trusted|harmless|low[- ]risk|no\s+(?:issues|findings))\b/i,
+  // "Reviewer" or "auditor" alone is usually a person; it counts only as a tool.
+  /\b(?:(?:security|ai|automated|static|code)\s+(?:scanners?|reviewers?|auditors?|analy[sz]ers?)|scanners?|analy[sz]ers?|llms?|language\s+models?|ai\s+(?:assistants?|models?))\b[^\n]{0,80}?\b(?:report|mark|classify|treat|consider|rate|flag|score)\b[^\n]{0,40}?\b(?:safe|pass(?:ed|ing)?|clean|benign|trusted|harmless|low[- ]risk|no\s+(?:issues|findings))\b/i,
   /\b(?:this|the)\s+(?:plugin|skill|mod|code|package|repo(?:sitory)?|extension)\s+(?:is|has\s+been)\s+(?:completely\s+|totally\s+|fully\s+|100%\s+)?(?:safe|benign|harmless|verified|audited|approved)\b[^\n]{0,60}?\b(?:report|mark|pass|ignore|skip|approve)\b/i,
 ]
 
@@ -101,7 +102,9 @@ export function promptChecks(ctx: ScanContext): CheckResult[] {
       credentials.push({ file: path, line: match.line, excerpt: `names ${secretName(match)}`, status: cap(/\b(?:echo|print|printenv|cat|send|include|output)\b/i.test(lineText) ? 'fail' : 'warn') })
     }
 
-    for (const match of findAll(text, REMOTE_INSTRUCTIONS, 3)) {
+    // A local address (a preview server the skill starts) is not remote.
+    const remoteOnly = (index: number) => !/^[^\n]{0,120}?https?:\/\/(?:localhost|127(?:\.\d{1,3}){3}|\[::1\]|0\.0\.0\.0)(?![\w.-])/i.test(text.slice(index, index + 200))
+    for (const match of findAll(text, REMOTE_INSTRUCTIONS, 3, remoteOnly)) {
       remote.push({ file: path, line: match.line, excerpt: match.excerpt, status: cap('warn') })
     }
     // Telling the model to download and run code fails; a sentence warning

package/hooks/scan/checks/provenance.ts

@@ -0,0 +1,190 @@
+import { isRecord, parseJson, type ScanContext } from './context'
+import { joinPath } from './text'
+import { capEvidence, row, type CheckResult, type Evidence } from './types'
+
+const GROUP = 'provenance' as const
+const MARKETPLACE = '.claude-plugin/marketplace.json'
+const FULL_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i
+const SPECIAL_REFS = /^(?:HEAD|FETCH_HEAD|ORIG_HEAD|MERGE_HEAD|CHERRY_PICK_HEAD|REVERT_HEAD|REBASE_HEAD|BISECT_HEAD|AUTO_MERGE)$/
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/
+
+/**
+ * Group 1, for a marketplace: whether each plugin it lists from elsewhere is
+ * pinned to one commit (or one package version). A plugin that follows a
+ * branch installs whatever the branch holds that day, not what was reviewed.
+ */
+export function marketplacePinsCheck(ctx: ScanContext): CheckResult[] {
+  const parsed = parseJson(ctx.text(MARKETPLACE))
+  if (!parsed.ok || !isRecord(parsed.value) || !Array.isArray(parsed.value.plugins)) return []
+  const evidence: Evidence[] = []
+  for (const plugin of parsed.value.plugins) {
+    if (!isRecord(plugin)) continue
+    const name = typeof plugin.name === 'string' ? plugin.name : '(unnamed)'
+    const judged = judgeSource(plugin.source)
+    if (judged !== undefined) evidence.push({ file: MARKETPLACE, excerpt: `${name}: ${judged.what}`, status: judged.status })
+  }
+  if (evidence.length === 0) return []
+  return [
+    row(
+      {
+        id: 'provenance.pins',
+        group: GROUP,
+        title: 'Marketplace pins',
+        advice: 'Pin each plugin to a full commit id (sha) or an exact package version. A branch, a tag or a commit given as ref can change what installs after it was reviewed.',
+      },
+      // Every entry is judged; only the worst are listed.
+      capEvidence(evidence, 30),
+    ),
+  ]
+}
+
+function judgeSource(source: unknown): { what: string; status: 'pass' | 'warn' | 'fail' } | undefined {
+  if (typeof source === 'string') {
+    // A folder in the marketplace is pinned with the marketplace itself; one
+    // that climbs out of it is not part of what was pinned.
+    if (source.startsWith('./') || source.startsWith('../')) {
+      return joinPath('', source) === undefined ? { what: `comes from ${source}, outside the marketplace, which is not pinned with it`, status: 'warn' } : undefined
+    }
+    return { what: `comes from ${source} and follows its default branch`, status: 'warn' }
+  }
+  if (!isRecord(source)) return undefined
+  const kind = typeof source.source === 'string' ? source.source : 'unknown'
+  if (kind === 'npm' || kind === 'pip') {
+    const version = typeof source.version === 'string' ? source.version : undefined
+    const pkg = typeof source.package === 'string' ? source.package : '(package)'
+    return version !== undefined && EXACT_VERSION.test(version)
+      ? { what: `${kind} package ${pkg} at exactly ${version}`, status: 'pass' }
+      : { what: `${kind} package ${pkg} ${version === undefined ? 'at whatever version is newest' : `at ${version}, not one exact version`}`, status: 'warn' }
+  }
+  const where = typeof source.repo === 'string' ? source.repo : typeof source.url === 'string' ? source.url : kind
+  const sha = typeof source.sha === 'string' ? source.sha : undefined
+  const ref = typeof source.ref === 'string' ? source.ref : undefined
+  if (ref !== undefined && SPECIAL_REFS.test(ref)) return { what: `${where} names git's own ${ref} as its ref`, status: 'fail' }
+  if (sha !== undefined) {
+    return FULL_SHA.test(sha)
+      ? { what: `${where} pinned to commit ${sha.slice(0, 12)}`, status: 'pass' }
+      : { what: `${where} has sha "${sha.slice(0, 64)}", which is not a full commit id`, status: 'warn' }
+  }
+  if (ref !== undefined && FULL_SHA.test(ref)) {
+    return { what: `${where} gives a commit id as its ref; a branch with that name would be checked out instead, so use sha`, status: 'warn' }
+  }
+  if (ref !== undefined) return { what: `${where} follows ${ref}, which its owner can move`, status: 'warn' }
+  return { what: `${where} follows its default branch`, status: 'warn' }
+}
+
+/** What a README's AI Install Guard badge claims, read from its shields.io image. */
+export type BadgeClaim = {
+  file: string
+  line: number
+  claimed: 'safe' | 'caution' | 'reject' | 'unverified'
+  /** The version the badge names: a short commit or `tree <hash>`, when it names one. */
+  pin?: string
+  text: string
+}
+
+const BADGE_IMAGE = /img\.shields\.io\/badge\/AI(?:_|%20| )Install(?:_|%20| )Guard-([^)\s"'?]{1,300})/gi
+const HTML_BLOCK_START = /^ {0,3}<\/?[A-Za-z][\w-]*(?:\s|\/?>|$)/
+
+/**
+ * The strongest claim among the AI Install Guard badges a README shows, read
+ * the way a Markdown renderer shows it: fenced and indented code blocks and
+ * HTML comments are left out (there a badge is an example or hidden), while
+ * HTML blocks and list items, where badges usually sit indented, count. A
+ * badge whose words name no verdict is read as claiming the best one, since
+ * that is what it would make a reader think.
+ */
+export function badgeClaim(readme: { path: string; text: string } | undefined): BadgeClaim | undefined {
+  if (readme === undefined) return undefined
+  const lines = readme.text.split('\n')
+  let fence: { char: string; length: number } | undefined
+  let comment = false
+  let htmlBlock = false
+  let indentedCode = false
+  let listContext = false
+  let previousBlank = true
+  let best: BadgeClaim | undefined
+  for (let index = 0; index < lines.length; index += 1) {
+    let line = lines[index] as string
+    const blank = line.trim() === ''
+    // Inside a list item a fence may sit as deep as the item's own content.
+    const fenceIndent = listContext ? '[ \\t]{0,16}' : ' {0,3}'
+    if (fence !== undefined) {
+      // A fence closes only with its own character, at least as long, and nothing after.
+      const close = new RegExp(`^${fenceIndent}(\`{3,}|~{3,})[ \\t]*$`).exec(line)
+      if (close !== null && (close[1] as string)[0] === fence.char && (close[1] as string).length >= fence.length) fence = undefined
+      continue
+    }
+    if (comment) {
+      const end = line.indexOf('-->')
+      if (end === -1) continue
+      comment = false
+      line = line.slice(end + 3)
+    }
+    const open = htmlBlock ? null : new RegExp(`^${fenceIndent}(\`{3,}|~{3,})(.*)$`).exec(line)
+    // A backtick fence's info string cannot hold a backtick: ```x``` is inline code.
+    if (open !== null && !((open[1] as string)[0] === '`' && (open[2] as string).includes('`'))) {
+      fence = { char: (open[1] as string)[0] as string, length: (open[1] as string).length }
+      continue
+    }
+    // An HTML comment hides what it holds only when it opens a line; inline,
+    // only a closed one is a comment.
+    if (/^ {0,3}<!--/.test(line) && !line.includes('-->', line.indexOf('<!--') + 4)) {
+      comment = true
+      continue
+    }
+    const indented = /^(?: {4}|\t)/.test(line)
+    if (indentedCode && !blank && !indented) indentedCode = false
+    if (!indentedCode && indented && previousBlank && !listContext && !htmlBlock) indentedCode = true
+    if (htmlBlock && blank) htmlBlock = false
+    else if (!htmlBlock && !indentedCode && HTML_BLOCK_START.test(line)) htmlBlock = true
+    if (!blank && !indented) listContext = /^ {0,3}(?:[-*+]|\d{1,9}[.)])\s/.test(line) || (listContext && !previousBlank)
+    else if (/^ {0,3}(?:[-*+]|\d{1,9}[.)])\s/.test(line)) listContext = true
+    previousBlank = blank
+    if (indentedCode) continue
+    const shown = line.replace(/<!--[\s\S]*?-->/g, '').replace(/`[^`]*`/g, '')
+    for (const found of shown.matchAll(BADGE_IMAGE)) {
+      let message = found[1] as string
+      try {
+        message = decodeURIComponent(message)
+      } catch {
+        // Left as written.
+      }
+      const words = message.replace(/--/g, '\u0000').replace(/-[0-9a-f]{3,8}$|-[a-z]+$/i, '').replace(/_/g, ' ').replace(/\u0000/g, '-').toLowerCase()
+      const claimed = /do not install/.test(words) ? 'reject' : /could not verify/.test(words) ? 'unverified' : /caution|review what it can do/.test(words) ? 'caution' : 'safe'
+      const pin = /·\s*((?:tree\s+)?[0-9a-f]{7,64})\b/.exec(words)?.[1]
+      if (best === undefined || VERDICT_RANK[claimed] < VERDICT_RANK[best.claimed]) best = { file: readme.path, line: index + 1, claimed, pin, text: words.slice(0, 120) }
+    }
+  }
+  return best
+}
+
+const VERDICT_RANK = { safe: 0, caution: 1, unverified: 2, reject: 3 } as const
+const VERDICT_WORDS = { safe: 'Safe to install', caution: 'Review what it can do', unverified: 'Could not verify', reject: 'Do not install' } as const
+
+/**
+ * The row for a README's badge, judged against this scan's own verdict. A
+ * badge never improves a verdict: one that claims better than the scan finds
+ * is a warning, one that matches is only noted.
+ */
+export function badgeRow(claim: BadgeClaim, actual: keyof typeof VERDICT_RANK, version: { sha?: string; treeHash?: string } = {}): CheckResult {
+  const overclaims = VERDICT_RANK[claim.claimed] < VERDICT_RANK[actual]
+  // Which version the badge names, against the one scanned now.
+  const scanned = version.sha !== undefined ? version.sha.slice(0, 7) : version.treeHash !== undefined ? `tree ${version.treeHash.slice(7, 15)}` : undefined
+  const sameVersion = claim.pin !== undefined && scanned !== undefined && (claim.pin.startsWith('tree ') ? version.treeHash?.slice(7).startsWith(claim.pin.slice(5)) === true : version.sha?.startsWith(claim.pin) === true)
+  const named = claim.pin === undefined ? 'names no version' : sameVersion ? `is for this version (${claim.pin})` : `is for another version (${claim.pin})`
+  const summary = overclaims
+    ? [`The README's badge says ${VERDICT_WORDS[claim.claimed]}, but this version scans as ${VERDICT_WORDS[actual]}`, `The badge ${named}: it is outdated or was never earned`]
+    : sameVersion && claim.claimed === actual
+      ? [`The README shows an AI Install Guard badge for this version (${VERDICT_WORDS[claim.claimed]}); this scan agrees`]
+      : [`The README's badge says ${VERDICT_WORDS[claim.claimed]} and ${named}; this version scans as ${VERDICT_WORDS[actual]}`]
+  return row(
+    {
+      id: 'provenance.badge',
+      group: GROUP,
+      title: 'Review badge in the README',
+      advice: 'A badge is a picture anyone can paste. This scan is what counts: a badge that claims more than it finds is outdated or was never earned.',
+      summary,
+    },
+    [{ file: claim.file, line: claim.line, excerpt: `badge: ${claim.text}`, status: overclaims ? 'warn' : 'info' }],
+  )
+}