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

package/src/posture/integrity.js

@@ -33,16 +33,23 @@ function _keyDir() {
 }
 function _keyPath() { return path.join(_keyDir(), 'scan-key'); }
 
+// Where the active key came from. A signature is only as meaningful as the key
+// behind it, and `env` means "whoever set the environment could sign this" —
+// a reader of a scan artifact deserves to know which case they are in.
+let _keySource = null;
+export function keyProvenance() { return _keySource || 'unresolved'; }
+
 function _readOrGenerateKey() {
   const fromEnv = process.env.AGENTIC_SECURITY_HMAC_KEY;
   if (fromEnv && /^[0-9a-fA-F]{32,}$/.test(fromEnv.trim())) {
+    _keySource = 'env';
     return Buffer.from(fromEnv.trim(), 'hex');
   }
   const fp = _keyPath();
   try {
     if (fs.existsSync(fp)) {
       const hex = fs.readFileSync(fp, 'utf8').trim();
-      if (/^[0-9a-fA-F]{32,}$/.test(hex)) return Buffer.from(hex, 'hex');
+      if (/^[0-9a-fA-F]{32,}$/.test(hex)) { _keySource = 'per-install'; return Buffer.from(hex, 'hex'); }
     }
   } catch { /* fall through to generate */ }
   // Generate, mode 0600.
@@ -50,13 +57,39 @@ function _readOrGenerateKey() {
   try {
     fs.mkdirSync(_keyDir(), { recursive: true, mode: 0o700 });
     fs.writeFileSync(fp, buf.toString('hex') + '\n', { mode: 0o600 });
-  } catch { /* best-effort — fall back to in-memory key for the process */ }
+    _keySource = 'per-install-new';
+  } catch {
+    // Could not persist — this key lives for this process only, so nothing
+    // signed with it will verify on any later run. Callers must be able to see
+    // that, or a permanently-unverifiable signature looks like a valid one.
+    _keySource = 'ephemeral';
+  }
   return buf;
 }
 
-function _legacyHostnameKey() {
-  return crypto.createHash('sha256').update(`${_HMAC_SALT}:${os.hostname()}`).digest();
-}
+// REMOVED (2026-08-08): the legacy hostname-derived key.
+//
+// It was `sha256(_HMAC_SALT + ':' + os.hostname())`. `_HMAC_SALT` is a constant
+// in published, npm-shipped source and a hostname is not a secret — it appears
+// in CI logs, build artifacts and error messages. So the "signature" could be
+// forged by anyone who knew the target's hostname, which is to say by anyone.
+//
+// This was known. The 0.62.0 changelog introduced the per-install key precisely
+// because the old one was "hostname-derived and publicly forgeable in CI /
+// containers", and kept verification of the legacy key "for one release to
+// migrate existing signed scans". The comment here said "Remove after one minor
+// release." It was still accepted at 0.132.0 — SEVENTY minor releases later.
+//
+// What it cost: `rule-overrides.js` gates the `disable:` list on
+// `verifyLastScan`, so a forged signature silently switched off arbitrary
+// detectors and the scan reported clean. Demonstrated end to end before removal:
+// with a hostname-forged `rules.yml.sig`, a command-injection finding went from
+// 1 reported to 0.
+//
+// A migration window that nobody closes is not a migration window; it is the
+// vulnerability, kept on purpose. Signatures made under the legacy key no longer
+// verify — that is the intended consequence. Re-sign with `agentic-security
+// rules sign`.
 
 let _cachedKey = null;
 function _key() {
@@ -85,13 +118,13 @@ export function verifyLastScan(body, sigFile) {
       return crypto.timingSafeEqual(Buffer.from(stored, 'hex'), Buffer.from(expected, 'hex'));
     } catch { return false; }
   };
+  // ONE key. There is deliberately no fallback: a second accepted key is a
+  // second thing that can be forged, and the last one was forgeable by anyone
+  // who could read a hostname.
   if (tryKey(_key())) return true;
-  // Legacy hostname-key path — accepted for verification only, not for new
-  // signatures. Remove after one minor release.
-  if (tryKey(_legacyHostnameKey())) return true;
   return false;
 }
 
 // Test-only helpers (premortem-tracked):
-export function _resetKeyCacheForTests() { _cachedKey = null; }
+export function _resetKeyCacheForTests() { _cachedKey = null; _keySource = null; }
 export function _keyFilePathForTests() { return _keyPath(); }

package/src/posture/learning.js

@@ -90,7 +90,14 @@ export function applyFeedback(scanRoot, findings) {
   if (process.env.AGENTIC_SECURITY_LEARN !== '1') return { kept: findings, suppressed };
   const data = loadFeedback(scanRoot);
   if (!data.entries || !data.entries.length) return { kept: findings, suppressed };
-  const quorum = Math.max(1, parseInt(process.env.AGENTIC_SECURITY_LEARN_QUORUM || '2', 10));
+  // Floor of 2, not 1. A quorum of 1 means a SINGLE triage verdict suppresses a
+  // finding — and because suppression also matches on `family + filePattern`
+  // below, one verdict can silence a whole family across a path. That is
+  // precisely the case the root CLAUDE.md warns about ("think about what a
+  // malicious-PR-author could suppress"), and clamping to 1 let an env var
+  // request it. A value below 2 is now raised to 2 rather than honoured.
+  const _requested = parseInt(process.env.AGENTIC_SECURITY_LEARN_QUORUM || '2', 10);
+  const quorum = Number.isFinite(_requested) ? Math.max(2, _requested) : 2;
   // Keep the most recent 500 entries by `at`.
   const sorted = [...data.entries].sort((a, b) => String(a.at || '').localeCompare(String(b.at || ''))).slice(-500);
   const fpCountById = new Map();

package/src/posture/model-routing.js

@@ -1,3 +1,4 @@
+import { applyMeasuredTrust } from './model-trust.js';
 // Capability-based model routing for cost-sensitive subagent dispatch.
 //
 // A declarative CWE/severity → model policy. When the orchestrator is about to
@@ -105,6 +106,31 @@ export function routeModelForFinding(finding) {
     reason: `${cwe ? `${cwe} at ` : ''}${severity || 'low'} severity is a simple / hardening class — ${LABEL[MODEL_CHEAPEST]} at low effort.` };
 }
 
+// R13 — measured trust, layered over the capability policy above.
+//
+// The policy is a set of hand-written beliefs about which classes are hard.
+// This lets a class be downgraded to the cheapest model ONLY once that model's
+// measured miss rate clears a Wilson 95% upper bound for that class. The
+// capability route is the floor: measured evidence can permit a downgrade the
+// policy already allows, never promote a class the policy thinks is hard.
+//
+// Without a ledger the behaviour is byte-identical to before — no evidence is
+// not permission, and the default remains the stronger model.
+export function trustKeyFor(finding) {
+  return `${MODEL_CHEAPEST}::${parseCwe(finding?.cwe) || 'no-cwe'}::${(finding?.severity || 'unknown').toLowerCase()}`;
+}
+
+export function routeModelWithTrust(finding, ledger = null) {
+  const route = routeModelForFinding(finding);
+  if (!ledger || route.model === MODEL_CHEAPEST) return { ...route, trust: null };
+  return applyMeasuredTrust(
+    route,
+    { model: MODEL_CHEAPEST, effort: 'low' },
+    ledger,
+    trustKeyFor(finding),
+  );
+}
+
 // Route a list of findings. Returns [{ finding, model, effort, reason }, …].
 export function routeModelForFindings(findings) {
   const list = Array.isArray(findings) ? findings : [];

package/src/posture/model-trust.js

@@ -0,0 +1,174 @@
+// R13 — multi-model routing gated on MEASURED trust.
+//
+// `model-routing.js` already routes by capability: crypto and auth go to the
+// strongest model, hardening to the cheapest. That policy is a set of
+// hand-written beliefs about which classes are hard. It has never been checked
+// against what the cheap model actually gets wrong.
+//
+// This module supplies the check. A decision class may be downgraded to a
+// cheaper model only once that model's measured MISS RATE clears a statistical
+// bound — specifically the Wilson 95% UPPER bound, not the point estimate.
+//
+// WHY THE UPPER BOUND, AND WHY THAT IS THE WHOLE IDEA. "0 misses in 5 samples"
+// has a point estimate of 0% and looks perfect. Its Wilson upper bound is
+// about 52%: the data is equally consistent with a model that misses half the
+// time. Routing on the point estimate would let five lucky samples hand a
+// security decision to a model that fails constantly. The upper bound is what
+// converts "we have not seen it fail" into "we have enough evidence that it
+// rarely fails", and it is precisely what makes small-n evidence unusable
+// rather than flattering. Small n cannot clear a tight threshold at all — that
+// is the feature, not a limitation to engineer around.
+//
+// FAIL CLOSED. No evidence for a class means no downgrade. The expensive model
+// is the safe default, so absence of data must never read as permission. This
+// is the same rule as everywhere else here: an unverified check is not a pass.
+//
+// A MISS IS ASYMMETRIC. `record()` takes agreement with the trusted model, and
+// what is counted is DISAGREEMENT WHERE THE CHEAP MODEL WAS WRONG — a missed
+// true positive. A cheap model that is merely noisier (extra false positives)
+// costs triage time; one that misses real vulnerabilities costs a breach. Only
+// the second gates routing.
+
+// STATUS — MECHANISM ONLY. Nothing in `src/` or `bin/` constructs a ledger, and
+// nothing calls `record()`: there is no adjudication source comparing a cheap
+// model's verdicts against a trusted model's, so no class ever accumulates
+// evidence. The consequence is benign, because the design fails closed — with
+// no observations every class stays on the stronger model — but this is a
+// mechanism waiting for data, not a working routing capability. Do not describe
+// it as one until something feeds it.
+
+import { wilsonInterval } from './calibration.js';
+
+// The default bar a cheap model must clear: its true miss rate must be below
+// 5% with 95% confidence. Deliberately strict — this gates security decisions,
+// and the cost of being wrong is a missed vulnerability, not a wasted token.
+export const DEFAULT_MAX_MISS_RATE = 0.05;
+
+// Below this, no bound is tight enough to matter and we refuse on principle
+// rather than letting an unusually clean run through on a technicality.
+export const MIN_SAMPLES = 30;
+
+/**
+ * An observation ledger, keyed by decision class.
+ *
+ * A "decision class" is whatever granularity routing decides at — this module
+ * does not impose one. `model-routing.js` decides by CWE family and severity,
+ * so `${model}::${cwe}` is the natural key there.
+ */
+export function createTrustLedger({ maxMissRate = DEFAULT_MAX_MISS_RATE, minSamples = MIN_SAMPLES } = {}) {
+  /** @type {Map<string, {n:number, misses:number}>} */
+  const classes = new Map();
+
+  function _get(key) {
+    let c = classes.get(key);
+    if (!c) { c = { n: 0, misses: 0 }; classes.set(key, c); }
+    return c;
+  }
+
+  return {
+    maxMissRate,
+    minSamples,
+
+    /**
+     * Record one adjudicated decision.
+     * @param {string}  key    decision class
+     * @param {boolean} missed did the cheap model MISS something the trusted
+     *                         model caught? Extra false positives are not misses.
+     */
+    record(key, missed) {
+      if (typeof key !== 'string' || !key) return false;
+      const c = _get(key);
+      c.n++;
+      if (missed) c.misses++;
+      return true;
+    },
+
+    observations(key) {
+      const c = classes.get(key);
+      return c ? { ...c } : { n: 0, misses: 0 };
+    },
+
+    /**
+     * May this class be routed to the cheaper model?
+     * @returns {{allowed:boolean, reason:string, n:number, misses:number,
+     *            missRate:number|null, upperBound:number|null}}
+     */
+    verdict(key) {
+      const { n, misses } = this.observations(key);
+      if (n < minSamples) {
+        return {
+          allowed: false, n, misses, missRate: n ? misses / n : null, upperBound: null,
+          reason: `only ${n} adjudicated sample(s) for '${key}'; ${minSamples} are required before a `
+            + 'downgrade can be justified. No evidence is not permission — the stronger model stands.',
+        };
+      }
+      // wilsonInterval is written for a SUCCESS count; the miss rate's interval
+      // is the same computation with misses as the successes.
+      const [, upper] = wilsonInterval(misses, n);
+      const missRate = misses / n;
+      if (upper > maxMissRate) {
+        return {
+          allowed: false, n, misses, missRate, upperBound: upper,
+          reason: `measured miss rate ${(missRate * 100).toFixed(1)}% over ${n} samples, but the 95% upper `
+            + `bound is ${(upper * 100).toFixed(1)}% — above the ${(maxMissRate * 100).toFixed(1)}% bar. `
+            + 'The point estimate is not the claim; the data is still consistent with a worse model.',
+        };
+      }
+      return {
+        allowed: true, n, misses, missRate, upperBound: upper,
+        reason: `${misses} miss(es) in ${n} samples; 95% upper bound ${(upper * 100).toFixed(1)}% is within the `
+          + `${(maxMissRate * 100).toFixed(1)}% bar, so the cheaper model is justified for '${key}'.`,
+      };
+    },
+
+    /** Every class with its verdict, for reporting. */
+    report() {
+      const out = {};
+      for (const key of [...classes.keys()].sort()) out[key] = this.verdict(key);
+      return out;
+    },
+  };
+}
+
+/**
+ * Apply measured trust on top of a capability route.
+ *
+ * The capability route is the FLOOR, never overridden upward by this module:
+ * measured trust can only permit a downgrade that policy already proposed, it
+ * cannot promote a class the policy thinks is hard. Evidence about a cheap
+ * model's miss rate says nothing about whether a hard class deserves a strong
+ * one.
+ *
+ * @param {object} route     from routeModelForFinding: {model, effort, reason}
+ * @param {object} proposal  the cheaper alternative: {model, effort}
+ * @param {object} ledger    createTrustLedger()
+ * @param {string} key       decision class
+ */
+export function applyMeasuredTrust(route, proposal, ledger, key) {
+  if (!route || !proposal || !ledger) return { ...route, trust: null };
+  const v = ledger.verdict(key);
+  if (!v.allowed) {
+    return {
+      ...route,
+      trust: { ...v, applied: false },
+      reason: `${route.reason} Downgrade withheld: ${v.reason}`,
+    };
+  }
+  return {
+    model: proposal.model,
+    effort: proposal.effort ?? route.effort,
+    trust: { ...v, applied: true },
+    reason: `Downgraded to ${proposal.model} on measured evidence: ${v.reason}`,
+  };
+}
+
+/** One-line summary of a trust report. */
+export function renderTrustSummary(report) {
+  const keys = Object.keys(report || {});
+  if (!keys.length) return null;
+  const allowed = keys.filter(k => report[k].allowed);
+  const short = keys.filter(k => report[k].n < MIN_SAMPLES);
+  return `measured-trust routing: ${allowed.length}/${keys.length} class(es) cleared the `
+    + `95% upper-bound bar; ${short.length} still below the ${MIN_SAMPLES}-sample minimum `
+    + '(those keep the stronger model).';
+}

package/src/posture/poc-inprocess.js

@@ -0,0 +1,165 @@
+// In-process proof-of-concept synthesis (R2 — closing the automatic loop).
+//
+// WHY A SECOND POC KIND. `poc-generator.js` emits *HTTP* PoCs: they take a URL
+// and a param and hit a running server. Those are the right artifact for a
+// human reproducing a bug against a deployed app, but they cannot be executed
+// by `execution-proof.js` — the sandbox denies network egress and there is no
+// server inside it. That is the concrete reason nothing in the scan pipeline
+// ever produced an `execution-proven` finding: the PoCs it generated were
+// unrunnable *by construction* in the only place proofs are allowed to run.
+//
+// This module emits the other kind: a self-contained script that imports the
+// vulnerable file directly, calls the exported handler with a crafted request,
+// and lets the injected payload write the proof marker. No server, no network,
+// no fixture discovery.
+//
+// DELIBERATELY NARROW. It refuses far more than it accepts, and that is the
+// design rather than a gap to close later. A PoC that runs but proves nothing
+// is worse than no PoC: `proof-failed` is a triage signal about the FINDING,
+// so a template that misfires manufactures evidence against real bugs. Every
+// refusal below is a case where the generated script would have been a guess.
+//
+// SAFETY. The payload is a shell redirect that creates a marker file inside
+// the sandbox root (`> PROVEN`). It is the least destructive thing that still
+// proves arbitrary command execution: no network, no writes outside the root,
+// no privilege attempts, and it is only ever executed inside R1's sandbox with
+// egress denied and the filesystem confined.
+
+const MARKER = 'PROVEN';
+
+// Only families where "the injected payload ran" is observable from a marker
+// file. Others (XSS, weak crypto) need a browser or a judgement call about
+// output, and a marker-file proof would be a category error.
+const SUPPORTED = new Set(['command-injection', 'code-injection']);
+
+const JS_EXT = /\.(js|cjs|mjs)$/i;
+
+// A handler we can call: `module.exports = function (req, res)` or
+// `module.exports.name = function (req, res)` / `exports.name = ...`.
+// Arrow and function forms both count. The two-parameter (req, res) shape is
+// required — a one-arg export is not an Express-style handler and calling it
+// with a fake request would be inventing an interface.
+const HANDLER_RES = [
+  /module\.exports\s*=\s*(?:async\s+)?function\s*\w*\s*\(\s*(\w+)\s*,\s*(\w+)\s*\)/,
+  /module\.exports\s*=\s*(?:async\s+)?\(\s*(\w+)\s*,\s*(\w+)\s*\)\s*=>/,
+];
+const NAMED_HANDLER_RES = [
+  /(?:module\.)?exports\.(\w+)\s*=\s*(?:async\s+)?function\s*\w*\s*\(\s*(\w+)\s*,\s*(\w+)\s*\)/,
+  /(?:module\.)?exports\.(\w+)\s*=\s*(?:async\s+)?\(\s*(\w+)\s*,\s*(\w+)\s*\)\s*=>/,
+];
+
+// The request property the handler reads. Anchored to the request identifier
+// the export actually binds, so a file that reads `req.query` while exporting
+// `(request, response)` does not produce a PoC built on the wrong name.
+function _requestSource(content, reqIdent) {
+  const esc = reqIdent.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  for (const prop of ['query', 'body', 'params']) {
+    const re = new RegExp(`\\b${esc}\\.${prop}\\.(\\w+)`);
+    const m = content.match(re);
+    if (m) return { prop, key: m[1] };
+  }
+  return null;
+}
+
+// The sink must interpolate into a SHELL, not an argv array. `exec`/`execSync`
+// run through a shell so `; > PROVEN` executes; `execFile`/`spawn` with an
+// array do not, and a marker PoC against those would fail for a reason that
+// has nothing to do with whether the finding is real.
+const SHELL_SINK = /\b(?:exec|execSync)\s*\(/;
+const ARGV_SINK = /\b(?:execFile|execFileSync|spawn|spawnSync)\s*\(/;
+
+/**
+ * Synthesize a sandbox-runnable PoC, or return a refusal explaining why not.
+ *
+ * @returns {{ok:true, poc:object} | {ok:false, reason:string}}
+ */
+export function synthesizeInProcessPoc(finding, fileContent) {
+  if (!finding || typeof finding !== 'object') return { ok: false, reason: 'no finding' };
+  if (!SUPPORTED.has(finding.family)) {
+    return { ok: false, reason: `family '${finding.family || 'unknown'}' has no marker-observable in-process template` };
+  }
+  if (!finding.file || !JS_EXT.test(finding.file)) {
+    return { ok: false, reason: 'in-process PoCs are JavaScript-only today' };
+  }
+  if (typeof fileContent !== 'string' || !fileContent.trim()) {
+    return { ok: false, reason: 'the vulnerable file content was not available' };
+  }
+  if (/^\s*(?:import|export)\s/m.test(fileContent) && !/module\.exports/.test(fileContent)) {
+    return { ok: false, reason: 'ES-module source: the CommonJS handler shapes do not apply' };
+  }
+
+  if (!SHELL_SINK.test(fileContent)) {
+    return {
+      ok: false,
+      reason: ARGV_SINK.test(fileContent)
+        ? 'the sink passes an argv array, so a shell-metacharacter payload would not execute — absence of proof here would say nothing about the finding'
+        : 'no shell-executing sink found in the file',
+    };
+  }
+
+  // Default export first, then a named one.
+  let call = null, reqIdent = null;
+  for (const re of HANDLER_RES) {
+    const m = fileContent.match(re);
+    if (m) { call = { kind: 'default', name: null }; reqIdent = m[1]; break; }
+  }
+  if (!call) {
+    for (const re of NAMED_HANDLER_RES) {
+      const m = fileContent.match(re);
+      if (m) { call = { kind: 'named', name: m[1] }; reqIdent = m[2]; break; }
+    }
+  }
+  if (!call) {
+    return { ok: false, reason: 'no exported two-argument (req, res) handler found — nothing to call without inventing an interface' };
+  }
+
+  const src = _requestSource(fileContent, reqIdent);
+  if (!src) {
+    return { ok: false, reason: `the handler does not read query/body/params off '${reqIdent}', so the injection point is unknown` };
+  }
+
+  const base = finding.file.split(/[\\/]/).pop();
+  const imported = call.kind === 'default' ? 'handler' : `{ ${call.name} }`;
+  const invoke = call.kind === 'default' ? 'handler' : call.name;
+
+  // The timer is unref'd so the process exits as soon as the handler responds.
+  // Without that it stays alive for the full timeout even after the exploit
+  // has landed, and on a loaded machine it can outlive the proof budget — at
+  // which point `attachProofTier` demotes a real proof to its static tier
+  // because `ran` is false. Correct, but it throws away a genuine result.
+  const code = [
+    `// Auto-generated in-process proof-of-concept for ${finding.file}.`,
+    '// Proves arbitrary command execution by having the injected payload',
+    `// create the marker file '${MARKER}' inside the sandbox root.`,
+    `import ${imported} from './${base}';`,
+    'await new Promise((resolve) => {',
+    '  const res = {',
+    '    send: () => resolve(), json: () => resolve(), end: () => resolve(),',
+    '    status: () => ({ send: () => resolve(), json: () => resolve(), end: () => resolve() }),',
+    '  };',
+    `  const req = { ${src.prop}: ${JSON.stringify({ [src.key]: `x; > ${MARKER}` })} };`,
+    `  try { ${invoke}(req, res); } catch { resolve(); }`,
+    '  setTimeout(resolve, 4000).unref();',
+    '});',
+  ].join('\n');
+
+  return {
+    ok: true,
+    poc: {
+      lang: 'js',
+      kind: 'in-process',
+      family: finding.family,
+      cwe: finding.cwe || null,
+      marker: MARKER,
+      paramKey: src.key,
+      paramSource: src.prop,
+      handler: call.kind === 'default' ? 'module.exports' : `exports.${call.name}`,
+      // The file the PoC imports. `execution-proof.js` materialises this into
+      // the sandbox root; without it the import fails and nothing is proved.
+      requires: [base],
+      code,
+    },
+  };
+}
+
+export const _internals = { MARKER, SUPPORTED, _requestSource };

package/src/posture/prove-findings.js

@@ -0,0 +1,148 @@
+// 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 } 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;
+
+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, {
+  fileContents = null, maxCandidates = DEFAULT_MAX, timeoutMs = 10000,
+  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 = {};
+    for (const rel of c.poc.requires || []) files[rel] = 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 };