ai-install-guard 0.0.0 → 0.2.0

package/hooks/scan/checks/prompts.ts

@@ -0,0 +1,319 @@
+import { languageOf, secretName } from './code'
+import { isCodeFile, isLive, type ScanContext } from './context'
+import { CREDENTIAL_PATH, DOWNLOAD_AND_RUN, NETWORK_COMMAND, NETWORK_CODE, SECRET_ENV, UNPINNED_RUNNER } from './patterns'
+import { basename, dirname, findAll, findFirst, spanKinds } from './text'
+import { row, type CheckResult, type Evidence, type Status } from './types'
+
+const GROUP = 'prompts' as const
+
+/** Phrases that try to take over the model or hide from the person. */
+const INJECTION: readonly RegExp[] = [
+  /\bignore\s+(?:all\s+|any\s+)?(?:of\s+)?(?:the\s+|your\s+)?(?:previous|prior|above|earlier|preceding|system|original)\s+(?:instructions?|prompts?|messages?|rules|guidelines|directions)/i,
+  /\bdisregard\s+(?:(?:all|any)\s+)?(?:(?:the|your)\s+)?(?:(?:previous|prior|above|earlier|system|original)\s+)?(?:instructions?|prompts?|rules|guidelines)\b/i,
+  /\bforget\s+(?:all\s+|everything\s+)?(?:about\s+)?(?:your|the|previous|prior)\s+(?:instructions?|rules|guidelines)/i,
+  /\b(?:do\s+not|don['’]t|never)\s+(?:tell|inform|show|mention|reveal|disclose|alert|notify|warn)\s+(?:this\s+to\s+|it\s+to\s+|anything\s+to\s+)?(?:the\s+)?user\b/i,
+  /\bwithout\s+(?:telling|asking|informing|notifying|alerting|showing|warning)\s+(?:the\s+)?user\b/i,
+  /\b(?:silently|secretly|quietly|covertly|discreetly|invisibly)\s+(?:run|execute|send|upload|post|install|delete|remove|read|copy|modify|fetch|download|exfiltrate|transmit|forward|add|write|change|append|collect)\b/i,
+  /\b(?:override|bypass|disable|circumvent|skip)\s+(?:the\s+|all\s+|any\s+|your\s+)?(?:permission|permissions|safety|security|sandbox|approval|approvals|guardrails?|confirmation)\b/i,
+  /\bexfiltrat\w*/i,
+  /\b(?:send|post|upload|forward|transmit)\s+(?:it|them|this|that|everything|all|the\s+\w+(?:\s+\w+)?)\s+to\s+(?:https?:\/\/|the\s+(?:url|endpoint|server|webhook)|this\s+(?:url|endpoint|server|webhook))/i,
+  /\byou\s+are\s+now\s+(?:in\s+)?(?:developer|god|jailbreak|unrestricted|dan)\b/i,
+  /\b(?:new|updated|real|actual)\s+system\s+(?:prompt|instructions?)\s*:/i,
+  /<\s*\/?\s*(?:system|system-reminder|system_prompt|assistant)\s*>/i,
+]
+
+/** 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,
+  // "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,
+]
+
+const READ_VERB = /\b(?:cat|read|open|print|show|copy|upload|send|include|paste|output|display|load|attach|collect)\b/i
+
+const REMOTE_INSTRUCTIONS =
+  /\b(?:fetch|download|read|load|get|curl|retrieve|visit|open)\b[^\n]{0,80}?https?:\/\/\S{1,500}[^\n]{0,80}?\b(?:follow|execute|run|apply|obey|use|do)\b[^\n]{0,30}?\b(?:instructions?|steps|commands?|directions|it|them)\b|\bfollow\s+(?:the\s+)?(?:instructions?|steps|directions)\s+(?:at|from|in|on)\s+https?:\/\//i
+
+/** Claude Code's own commands, which a skill or command should not shadow. */
+const BUILT_IN_COMMANDS = new Set([
+  'add-dir', 'agents', 'bug', 'clear', 'compact', 'config', 'context', 'cost', 'doctor', 'exit', 'export', 'feedback', 'help',
+  'hooks', 'ide', 'init', 'install-github-app', 'login', 'logout', 'mcp', 'memory', 'model', 'output-style', 'permissions',
+  'plugin', 'plugins', 'pr-comments', 'privacy-settings', 'release-notes', 'resume', 'review', 'rewind', 'sandbox',
+  'security-review', 'skills', 'status', 'statusline', 'tasks', 'terminal-setup', 'theme', 'todos', 'upgrade', 'usage', 'vim',
+])
+
+const CLAIMS_ANTHROPIC = /\b(?:by|from|made\s+by|official(?:ly)?|verified\s+by|endorsed\s+by|approved\s+by)\s+anthropic\b|\banthropic[-\s]?(?:official|verified|certified)\b|\bofficial\s+claude\b/i
+
+/**
+ * What is wrong with a piece of model-facing text on its own (a prompt or
+ * agent hook): injection fails when it reaches out, reading credentials
+ * fails, anything else is a warning, as any model hook is.
+ */
+export function promptConcerns(text: string): { status: Status; reasons: string[] } {
+  const reachesOut = NETWORK_COMMAND.test(text) || NETWORK_CODE.test(text) || /https?:\/\//.test(text) || CREDENTIAL_PATH.test(text)
+  const reasons: string[] = []
+  let status: Status = 'warn'
+  if (INJECTION.some(pattern => pattern.test(text))) {
+    reasons.push('prompt injection')
+    if (reachesOut) status = 'fail'
+  }
+  if (CREDENTIAL_PATH.test(text) && READ_VERB.test(text)) {
+    reasons.push('reads credentials')
+    status = 'fail'
+  }
+  if (SCANNER_ADDRESS.some(pattern => pattern.test(text))) reasons.push('talks to the scanner')
+  return { status, reasons }
+}
+
+export function promptChecks(ctx: ScanContext): CheckResult[] {
+  const injection: Evidence[] = []
+  const credentials: Evidence[] = []
+  const tools: Evidence[] = []
+  const remote: Evidence[] = []
+  const names: Evidence[] = []
+
+  for (const path of ctx.prompts) {
+    const text = ctx.text(path)
+    if (text === undefined) continue
+    const live = isLive(ctx.roleOf(path))
+    const cap = (status: Status): Status => (live ? status : 'info')
+    const reachesOut = NETWORK_COMMAND.test(text) || NETWORK_CODE.test(text) || /https?:\/\//.test(text) || CREDENTIAL_PATH.test(text)
+
+    for (const pattern of INJECTION) {
+      for (const match of findAll(text, pattern, 3)) {
+        const hidden = isInsideComment(text, match.line) ? ' (inside an HTML comment, hidden when rendered)' : ''
+        injection.push({ file: path, line: match.line, excerpt: `${match.excerpt}${hidden}`, status: cap(reachesOut ? 'fail' : 'warn') })
+      }
+    }
+    const hiddenInstructions = findAll(text, /<!--[\s\S]{0,5000}?-->/g, 10_000)
+      .filter(comment => comment.text.length > 40 && /\b(?:run|execute|send|call|use|read|write|ignore|always|never|must)\b/i.test(comment.text))
+      .slice(0, 5)
+    for (const comment of hiddenInstructions) {
+      injection.push({ file: path, line: comment.line, excerpt: `instructions inside an HTML comment, hidden when rendered: ${comment.excerpt}`, status: cap('warn') })
+    }
+
+    for (const match of findAll(text, CREDENTIAL_PATH, 5)) {
+      const lineText = text.split('\n')[match.line - 1] ?? ''
+      credentials.push({ file: path, line: match.line, excerpt: match.excerpt, status: cap(READ_VERB.test(lineText) ? 'fail' : 'warn') })
+    }
+    for (const match of findAll(text, SECRET_ENV, 5)) {
+      const lineText = text.split('\n')[match.line - 1] ?? ''
+      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') })
+    }
+
+    // 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
+    // against it ("never run curl | sh") is still a warning, since negation
+    // is easy to fake ("don't hesitate to run ...").
+    for (const match of findAll(text, DOWNLOAD_AND_RUN, 3)) {
+      const warnsAgainst = isNegated(text, match.index)
+      remote.push({
+        file: path,
+        line: match.line,
+        excerpt: `${warnsAgainst ? 'mentions' : 'tells the model to'} download and run code: ${match.excerpt}`,
+        status: cap(warnsAgainst ? 'warn' : 'fail'),
+      })
+    }
+    // An unpinned package runner counts only as a command (in a code span or
+    // block), not prose about one ("npx is a package runner").
+    const inCode = codeSpans(text)
+    for (const match of findAll(text, UNPINNED_RUNNER, 3, inCode)) {
+      remote.push({ file: path, line: match.line, excerpt: `tells the model to run an unpinned package: ${match.excerpt}`, status: cap('warn') })
+    }
+
+    const front = frontmatter(text)
+    for (const key of ['allowed-tools', 'tools']) {
+      const value = front[key]
+      if (value === undefined) continue
+      for (const tool of toolList(value)) {
+        const verdict = judgeTool(tool)
+        if (verdict !== undefined) tools.push({ file: path, line: lineOfKey(text, key), excerpt: `${key}: ${tool} (${verdict.why})`, status: cap(verdict.status) })
+      }
+    }
+    const mode = front.permissionMode ?? front['permission-mode']
+    if (mode !== undefined && /\b(?:bypassPermissions|acceptEdits)\b/i.test(mode)) {
+      tools.push({ file: path, line: lineOfKey(text, 'permissionMode'), excerpt: `permissionMode: ${mode}`, status: cap('fail') })
+    }
+
+    const name = (front.name ?? basename(path).replace(/\.(md|mdx|markdown)$/i, '')).trim().toLowerCase()
+    const commandName = /(^|\/)SKILL\.md$/i.test(path) ? (front.name ?? basename(dirname(path))).toLowerCase() : name
+    if (BUILT_IN_COMMANDS.has(commandName)) {
+      names.push({ file: path, excerpt: `named /${commandName}, the same as a Claude Code command`, status: cap('warn') })
+    }
+    const claim = findFirst(`${front.name ?? ''}\n${front.description ?? ''}`, CLAIMS_ANTHROPIC)
+    if (claim !== undefined) names.push({ file: path, excerpt: `claims to come from Anthropic: ${claim.excerpt}`, status: cap('warn') })
+    if (/(^|\/)SKILL\.md$/i.test(path) && front.name !== undefined && front.name.trim() !== basename(dirname(path)) && dirname(path) !== '') {
+      names.push({ file: path, excerpt: `skill name "${front.name.trim()}" differs from its folder "${basename(dirname(path))}"`, status: 'info' })
+    }
+  }
+
+  const manifestName = typeof ctx.manifest?.name === 'string' ? ctx.manifest.name : ''
+  const manifestText = `${manifestName}\n${typeof ctx.manifest?.description === 'string' ? ctx.manifest.description : ''}`
+  const claim = findFirst(manifestText, CLAIMS_ANTHROPIC)
+  if (claim !== undefined || /\banthropic\b/i.test(manifestName)) {
+    names.push({ file: '.claude-plugin/plugin.json', excerpt: `presents itself as Anthropic's: ${claim?.excerpt ?? manifestName}`, status: 'warn' })
+  }
+
+  // Text aimed at the scanner, anywhere in the candidate but its own patterns and comments.
+  const addressed: Evidence[] = []
+  for (const file of ctx.files) {
+    const text = ctx.text(file.path)
+    if (text === undefined) continue
+    const kindAt = isCodeFile(file.path, text) ? spanKinds(text, languageOf(file.path, text)) : undefined
+    const status: Status = ctx.roleOf(file.path) === 'test' ? 'info' : 'warn'
+    const seen = new Set<number>()
+    for (const pattern of SCANNER_ADDRESS) {
+      for (const match of findAll(text, pattern, 2)) {
+        const kind = kindAt?.(match.index)
+        if (kind === 'regex' || kind === 'comment' || seen.has(match.line)) continue
+        seen.add(match.line)
+        addressed.push({ file: file.path, line: match.line, excerpt: match.excerpt, status })
+      }
+    }
+  }
+
+  const results = [
+    row({ id: 'prompts.injection', group: GROUP, title: 'Prompt injection', advice: 'Skills, commands and agents are instructions the model follows. Text that tells it to ignore you, hide what it does or send data out is an attack, more so when it names a URL or your keys.' }, injection),
+    row({ id: 'prompts.credentials', group: GROUP, title: 'Instructions that touch credentials', advice: 'A skill has no reason to read your keys, tokens or browser data. Do not install one that asks the model to.' }, credentials),
+    row({ id: 'prompts.tools', group: GROUP, title: 'Tool permissions it grants itself', advice: 'allowed-tools runs those tools without asking you. Bash with no pattern, a wildcard, an interpreter or a package runner is the same as giving it your shell.' }, tools),
+    row({ id: 'prompts.remote', group: GROUP, title: 'Remote instructions and code', advice: 'Instructions or code loaded from a URL at run time can change after this scan, so they were never checked. Prefer skills that ship everything they run.' }, remote),
+    row({ id: 'prompts.names', group: GROUP, title: 'Names and claims', advice: 'A name that shadows a built-in command or claims to be from Anthropic is a common way to be trusted by mistake.' }, names),
+    row({ id: 'prompts.scanner', group: GROUP, title: 'Text addressed to a security scanner', advice: 'Legitimate plugins do not talk to scanners. This text cannot change the verdict here; treat it as a sign of intent.' }, addressed),
+  ]
+  return ctx.prompts.length === 0 ? results.filter(result => result.id === 'prompts.names' || result.id === 'prompts.scanner') : results
+}
+
+/** Programs that run anything they are given, fetch and run packages, or reach the network. */
+const SHELL_WIDE = new Set([
+  'sh', 'bash', 'zsh', 'dash', 'fish', 'ksh', 'csh', 'tcsh', 'pwsh', 'powershell', 'cmd', 'osascript',
+  'python', 'node', 'deno', 'bun', 'perl', 'ruby', 'php', 'lua', 'awk', 'gawk',
+  'eval', 'exec', 'env', 'xargs', 'sudo', 'su', 'doas', 'nohup', 'timeout', 'watch',
+  'npx', 'bunx', 'pnpx', 'uvx', 'pipx', 'npm', 'pnpm', 'yarn', 'uv',
+  'curl', 'wget', 'nc', 'ncat', 'netcat', 'socat', 'ssh', 'scp', 'sftp', 'telnet',
+])
+
+/**
+ * Whether the words right before `index` tell the reader not to run what
+ * follows: the nearest negation ("never run this:", "avoid", "do not use")
+ * within three words. "Don't hesitate to run" or "never forget to run" urge
+ * the reader on, so they are not a negation.
+ */
+function isNegated(text: string, index: number): boolean {
+  const before = text.slice(Math.max(0, index - 40), index).split(/[.!?\n]/).pop() ?? ''
+  const last = Array.from(before.matchAll(/\b(?:never|not|don['’]t|do not|avoid|instead of)\b/gi)).at(-1)
+  if (last === undefined) return false
+  const rest = before.slice(last.index ?? 0)
+  if (/^(?:never|not|don['’]t|do not)\s+(?:ever\s+)?(?:hesitate|forget|fail|neglect|wait)\b/i.test(rest)) return false
+  return /^(?:never|not|don['’]t|do not|avoid|instead of)(?:\W+\w+){0,3}\W*$/i.test(rest)
+}
+
+/**
+ * A lookup for whether an index falls inside a Markdown code span or fenced
+ * block. Fences, line breaks and backticks are found once per text, so
+ * asking about many matches stays linear.
+ */
+function codeSpans(text: string): (index: number) => boolean {
+  const positions = (pattern: RegExp) => Array.from(text.matchAll(pattern), match => match.index ?? 0)
+  const fences = positions(/^[ \t]*(?:```|~~~)/gm)
+  const breaks = positions(/\n/g)
+  const ticks = positions(/`/g)
+  const prompts = new Map<number, boolean>()
+  return index => {
+    if (countBefore(fences, index) % 2 === 1) return true
+    const line = countBefore(breaks, index)
+    const lineStart = line === 0 ? 0 : (breaks[line - 1] as number) + 1
+    if ((countBefore(ticks, index) - countBefore(ticks, lineStart)) % 2 === 1) return true
+    let prompt = prompts.get(lineStart)
+    if (prompt === undefined) {
+      const shell = /[ \t]*\$\s/y
+      shell.lastIndex = lineStart
+      prompt = shell.test(text)
+      prompts.set(lineStart, prompt)
+    }
+    return prompt
+  }
+}
+
+/** How many of the sorted `positions` come before `index`. */
+function countBefore(positions: number[], index: number): number {
+  let low = 0
+  let high = positions.length
+  while (low < high) {
+    const mid = (low + high) >> 1
+    if ((positions[mid] as number) < index) low = mid + 1
+    else high = mid
+  }
+  return low
+}
+
+function judgeTool(tool: string): { status: Status; why: string } | undefined {
+  const bash = /^Bash\s*(?:\(([\s\S]*)\))?$/i.exec(tool.trim())
+  if (bash === null) return undefined
+  const pattern = bash[1]?.trim()
+  // Bash with no pattern runs any command unasked, exactly as Bash(*) does.
+  if (pattern === undefined) return { status: 'fail', why: 'any shell command: no pattern narrows it' }
+  if (/^\*+\s*(?::\s*\*+)?$/.test(pattern) || pattern === '') return { status: 'fail', why: 'a wildcard: any shell command' }
+  // The program the pattern allows, without its path: `/bin/sh:*` is `sh`.
+  const program = basename(/^[^\s:]+/.exec(pattern)?.[0] ?? '').toLowerCase()
+  if (SHELL_WIDE.has(program) || /^python\d*(?:\.\d+)?$/.test(program)) {
+    return { status: 'fail', why: 'an interpreter, package runner or network tool: any command through it' }
+  }
+  return undefined
+}
+
+function frontmatter(text: string): Record<string, string> {
+  const match = /^\ufeff?---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text)
+  if (match === null) return {}
+  const out: Record<string, string> = {}
+  let lastKey: string | undefined
+  for (const line of (match[1] as string).split(/\r?\n/)) {
+    const pair = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line)
+    if (pair !== null) {
+      lastKey = pair[1] as string
+      out[lastKey] = unquote((pair[2] as string).trim())
+    } else if (lastKey !== undefined && /^[ \t]*-[ \t]+/.test(line)) {
+      // A YAML list item, indented or at column 0 under its key.
+      out[lastKey] = `${out[lastKey] ?? ''}${out[lastKey] ? ', ' : ''}${unquote(line.replace(/^[ \t]*-[ \t]+/, '').trim())}`
+    }
+  }
+  return out
+}
+
+/** YAML's surrounding quotes, removed: `"help"` → `help`. */
+function unquote(value: string): string {
+  return /^(["']).*\1$/.test(value) ? value.slice(1, -1) : value
+}
+
+/** `Bash(git:*), Read` or `[Bash, Read]` → the tool names, keeping each pattern whole. */
+function toolList(value: string): string[] {
+  const out: string[] = []
+  let depth = 0
+  let current = ''
+  for (const char of value.replace(/^\[|\]$/g, '')) {
+    if (char === '(') depth += 1
+    if (char === ')') depth = Math.max(0, depth - 1)
+    if ((char === ',' || (char === ' ' && depth === 0 && current.trim() !== '' && !current.endsWith('('))) && depth === 0) {
+      if (current.trim() !== '') out.push(current.trim().replace(/^["']|["']$/g, ''))
+      current = ''
+    } else {
+      current += char
+    }
+  }
+  if (current.trim() !== '') out.push(current.trim().replace(/^["']|["']$/g, ''))
+  return out
+}
+
+function lineOfKey(text: string, key: string): number | undefined {
+  return findFirst(text, new RegExp(`^${key}\\s*:`, 'm'))?.line
+}
+
+function isInsideComment(text: string, line: number): boolean {
+  const lines = text.split('\n')
+  const before = lines.slice(0, line).join('\n')
+  return before.lastIndexOf('<!--') > before.lastIndexOf('-->')
+}

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' }],
+  )
+}

package/hooks/scan/checks/quality.ts

@@ -0,0 +1,56 @@
+import { isTestPath, type ScanContext } from './context'
+import type { CheckResult } from './types'
+
+/** Group 1's local part: a license. The rest of provenance needs the repo. */
+export function licenseCheck(ctx: ScanContext): CheckResult {
+  const file = ctx.files.find(entry => /^(?:license|licence|copying)(?:\.[a-z]+)?$/i.test(entry.path))
+  const declared = typeof ctx.manifest?.license === 'string' && ctx.manifest.license.trim() !== '' ? ctx.manifest.license.trim() : undefined
+  const found = file?.path ?? (declared === undefined ? undefined : `license "${declared}" in plugin.json`)
+  return {
+    id: 'provenance.license',
+    group: 'provenance',
+    title: 'License',
+    status: found === undefined ? 'warn' : 'pass',
+    severity: found === undefined ? 'low' : 'none',
+    evidence: found === undefined ? [{ file: '-', excerpt: 'no LICENSE file and no license in plugin.json', status: 'warn' }] : [{ file: found, excerpt: 'license present', status: 'pass' }],
+    advice: 'Without a license you have no clear right to use or change the code, and it is a sign of a hurried or throwaway project.',
+  }
+}
+
+/** Group 9: reported, never a reason to fail. */
+export function qualityChecks(ctx: ScanContext): CheckResult[] {
+  const tests = ctx.files.filter(file => isTestPath(file.path)).length
+  const readme = ctx.readme?.text ?? ''
+  const explainsUninstall = /\b(?:uninstall|remove|disable)\b/i.test(readme)
+  return [
+    {
+      id: 'quality.tests',
+      group: 'quality',
+      title: 'Tests',
+      status: 'info',
+      severity: 'none',
+      evidence: [{ file: '-', excerpt: tests > 0 ? `${tests} test file${tests === 1 ? '' : 's'} (not run)` : 'no tests found' }],
+      advice: 'Tests are a sign of care. They are never run here.',
+    },
+    {
+      id: 'quality.readme',
+      group: 'quality',
+      title: 'README',
+      status: readme.trim().length < 80 ? 'warn' : 'info',
+      severity: readme.trim().length < 80 ? 'low' : 'none',
+      evidence: [
+        {
+          file: ctx.readme?.path ?? '-',
+          excerpt:
+            readme.trim().length < 80
+              ? 'no README that says what it does'
+              : explainsUninstall
+                ? 'says what it does and how to remove it'
+                : 'does not say how to uninstall',
+          status: readme.trim().length < 80 ? 'warn' : 'info',
+        },
+      ],
+      advice: 'A README should say what the plugin does, what it needs and how to remove it.',
+    },
+  ]
+}