@clear-capabilities/agentic-security-scanner 0.132.0 → 0.134.0

package/src/posture/prove-findings.js

@@ -0,0 +1,172 @@
+// Promote findings to `execution-proven` during a scan (R2 — the automatic half).
+//
+// Before this, `proveFinding` existed and was tested but had no call site in a
+// scan, so `last-scan.json` could never contain an execution-proven finding and
+// corpus auto-enrolment had to be driven by hand. This annotator closes that:
+// it synthesizes a sandbox-runnable PoC for eligible findings, runs it inside
+// R1's sandbox, and lets the sandbox decide the tier.
+//
+// OPT-IN, AND IT STAYS OPT-IN. This executes code derived from the scanned
+// project. That is a different risk class from static analysis, and it is slow
+// — one sandboxed process per candidate. Making it default-on would change
+// what `scan` means. Enable with `AGENTIC_SECURITY_PROVE=1`.
+//
+// FAIL-CLOSED IN BOTH DIRECTIONS:
+//   - No sandbox → nothing is executed and no tier is promoted. An
+//     unavailable sandbox disables the feature, it never bypasses it.
+//   - A PoC that could not run leaves the finding at its static tier. Only a
+//     PoC that RAN and produced the marker yields `execution-proven`;
+//     `attachProofTier` enforces that independently of anything here.
+//
+// BOUNDED TWICE, BECAUSE ONE BOUND WAS NOT ENOUGH. `maxCandidates` caps how
+// many findings are proved in one scan, and the cap is REPORTED rather than
+// applied silently — a scan that quietly proved the first N findings and said
+// nothing would look like a scan that found only N provable ones.
+//
+// A count cap alone bounds nothing in time, though, and a per-run timeout is
+// only as good as the backend's ability to enforce it — which CI proved is not
+// something to take on faith (the namespace backend's timeout did not stop a
+// payload at all until `killSignal: 'SIGKILL'` landed). So there is also an
+// AGGREGATE wall-clock budget checked between candidates. It cannot interrupt a
+// call already in flight (`spawnSync` blocks the thread), but it bounds the
+// total and stops the loop rather than letting a slow host multiply one bad
+// case by `maxCandidates`.
+//
+// WHAT THIS ACTUALLY EXECUTES, STATED PLAINLY. The generated PoC does
+// `import handler from './<target file>'`, and an ES module import runs the
+// target file's ENTIRE TOP-LEVEL BODY before any handler is called. So enabling
+// this on a repository you do not trust executes that repository's top-level
+// code. Confinement contains what it can — no filesystem writes outside the
+// sandbox root, no network egress, both verified by executing tests on each
+// backend — but CPU and wall-clock are bounded only by the budgets here. Do not
+// enable this on untrusted code without accepting that.
+
+import { synthesizeInProcessPoc } from './poc-inprocess.js';
+import { proveFinding, DEFAULT_PROOF_TIMEOUT_MS } from './execution-proof.js';
+import { sandboxAvailable } from '../sandbox/index.js';
+
+const DEFAULT_MAX = 25;
+// Aggregate wall-clock across all candidates in one scan.
+const DEFAULT_TOTAL_BUDGET_MS = 120000;
+
+/**
+ * The file set materialised into the sandbox root for one PoC.
+ *
+ * `requires` names the vulnerable source (the PoC imports it). `extraFiles`
+ * carries support files a template needs that are NOT that source — the SQL
+ * class ships a recording driver stub as `node_modules/<driver>/index.js`.
+ *
+ * `requires` WINS on a collision. Otherwise a template could name the
+ * vulnerable file in `extraFiles` and replace the very code the PoC is
+ * supposed to exploit with content of its own choosing, and the run would
+ * prove a fact about the template.
+ */
+export function mergePocFiles(poc, content) {
+  const files = {};
+  for (const rel of poc?.requires || []) files[rel] = content;
+  for (const [rel, c] of Object.entries(poc?.extraFiles || {})) {
+    if (rel in files) continue;
+    if (typeof c === 'string') files[rel] = c;
+  }
+  return files;
+}
+
+export function proveEnabled(env = process.env) {
+  return env.AGENTIC_SECURITY_PROVE === '1';
+}
+
+/**
+ * @param {object[]} findings   annotated findings (mutated in place)
+ * @param {object}   opts
+ * @param {Map|object} opts.fileContents  file -> source, as the engine already carries
+ * @returns {object} a summary suitable for surfacing on the scan
+ */
+export async function annotateExecutionProofs(findings, {
+  // Shares one ceiling with execution-proof.js so the two cannot drift; see the
+  // rationale on DEFAULT_PROOF_TIMEOUT_MS there. Bounded overall by
+  // maxCandidates, so a generous per-PoC budget cannot run away.
+  fileContents = null, maxCandidates = DEFAULT_MAX, timeoutMs = DEFAULT_PROOF_TIMEOUT_MS,
+  totalBudgetMs = DEFAULT_TOTAL_BUDGET_MS, env = process.env, now = Date.now,
+} = {}) {
+  const summary = {
+    enabled: false, attempted: 0, proven: 0, failed: 0, inconclusive: 0,
+    skipped: 0, capped: 0, budgetExhausted: 0, reason: null,
+  };
+  if (!Array.isArray(findings) || !findings.length) return summary;
+  if (!proveEnabled(env)) {
+    summary.reason = 'not enabled (set AGENTIC_SECURITY_PROVE=1)';
+    return summary;
+  }
+  if (!sandboxAvailable()) {
+    // Deliberately not an error: an unavailable confinement primitive means
+    // execution features switch OFF, per R1's constraint.
+    summary.reason = 'no confinement backend available; execution proof disabled';
+    return summary;
+  }
+  summary.enabled = true;
+
+  const read = (file) => {
+    if (!fileContents) return null;
+    if (typeof fileContents.get === 'function') return fileContents.get(file) ?? null;
+    return fileContents[file] ?? null;
+  };
+
+  const candidates = [];
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const content = read(f.file);
+    const syn = synthesizeInProcessPoc(f, content);
+    if (!syn.ok) { summary.skipped++; continue; }
+    candidates.push({ finding: f, poc: syn.poc, content });
+  }
+
+  if (candidates.length > maxCandidates) {
+    summary.capped = candidates.length - maxCandidates;
+    candidates.length = maxCandidates;
+  }
+
+  const startedAt = now();
+  for (const c of candidates) {
+    // Checked BEFORE each call, since a call in flight cannot be interrupted.
+    // Reported, never silent: findings left unproven because the budget ran out
+    // are a different statement from findings that could not be proved.
+    if (now() - startedAt >= totalBudgetMs) {
+      summary.budgetExhausted = candidates.length - summary.attempted;
+      break;
+    }
+    summary.attempted++;
+    // The PoC imports the vulnerable file, so it must exist in the sandbox
+    // root alongside it.
+    const files = mergePocFiles(c.poc, c.content);
+    let proved;
+    try {
+      proved = await proveFinding({ ...c.finding, poc: c.poc }, { files, timeoutMs });
+    } catch (e) {
+      summary.inconclusive++;
+      continue;
+    }
+    c.finding.poc = c.poc;
+    c.finding.proofTier = proved.proofTier;
+    c.finding.proofEvidence = proved.proofEvidence;
+    if (proved.proofTier === 'execution-proven') summary.proven++;
+    else if (proved.proofTier === 'proof-failed') summary.failed++;
+    else summary.inconclusive++;
+  }
+  return summary;
+}
+
+/** One-line human summary; null when the feature did not run. */
+export function renderProofSummary(s) {
+  if (!s || !s.enabled) return null;
+  const bits = [`${s.proven} execution-proven of ${s.attempted} attempted`];
+  if (s.failed) bits.push(`${s.failed} ran without demonstrating the bug (triage signal, NOT a false-positive verdict)`);
+  if (s.inconclusive) bits.push(`${s.inconclusive} inconclusive`);
+  if (s.capped) bits.push(`${s.capped} eligible finding(s) NOT attempted (per-scan cap)`);
+  if (s.budgetExhausted) {
+    bits.push(`${s.budgetExhausted} eligible finding(s) NOT attempted (aggregate time budget exhausted) — `
+      + 'unproven here means unattempted, not unprovable');
+  }
+  return bits.join('; ') + '.';
+}
+
+export const _internals = { DEFAULT_MAX, DEFAULT_TOTAL_BUDGET_MS };

package/src/posture/rule-overrides.js

@@ -120,11 +120,72 @@ export function applyOverrides(findings, scanRoot) {
     disable = new Set();
   }
   const sevMap = o.severityOverrides || {};
-  return findings
-    .filter(f => !disable.has(f.vuln) && !disable.has(f.id))
-    .map(f => sevMap[f.vuln] ? { ...f, severity: sevMap[f.vuln] } : f);
+  const kept = [];
+  for (const f of findings) {
+    const key = disable.has(f.vuln) ? f.vuln : (disable.has(f.id) ? f.id : null);
+    if (key !== null) {
+      // RECORD the suppression. A `disable:` that takes effect otherwise
+      // produces findings that are simply absent — indistinguishable, in the
+      // artifact a human reads, from a clean scan. Coverage reduction must be
+      // visible where the results are, not only on a stderr line nobody keeps.
+      _recordSuppression(scanRoot, key, f);
+      continue;
+    }
+    kept.push(sevMap[f.vuln] ? { ...f, severity: sevMap[f.vuln] } : f);
+  }
+  return kept;
+}
+
+// Per-scanRoot ledger of what `disable:` removed, and under what authority.
+// Read by the CLI and attached to the scan output.
+const _suppressions = new Map();
+
+function _recordSuppression(scanRoot, key, finding) {
+  const root = String(scanRoot || '');
+  let e = _suppressions.get(root);
+  if (!e) { e = { rules: new Map(), total: 0 }; _suppressions.set(root, e); }
+  let r = e.rules.get(key);
+  if (!r) { r = { rule: key, count: 0, severities: {}, examples: [] }; e.rules.set(key, r); }
+  r.count++;
+  e.total++;
+  const sev = finding?.severity || 'unknown';
+  r.severities[sev] = (r.severities[sev] || 0) + 1;
+  // A bounded sample so a reader can see WHAT was removed, not just how much.
+  if (r.examples.length < 5 && finding?.file) {
+    r.examples.push(`${finding.file}${finding.line ? ':' + finding.line : ''}`);
+  }
 }
 
+/**
+ * What `disable:` removed from this scan, and under what authority.
+ *
+ * Returns null when nothing was suppressed — callers omit the section rather
+ * than rendering an empty one. `authority` is the reason the gate allowed it,
+ * so a reader can tell a signed suppression from an env-var opt-out.
+ */
+export function suppressionReport(scanRoot) {
+  const e = _suppressions.get(String(scanRoot || ''));
+  if (!e || !e.total) return null;
+  const gate = _disableAllowed(scanRoot);
+  return {
+    total: e.total,
+    authority: gate.reason,
+    rules: [...e.rules.values()].sort((a, b) => b.count - a.count || (a.rule < b.rule ? -1 : 1)),
+    note: 'These findings were REMOVED from the report by `disable:` in '
+      + '.agentic-security/rules.yml. They are not absent because the code is clean.',
+  };
+}
+
+/** One-line human summary; null when nothing was suppressed. */
+export function renderSuppressionSummary(rep) {
+  if (!rep) return null;
+  const top = rep.rules.slice(0, 3).map(r => `${r.rule} (${r.count})`).join(', ');
+  return `${rep.total} finding(s) SUPPRESSED by rules.yml disable: [${top}${rep.rules.length > 3 ? ', …' : ''}] `
+    + `— authority: ${rep.authority}. These are removed results, not clean code.`;
+}
+
+export function _resetSuppressionsForTests() { _suppressions.clear(); }
+
 // Cache: compiled custom rules per scanRoot. Validated at first call;
 // subsequent calls for the same scan reuse the compiled regexes.
 const _compiledCustomRules = new Map();   // scanRoot → { compiled[], errors[] }

package/src/posture/state-dir.js

@@ -16,6 +16,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+const STATE_DIR_NAME = '.agentic-security';
+
 const PROJECT_MARKERS = [
   '.git',
   'package.json',
@@ -83,6 +85,29 @@ export function isSafeStateDir(dir) {
       if (fs.existsSync(path.join(parent, m))) return true;
     } catch { /* ignore */ }
   }
+  // A directory NESTED inside an already-valid state root is safe too.
+  //
+  // Without this the check only ever accepted `<project>/.agentic-security`
+  // itself, because it looks for a project marker in the immediate parent and
+  // `.agentic-security` deliberately does not count as one. Every nested state
+  // directory — `llm-cache/`, `fix-history/`, `sbom-history/` — therefore
+  // failed, and `safeWriteState` silently refused to write there.
+  //
+  // The consequence was not theoretical: `llm-validator`'s `writeCache` goes
+  // through `safeWriteState`, so the validator cache never persisted a single
+  // entry. Every scan re-queried the model for every finding, while a
+  // `validator-cache stats|gc` subcommand existed to manage a cache that was
+  // always empty. Found by a positive-control test asserting that a
+  // legitimately written entry round-trips.
+  //
+  // This does not weaken the guard. Its purpose is to stop `.agentic-security/`
+  // being created in unrelated directories; a subdirectory of a state root that
+  // has already been validated is exactly the case it was never meant to catch.
+  const segments = path.resolve(dir).split(path.sep);
+  const idx = segments.lastIndexOf(STATE_DIR_NAME);
+  if (idx > 0 && idx < segments.length - 1) {
+    return isSafeStateDir(segments.slice(0, idx + 1).join(path.sep));
+  }
   return false;
 }
 

package/src/posture/vuln-archaeology.js

@@ -0,0 +1,231 @@
+// R14 — vulnerability archaeology.
+//
+// The engine scores the CURRENT tree, and `material-change.js` scores a diff.
+// Neither reads history. But a repository's history holds a signal nothing in
+// the present tree does: WHERE this team has introduced security bugs before,
+// and how often those places needed fixing again.
+//
+// The output is not a finding. It is a per-file risk prior — "this file has
+// been security-fixed four times in the last two years" — that ranks where
+// attention is worth spending. Emitting archaeology as findings would be
+// wrong twice over: the bugs are already fixed, and a historical fix is not
+// evidence of a present defect.
+//
+// HOW A SECURITY FIX IS RECOGNISED, AND WHY THAT IS THE HARD PART. There is no
+// reliable marker. Commit messages are the only broad signal, and they are
+// written by humans in a hurry. So the classifier is deliberately conservative
+// and every match carries the evidence that produced it:
+//
+//   - A CVE/GHSA identifier is strong evidence and is treated as such.
+//   - A vocabulary of fix verbs paired with vulnerability nouns ("fix XSS",
+//     "patch the traversal") is medium evidence.
+//   - A bare vulnerability noun is weak: "add XSS tests", "refactor the auth
+//     module" and "document CSRF" all mention the noun without fixing
+//     anything. These are counted separately and never inflate the strong tier.
+//
+// FALSE POSITIVES ARE EXPECTED AND MUST STAY VISIBLE. A message-based
+// classifier cannot be precise, so the module reports its tiers separately
+// rather than collapsing them into one confident number, and every hotspot
+// carries the commit subjects behind it so a human can dismiss a bad match in
+// seconds. A single blended "risk score" would hide exactly the errors a
+// reader needs to see.
+//
+// Offline and cheap: one `git log` invocation, bounded by commit count and a
+// timeout, degrading to an empty result in a non-repository.
+
+import { execFileSync } from 'node:child_process';
+
+const CVE_RE = /\b(?:CVE-\d{4}-\d{4,7}|GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})\b/i;
+
+const FIX_VERBS = /\b(?:fix(?:e[sd])?|patch(?:e[sd])?|resolv(?:e[sd])|remediat(?:e[sd])|harden(?:ed)?|mitigat(?:e[sd])|prevent(?:ed)?|sanitiz(?:e[sd])|escap(?:e[sd])|clos(?:e[sd]))\b/i;
+
+const VULN_NOUNS = new RegExp([
+  'xss', 'cross[- ]site scripting', 'csrf', 'cross[- ]site request forgery',
+  'sql[- ]?injection', 'sqli', 'command[- ]?injection', 'code[- ]?injection',
+  'path[- ]?traversal', 'directory[- ]?traversal', 'ssrf', 'xxe',
+  'deserializ', 'prototype[- ]pollution', 'open[- ]redirect', 'redos',
+  'privilege escalation', 'auth(?:entication|orization)? bypass', 'idor',
+  'insecure[- ]direct[- ]object', 'race condition', 'use[- ]after[- ]free',
+  'buffer overflow', 'integer overflow', 'timing attack', 'security', 'vulnerab',
+  'exploit', 'injection', 'sanitiz', 'unsafe[- ]eval', 'hardcoded (?:secret|password|key|credential)',
+].join('|'), 'i');
+
+// Messages that mention a vulnerability noun while plainly not fixing one.
+// Checked BEFORE the verb pair, because "add tests for the XSS fix" contains
+// both a fix verb and a noun yet fixes nothing.
+//
+// KEPT DELIBERATELY NARROW. Words like "comment", "format", "example", "spec"
+// and "demo" look like chore markers but are ordinary code vocabulary — "fix
+// XSS in the comment renderer" is a real fix, and an over-broad list demotes it
+// to the weak tier. Every word here has to be one that describes the COMMIT'S
+// PURPOSE and is unlikely to name a code component. When in doubt leave a word
+// out: a missed demotion costs one over-counted hotspot, while a wrong one
+// hides a real security fix from the ranking entirely.
+const NON_FIX_RE = /\b(?:test(?:s|ing|ed)?|doc(?:s|ument(?:s|ed|ing|ation)?)?|readme|changelog|typo|rename[ds]?|lint|bump(?:ed)?|revert(?:ed)?|wip|todo)\b/i;
+
+export const TIERS = Object.freeze(['identified', 'likely', 'mentioned']);
+
+/**
+ * Classify one commit subject.
+ * @returns {{tier:string, evidence:string}|null}
+ */
+export function classifyCommit(subject) {
+  if (typeof subject !== 'string' || !subject.trim()) return null;
+  const s = subject.trim();
+
+  const cve = s.match(CVE_RE);
+  if (cve) return { tier: 'identified', evidence: `references ${cve[0]}` };
+
+  const noun = s.match(VULN_NOUNS);
+  if (!noun) return null;
+
+  if (NON_FIX_RE.test(s)) {
+    return { tier: 'mentioned', evidence: `mentions "${noun[0]}" but reads as test/doc/chore work` };
+  }
+  const verb = s.match(FIX_VERBS);
+  if (verb) return { tier: 'likely', evidence: `"${verb[0]}" + "${noun[0]}"` };
+  return { tier: 'mentioned', evidence: `mentions "${noun[0]}" with no fix verb` };
+}
+
+function _gitLog(scanRoot, { maxCommits, timeoutMs }) {
+  // NUL-delimited records so subjects containing newlines cannot split a
+  // record — a commit message is arbitrary user text and must not be able to
+  // forge a record boundary.
+  const out = execFileSync('git', [
+    '-C', scanRoot, 'log', '-n', String(maxCommits), '--no-merges', '--no-color',
+    '--name-only', '--format=%x00%H%x1f%aI%x1f%s',
+  ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  const commits = [];
+  for (const block of out.split('\0')) {
+    if (!block.trim()) continue;
+    const nl = block.indexOf('\n');
+    const header = nl === -1 ? block : block.slice(0, nl);
+    const [sha, date, ...rest] = header.split('\x1f');
+    if (!sha) continue;
+    const files = nl === -1 ? [] : block.slice(nl + 1).split('\n').map(l => l.trim()).filter(Boolean);
+    commits.push({ sha, date: date || null, subject: rest.join('\x1f') || '', files });
+  }
+  return commits;
+}
+
+/**
+ * Mine history for security-relevant commits and turn them into per-file priors.
+ *
+ * @returns {{available:boolean, reason:string|null, commitsScanned:number,
+ *            byTier:object, hotspots:Array, commits:Array}}
+ */
+export function mineVulnHistory(scanRoot, { maxCommits = 500, timeoutMs = 30000, maxHotspots = 25, minConcentration = 0.15 } = {}) {
+  const empty = {
+    available: false, reason: null, commitsScanned: 0,
+    byTier: { identified: 0, likely: 0, mentioned: 0 }, hotspots: [], commits: [],
+  };
+  if (!scanRoot) return { ...empty, reason: 'no scan root' };
+
+  let commits;
+  try {
+    commits = _gitLog(scanRoot, { maxCommits, timeoutMs });
+  } catch (e) {
+    // Not a repository, git absent, shallow clone, timeout — all "no history
+    // available", never an error that fails a scan.
+    return { ...empty, reason: `git history unavailable: ${String(e.message || e).split('\n')[0]}` };
+  }
+
+  const byTier = { identified: 0, likely: 0, mentioned: 0 };
+  const perFile = new Map();
+  const matched = [];
+
+  const _file = (f) => {
+    let e = perFile.get(f);
+    if (!e) { e = { file: f, identified: 0, likely: 0, mentioned: 0, totalCommits: 0, subjects: [] }; perFile.set(f, e); }
+    return e;
+  };
+
+  // Total touches first, across EVERY commit. Without this the ranking rewards
+  // churn: a release commit whose subject says "fix XSS ..." also touches the
+  // changelog, the manifest and the version file, so the most-edited files in
+  // the repository float to the top of a raw count and the actual vulnerable
+  // source is buried. Measured on this repository, the raw ranking returned
+  // CLAUDE.md and package.json as the top two hotspots.
+  for (const c of commits) for (const f of c.files) _file(f).totalCommits++;
+
+  for (const c of commits) {
+    const cls = classifyCommit(c.subject);
+    if (!cls) continue;
+    byTier[cls.tier]++;
+    matched.push({ sha: c.sha.slice(0, 12), date: c.date, subject: c.subject, tier: cls.tier, evidence: cls.evidence, files: c.files.length });
+    for (const file of c.files) {
+      const e = _file(file);
+      e[cls.tier]++;
+      // Keep a bounded sample of the evidence, so a hotspot can be judged
+      // without re-reading the log.
+      if (e.subjects.length < 5) e.subjects.push({ sha: c.sha.slice(0, 12), tier: cls.tier, subject: c.subject });
+    }
+  }
+
+  const hotspots = [...perFile.values()]
+    // `mentioned` deliberately does NOT contribute to the ranking weight. It is
+    // the tier most likely to be wrong, so letting it rank files would sort by
+    // classifier error. It is still reported per file so a reader can see it.
+    .map(e => {
+      const weight = e.identified * 3 + e.likely;
+      // What fraction of this file's history is security work. A file touched
+      // by 200 commits of which 3 were security fixes is not a hotspot; one
+      // touched 4 times, 3 of them security fixes, is.
+      const concentration = e.totalCommits ? (e.identified + e.likely) / e.totalCommits : 0;
+      return { ...e, weight, concentration: Number(concentration.toFixed(3)) };
+    })
+    .filter(e => e.weight > 0 && e.concentration >= minConcentration)
+    // Rank by concentration first: it is the churn-corrected signal. Weight
+    // breaks ties so that, among equally-concentrated files, more security
+    // history ranks higher.
+    .sort((a, b) => b.concentration - a.concentration || b.weight - a.weight || (a.file < b.file ? -1 : 1))
+    .slice(0, maxHotspots);
+
+  return {
+    available: true,
+    reason: null,
+    commitsScanned: commits.length,
+    // Stated so a reader knows whether they are looking at all of history.
+    truncated: commits.length >= maxCommits,
+    byTier,
+    hotspots,
+    commits: matched.slice(0, 100),
+  };
+}
+
+/**
+ * Attach the historical prior to findings whose file is a hotspot.
+ * Advisory only: never changes severity, never removes anything.
+ */
+export function annotateHistoricalRisk(findings, history) {
+  if (!Array.isArray(findings) || !history?.available) return 0;
+  const byFile = new Map(history.hotspots.map(h => [h.file, h]));
+  let n = 0;
+  for (const f of findings) {
+    const h = f && f.file ? byFile.get(f.file) : null;
+    if (!h) continue;
+    f.historicalRisk = {
+      priorSecurityFixes: h.identified + h.likely,
+      identified: h.identified,
+      likely: h.likely,
+      note: 'advisory prior from git history — not evidence about this finding',
+    };
+    n++;
+  }
+  return n;
+}
+
+/** One-line summary; null when there is no history to report. */
+export function renderArchaeology(h) {
+  if (!h) return null;
+  if (!h.available) return `vulnerability archaeology: skipped (${h.reason}).`;
+  const { identified, likely, mentioned } = h.byTier;
+  if (!identified && !likely && !mentioned) {
+    return `vulnerability archaeology: no security-relevant commits in the last ${h.commitsScanned}.`;
+  }
+  return `vulnerability archaeology: ${identified} CVE-identified, ${likely} likely and ${mentioned} `
+    + `merely-mentioning commit(s) across ${h.commitsScanned} scanned${h.truncated ? ' (history truncated)' : ''}; `
+    + `${h.hotspots.length} file hotspot(s). Ranking ignores the "mentioned" tier — it is the least reliable.`;
+}
+
+export const _internals = { CVE_RE, FIX_VERBS, VULN_NOUNS, NON_FIX_RE, _gitLog };

package/src/report/index.js

@@ -3,6 +3,7 @@ import * as crypto from 'node:crypto';
 import { _isCustomSuppressed } from '../engine.js';
 import { alertFace, approveFace } from './mascot.js';
 import { SCANNER_VERSION } from '../posture/version.js';
+import { proofBlock } from '../posture/proof-artifact.js';
 
 const SEV_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 const SEV_TO_SARIF = { critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'none' };
@@ -412,6 +413,13 @@ export function toJSON(scan, meta={}, opts={}){
     // It carries its own `proves` / `doesNotProve` statement — do not quote
     // the digest as cross-machine reproducibility, which it is not.
     attestation: scan.attestation || null,
+    // Coverage reduction, surfaced in the ARTIFACT. `disable:` in rules.yml
+    // removes findings from the report, and a removed finding is
+    // indistinguishable from clean code unless the removal is stated. Null when
+    // nothing was suppressed, so consumers can omit the section rather than
+    // render an empty one. An AUTHORISED suppression is reported too — the
+    // signature proves who asked for it, not that the results are absent.
+    suppressedRules: scan.suppressedRules || null,
     _scanMeta: scan._scanMeta || null,
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];
@@ -702,6 +710,14 @@ export function toSARIF(scan, meta={}){
           // (verified | unsigned | pass-through). The legacy bool flags are
           // emitted alongside for one release of grace so existing dashboards
           // don't break; new integrations should switch to signatureStatus.
+          // PRD Epic 1.4 / 7.4 — the proof block. `proofLevel` is the
+          // reader-facing vocabulary (PROVEN / PROBABLE_FP / REACHABLE /
+          // PATTERN); `proofArtifactSha256` commits to the evidence that
+          // justified it, so a fix PR can reference the artifact it was
+          // reviewed against. Omitted entirely when the proof stage did not
+          // run — labelling every finding PATTERN would assert each was
+          // considered and found unprovable.
+          ...(proofBlock(f) || {}),
           signatureStatus: f.signatureStatus || (f._passThroughSigning ? 'pass-through' : (f._unsigned ? 'unsigned' : 'verified')),
           ...(f._unsigned ? { unsigned: true } : {}),
           ...(f._passThroughSigning ? { passThroughSigning: true } : {}),

package/src/sandbox/CLAUDE.md

@@ -164,11 +164,33 @@ write succeeds, out-of-root write is blocked and creates no file, a denied
 write is not reported as a clean run, the confined process cannot rebind the
 filesystem writable again, an ordinary non-zero exit stays `nonzero` rather
 than `blocked`, the parent environment is not handed over, outbound network is
-blocked, and a wall-clock overrun stops the direct child.
-
-Two limits carry over unchanged and are **not** claims this verification
-retires. The wall-clock case stops the *direct child*, not the process tree —
-the same caveat the userspace backend carries. And this is one kernel and one
+blocked, and the wall-clock behaviour is pinned as a KNOWN GAP (see below —
+the timeout does not actually stop the payload here).
+
+**The timeout: two wrong claims, settled by two CI runs.** This guide once
+carried the userspace caveat verbatim ("stops the direct child, not the process
+tree") and `backend-namespace.js` went further, reasoning that killing pid 1 of a
+PID namespace would reap everything and beat userspace. A test was added to check
+rather than assume, and CI corrected it twice:
+
+1. With the default **SIGTERM** the timeout did nothing: a 1200 ms budget against
+   a payload sleeping 30 s returned after `30057 ms`, payload run to completion.
+   The kernel drops default-action signals sent to a PID namespace's pid 1 from
+   outside it.
+2. With **SIGKILL** — which cannot be ignored — the call returns in about 1.2 s,
+   so the direct child IS bounded. A backgrounded grandchild still survived and
+   wrote its marker.
+
+**Settled behaviour: SIGKILL bounds the direct child promptly; it does not reap
+the process tree.** That is the same limitation the userspace backend carries —
+not better, which is what this module claimed for a long time. Confinement is
+unaffected: survivors stay inside the mount and network namespaces and can
+neither write out of root nor reach the network. What is missing is a bound on
+how long descendants run, so a caller needing one must impose it itself
+(`posture/prove-findings.js` does). Pinned by "KNOWN GAP: the timeout bounds the
+direct child but does NOT reap the tree", which fails in both directions.
+
+One further limit is unchanged: this is one kernel and one
 image: a different kernel is a different host fact, which is exactly why the
 job runs per push rather than being recorded once and trusted forever.
 

package/src/sandbox/backend-namespace.js

@@ -62,17 +62,32 @@
 // expectation that "the remount should have worked" is exactly the class of
 // claim this module exists to refuse.
 //
-// TIMEOUT SCOPE. The wall-clock timeout is `spawnSync`'s, which signals only
-// the direct child. On this backend the direct child is the namespace tool
-// running as pid 1 of a new PID namespace (`--pid --fork`), so killing it is
-// expected to take the whole namespace's processes with it — better than the
-// userspace backend, where a backgrounded grandchild demonstrably survives.
-// "Expected", NOT verified, and this one did not clear with the rest: the
-// escape suite has now RUN and passed on a Linux runner, but its wall-clock
-// case asserts only that the DIRECT CHILD is stopped. No test observes whether
-// a backgrounded grandchild dies with the PID namespace, so tree-kill remains
-// a reasoned expectation. Do not state it as a guarantee until a test asserts
-// the grandchild is gone.
+// TIMEOUT SCOPE — SETTLED BY TWO CI RUNS, AFTER TWO WRONG CLAIMS.
+//
+// This comment asserted for a long time that killing the direct child would
+// reap the whole namespace, since that child is pid 1 of a new PID namespace
+// (`--pid --fork`) — and that this made the backend BETTER than the userspace
+// one. A test was written to check rather than assume. What CI actually found,
+// in two rounds:
+//
+//   1. With the default SIGTERM the timeout did nothing at all: a 1200 ms
+//      budget against a payload sleeping 30 s returned after `30057 ms`, having
+//      run the payload to completion. The kernel does not deliver
+//      default-action signals to a PID namespace's pid 1 from outside it, so
+//      with no handler installed SIGTERM is simply dropped.
+//   2. With `killSignal: 'SIGKILL'` — which cannot be ignored — the call
+//      returns in about 1.2 s. The DIRECT CHILD is bounded. But a backgrounded
+//      grandchild still outlived it and wrote its marker, so the PID namespace
+//      does NOT reap the tree here.
+//
+// Settled: SIGKILL bounds the direct child promptly; it does not kill the tree.
+// That is the SAME limitation the userspace backend carries, not an improvement
+// on it. Confinement is unaffected — survivors remain inside the mount and
+// network namespaces and can neither write out of root nor reach the network —
+// but there is no bound on how long descendants run, and any caller needing one
+// must impose it (see `posture/prove-findings.js`, which does). Pinned by
+// "KNOWN GAP: the timeout bounds the direct child but does NOT reap the tree"
+// in `sandbox-escape.test.js`, which fails in both directions.
 //
 // PRIVILEGE. Creating mount/PID/IPC/UTS/network namespaces directly requires
 // CAP_SYS_ADMIN, which an ordinary CI account does not have — asking for them
@@ -293,6 +308,19 @@ export function runNamespace(argv, {
       {
         encoding: 'utf8',
         timeout: timeoutMs,
+        // SIGKILL, not the SIGTERM default, and this is the whole reason the
+        // timeout did not work here. The direct child is pid 1 of a new PID
+        // namespace (`--pid --fork`), and the kernel does not deliver
+        // default-action signals to a namespace's pid 1 from outside it — a
+        // process with no handler installed for SIGTERM simply does not die.
+        // SIGKILL is the one signal that cannot be ignored or blocked, so it
+        // is the only signal that can bound a payload here.
+        //
+        // Found by CI, not by reasoning: the first Linux run of the tree-kill
+        // test recorded duration_ms 30057 against a 1200 ms budget with the
+        // payload run to completion. The comment above this function used to
+        // claim the opposite.
+        killSignal: 'SIGKILL',
         maxBuffer,
         cwd: resolvedRoot,
         env: {