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

package/src/posture/fix-verify.js

@@ -21,6 +21,7 @@ import * as path from 'node:path';
 import { runFullScan } from '../engine.js';
 import { gateFixOutput } from './fix-honesty-gate.js';
 import { runProjectTests } from './test-runner.js';
+import { recordFixAttempt } from './fix-metrics.js';
 
 const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 
@@ -164,10 +165,23 @@ export async function verifyFix({
   depFileContents,
   fixMeta,
   testTimeoutMs,
+  recordMetrics = true,
+  poc,
 } = {}) {
+  // R5 (reporting half) — time each stage as it runs. Measured here rather
+  // than inside each stage because only this function knows the boundaries of
+  // one verification ATTEMPT, which is the unit the distribution is over.
+  const stages = {};
+  const t0 = Date.now();
+  let mark = t0;
+  const _lap = (name) => { const now = Date.now(); stages[name] = now - mark; mark = now; };
+
   const rescan = await verifyPatch({ scanRoot, originalFindingStableId, files, depFileContents });
+  _lap('rescan');
   const lint = runProjectLinter(scanRoot, Object.keys(files || {}));
+  _lap('lint');
   const tests = runProjectTests(scanRoot, testTimeoutMs != null ? { timeoutMs: testTimeoutMs } : {});
+  _lap('tests');
   // True when a candidate patch was supplied but has not been written, so the
   // suite necessarily ran against the pre-patch tree. Surfaced in the summary
   // and on the result so a caller cannot mistake it for a verified patch.
@@ -177,7 +191,39 @@ export async function verifyFix({
   if (fixMeta && typeof fixMeta === 'object') {
     try { honesty = gateFixOutput(fixMeta); } catch { honesty = null; }
   }
-  const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && (honesty ? honesty.ok : true);
+  _lap('honesty');
+
+  // R5 — the PoC leg. Re-run the finding's proof-of-concept against the
+  // CANDIDATE patch inside R1's sandbox. A patch that still lets the PoC
+  // demonstrate the predicted effect has not fixed anything, however green the
+  // re-scan looks: the re-scan only proves the DETECTOR stopped firing, which
+  // a cosmetic edit can achieve. Execution is the stronger claim.
+  //
+  // Direction matters and is asymmetric on purpose. `execution-proven` after
+  // the patch is a hard FAIL. Anything else is NOT a pass — a PoC that failed
+  // to run, or a sandbox that could not start, is recorded as `inconclusive`
+  // and left out of the verdict entirely. Treating "could not prove it" as
+  // "fixed" is exactly the false confidence this leg exists to prevent.
+  let pocLeg = { status: 'not-requested', reason: null, tier: null };
+  if (poc?.code) {
+    try {
+      const { proveFinding } = await import('./execution-proof.js');
+      const proved = await proveFinding({ ...(poc.finding || {}), poc }, { files });
+      const tier = proved.proofTier;
+      pocLeg = tier === 'execution-proven'
+        ? { status: 'still-exploitable', tier, reason: proved.proofEvidence?.observed || null }
+        : proved.proofEvidence?.ran
+          ? { status: 'no-longer-proven', tier, reason: proved.proofEvidence?.reason || null }
+          : { status: 'inconclusive', tier, reason: proved.proofEvidence?.reason || null };
+    } catch (e) {
+      pocLeg = { status: 'inconclusive', tier: null, reason: `proof harness error: ${e.message}` };
+    }
+  }
+  _lap('poc');
+  const pocOk = pocLeg.status !== 'still-exploitable';
+
+  const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && pocOk && (honesty ? honesty.ok : true);
+  const durations = { ...stages, totalMs: Date.now() - t0 };
   const summary = [
     `re-scan: ${rescan.ok ? 'PASS' : 'FAIL — ' + rescan.reason}`,
     `linter:  ${lint.runner === 'none' ? 'skipped (no linter config)'
@@ -193,6 +239,34 @@ export async function verifyFix({
               : tests.passed ? `PASS${_testedPrePatch ? ' — on the CURRENT on-disk tree, NOT the candidate patch' : ''}`
               : `FAIL (exit ${tests.exitCode})`}`,
     honesty ? `honesty: ${honesty.ok ? `PASS (${honesty.tier})` : 'FAIL — ' + honesty.violations.join('; ')}` : null,
+    // Never render `inconclusive` as a pass — say plainly that nothing was proven.
+    pocLeg.status === 'not-requested' ? null
+      : pocLeg.status === 'still-exploitable' ? `poc:     FAIL — the proof-of-concept still demonstrates the vulnerability against the patch`
+      : pocLeg.status === 'no-longer-proven' ? 'poc:     PASS (ran against the patch and no longer demonstrates the vulnerability)'
+      : `poc:     inconclusive — not counted either way (${pocLeg.reason || 'no detail reported'})`,
   ].filter(Boolean).join('\n');
-  return { ok, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, summary };
+  // Persist the attempt so the distribution can be reported from real runs.
+  // `testsRan` is the load-bearing field: it is what keeps "verified with no
+  // test suite to run" out of the headline time-to-validated-fix bucket.
+  // A patch that was never written to disk is recorded too, but flagged — its
+  // suite ran against the pre-patch tree, so its timing is real while its
+  // verdict is about a different tree.
+  if (recordMetrics && scanRoot) {
+    recordFixAttempt(scanRoot, {
+      at: new Date().toISOString(),
+      stableId: originalFindingStableId || null,
+      ok,
+      testsRan: !tests.skipped,
+      testsPassed: tests.skipped ? null : tests.passed === true,
+      testedPrePatch: _testedPrePatch,
+      lintRan: !(lint.skipped || lint.runner === 'none'),
+      honestyGated: honesty != null,
+      pocStatus: pocLeg.status,
+      files: Object.keys(files || {}).length,
+      stages,
+      totalMs: durations.totalMs,
+    });
+  }
+
+  return { ok, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, poc: pocLeg, durations, summary };
 }

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