@clear-capabilities/agentic-security-scanner 0.175.0 → 0.177.0

package/src/posture/fleet/lineage-summary.js

@@ -0,0 +1,55 @@
+// A bounded summary of one repository's Code Boundaries graph (the Data Flow Explorer's `DataFlowGraph v1`), for the enterprise graph
+// (PRD 4: "federate Code Boundaries across repositories"). The whole graph is not copied: a fleet of hundreds of repositories does not
+// need each node, only what crosses a repository boundary or changes what the organization knows about it:
+//   * the data classes that appear in the code (so a repository holding payment data is known to, even if the manifest forgot to say);
+//   * the external destinations the code sends data to, by host;
+//   * the queue topics it publishes to or consumes from;
+//   * the stores it touches, by host/database/table name;
+//   * counts, including flows that carry sensitive classes across a trust boundary.
+// Pure; hostile input (the graph came out of a scan of someone's code), so every string is bounded and shape-checked.
+const MAX_ITEMS = 64;
+const SENSITIVE = new Set(['pii', 'phi', 'pci', 'fin', 'credentials']);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const clean = (v, max = 120) => (typeof v === 'string' && v.length > 0 && v.length <= max && !/[\s\u0000-\u001f]/.test(v) ? v : null);
+
+function hostOf(literal) {
+  if (typeof literal !== 'string') return null;
+  try { const h = new URL(literal).hostname.toLowerCase(); return clean(h, 253); } catch { /* not a URL */ }
+  const bare = literal.toLowerCase().replace(/:\d+$/, '');
+  return /^[a-z0-9][a-z0-9.-]{0,252}$/.test(bare) ? bare : null;
+}
+
+export function summarizeLineage(graph) {
+  if (!graph || typeof graph !== 'object') return null;
+  const classes = new Set();
+  for (const d of arr(graph.dataElements)) for (const c of arr(d?.dataClasses)) { if (typeof c !== 'string') continue; const l = clean(c.toLowerCase(), 31); if (l && /^[a-z][a-z0-9-]*$/.test(l)) classes.add(l); }
+  const ext = new Map(); const queues = new Map(); const stores = new Map();
+  for (const n of arr(graph.nodes)) {
+    if (!n || typeof n !== 'object') continue;
+    if (n.kind === 'external') {
+      const host = hostOf(n.destination?.literalValue);
+      const key = `${n.subtype ?? 'external'}|${host ?? ''}`;
+      if (!ext.has(key) && ext.size < MAX_ITEMS) ext.set(key, { subtype: clean(n.subtype, 60) ?? 'external', host });
+    } else if (n.kind === 'queue') {
+      const topic = clean(n.queueDetail?.topic, 120); const op = n.queueDetail?.operation === 'consume' || n.queueDetail?.operation === 'receive' ? 'consume' : 'publish';
+      if (topic && queues.size < MAX_ITEMS) queues.set(`${topic}|${op}`, { topic, operation: op });
+    } else if (n.kind === 'store') {
+      const d = n.storeDetail ?? {};
+      const item = { subtype: clean(n.subtype, 60) ?? 'store', host: hostOf(d.host), database: clean(d.database, 120), table: clean(d.table, 120) };
+      const key = JSON.stringify(item);
+      if (stores.size < MAX_ITEMS) stores.set(key, item);
+    }
+  }
+  const edges = arr(graph.edges);
+  const crossing = new Set(edges.filter((e) => arr(e?.boundaryCrossings).length).map((e) => e.id));
+  const dataById = new Map(arr(graph.dataElements).map((d) => [d?.id, d]));
+  const sensitiveCrossing = arr(graph.flows).filter((f) => arr(f?.edgeIds).some((id) => crossing.has(id)) && arr(f?.dataElementIds).some((id) => arr(dataById.get(id)?.dataClasses).some((c) => SENSITIVE.has(String(c).toLowerCase())))).length;
+  return {
+    schema: 'agentic-security/fleet-lineage-summary', version: 1,
+    dataClasses: [...classes].sort().slice(0, MAX_ITEMS),
+    externalDestinations: [...ext.values()],
+    queues: [...queues.values()],
+    stores: [...stores.values()],
+    counts: { nodes: arr(graph.nodes).length, edges: edges.length, flows: arr(graph.flows).length, boundaryCrossingEdges: crossing.size, sensitiveFlowsCrossingBoundary: sensitiveCrossing },
+  };
+}

package/src/posture/fleet/org-health.js

@@ -0,0 +1,56 @@
+// Organization-level scan health (PRD 4, requirement 9). Pure.
+//
+//   Repositories requested: 1,250
+//   Complete: 1,228   Partial: 11   Failed: 6   Timed out: 5   Not run: ...
+//
+// The one rule: an organization is not GREEN while a required repository has no usable result. A repository that was requested but
+// has no job, was cancelled, is still queued or leased, failed or timed out is counted under its own heading and can never disappear
+// from the total. `partial` (the scan finished but the engine itself reported a degraded scan) keeps the organization out of GREEN
+// as well, because a partial scan is not evidence of a clean repository.
+//
+//   green      every required repository has a complete result and no optional repository has a problem
+//   degraded   every required repository has a result, but some result is partial, or an optional repository has a problem
+//   red        at least one required repository has no result
+import { isTerminal } from './job-store.js';
+
+export const ASSURANCE = Object.freeze(['green', 'degraded', 'red']);
+
+export function computeOrgHealth({ manifest, jobs }) {
+  const byRepo = new Map(jobs.map((j) => [j.repoId, j]));
+  const counts = { requested: manifest.repositories.length, complete: 0, partial: 0, failed: 0, timedOut: 0, cancelled: 0, notRun: 0 };
+  const repos = [];
+  for (const r of manifest.repositories) {
+    const j = byRepo.get(r.id);
+    let state;
+    if (!j) state = 'not-run';
+    else if (j.status === 'succeeded') state = 'complete';
+    else if (j.status === 'partial') state = 'partial';
+    else if (j.status === 'failed') state = 'failed';
+    else if (j.status === 'timed_out') state = 'timed-out';
+    else if (j.status === 'cancelled') state = 'cancelled';
+    else state = 'not-run'; // queued or leased: no result yet
+    counts[{ complete: 'complete', partial: 'partial', failed: 'failed', 'timed-out': 'timedOut', cancelled: 'cancelled', 'not-run': 'notRun' }[state]]++;
+    repos.push({ id: r.id, required: r.required, state, attempts: j?.attempts ?? 0, error: j?.error ?? null, cached: !!j?.summary?.cached, findings: j?.summary?.total ?? null, jobStatus: j?.status ?? null, finished: j ? isTerminal(j.status) : false });
+  }
+  const noResult = (x) => !['complete', 'partial'].includes(x.state);
+  const requiredMissing = repos.filter((x) => x.required && noResult(x));
+  const requiredPartial = repos.filter((x) => x.required && x.state === 'partial');
+  const optionalProblems = repos.filter((x) => !x.required && x.state !== 'complete');
+  const assurance = requiredMissing.length ? 'red' : (requiredPartial.length || optionalProblems.length) ? 'degraded' : 'green';
+  const reasons = [
+    ...(requiredMissing.length ? [`${requiredMissing.length} required ${requiredMissing.length === 1 ? 'repository has' : 'repositories have'} no result: ${requiredMissing.slice(0, 8).map((x) => `${x.id} (${x.state})`).join(', ')}${requiredMissing.length > 8 ? ', ...' : ''}`] : []),
+    ...(requiredPartial.length ? [`${requiredPartial.length} required ${requiredPartial.length === 1 ? 'repository was' : 'repositories were'} only partially scanned: ${requiredPartial.map((x) => x.id).join(', ')}`] : []),
+    ...(optionalProblems.length ? [`${optionalProblems.length} optional ${optionalProblems.length === 1 ? 'repository has' : 'repositories have'} a problem: ${optionalProblems.map((x) => `${x.id} (${x.state})`).join(', ')}`] : []),
+  ];
+  return { counts, assurance, reasons, repositories: repos };
+}
+
+const n = (x) => x.toLocaleString('en-US');
+export function renderOrgHealth(h) {
+  const c = h.counts;
+  const L = [`Repositories requested: ${n(c.requested)}`, `Complete: ${n(c.complete)}`, `Partial: ${n(c.partial)}`, `Failed: ${n(c.failed)}`, `Timed out: ${n(c.timedOut)}`];
+  if (c.cancelled) L.push(`Cancelled: ${n(c.cancelled)}`);
+  if (c.notRun) L.push(`Not run: ${n(c.notRun)}`);
+  L.push('', `Assurance: ${h.assurance.toUpperCase()}`, ...h.reasons.map((r) => `  ${r}`));
+  return L.join('\n');
+}

package/src/posture/fleet/scan-cache.js

@@ -0,0 +1,112 @@
+// The content-addressed scan cache (PRD 4, requirement 5). A repository's scan result is reused only when EVERYTHING that could
+// change it is unchanged: the commit (and any uncommitted change), the lockfiles, the scan configuration and the scanner itself.
+//
+//   key = sha256( repository fingerprint, lockfile digests, configuration, scanner identity )
+//
+// Anything that cannot be determined makes the key `null`, and a null key means "do not cache": an unknown input must never be
+// treated as an unchanged one. The scanner identity is the package version plus the SHA-256 recorded for the shipped bundle, so a
+// change to scanner logic changes the key. A source checkout with no built bundle has no such identity and therefore never reuses
+// a cached result.
+//
+// A cached record carries its own digest; one that was edited, truncated or does not match its key is a miss, never a hit.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { STATE_DIR_NAME } from '../state-dir.js';
+
+const LOCKFILES = Object.freeze(['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'go.sum', 'Cargo.lock', 'Pipfile.lock', 'poetry.lock', 'requirements.txt', 'Gemfile.lock', 'composer.lock', 'flake.lock', 'cabal.project.freeze', 'stack.yaml.lock']);
+const SKIP = new Set(['.git', 'node_modules', STATE_DIR_NAME]);
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+const MAX_FILES = 5000; const MAX_FILE_BYTES = 2 * 1024 * 1024; const MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+
+function git(repo, args, timeout = 10000) {
+  const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', timeout, killSignal: 'SIGKILL', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  return r.error || r.status !== 0 ? null : r.stdout;
+}
+
+function treeDigest(root) {
+  const h = createHash('sha256'); let files = 0; let total = 0; let complete = true;
+  const walk = (d, rel) => {
+    let ents = [];
+    try { ents = fs.readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); } catch { complete = false; return; }
+    for (const e of ents) {
+      if (!complete) return;
+      if (SKIP.has(e.name)) continue;
+      const p = path.join(d, e.name); const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink()) { h.update(`L ${r}\0`); continue; }
+      if (e.isDirectory()) { walk(p, r); continue; }
+      if (!e.isFile()) continue;
+      if (++files > MAX_FILES) { complete = false; return; }
+      let st; try { st = fs.statSync(p); } catch { complete = false; return; }
+      total += st.size;
+      if (total > MAX_TOTAL_BYTES) { complete = false; return; }
+      if (st.size > MAX_FILE_BYTES) { h.update(`B ${r} ${st.size}\0`); continue; }
+      try { h.update(`F ${r}\0${sha(fs.readFileSync(p))}\0`); } catch { complete = false; return; }
+    }
+  };
+  walk(root, '');
+  return complete ? h.digest('hex') : null;
+}
+
+/** What identifies this repository's content right now, or null parts where it cannot be determined. */
+export function repoFingerprint(repoPath) {
+  const head = git(repoPath, ['rev-parse', 'HEAD']);
+  const commit = head ? head.trim() : null;
+  let content = null; let dirty = null;
+  if (commit) {
+    const status = git(repoPath, ['status', '--porcelain=v1', '-uall']);
+    dirty = status == null ? null : status.trim().length > 0;
+    if (dirty === false) content = `git:${commit}`;
+    else if (dirty === true) { const t = treeDigest(repoPath); content = t ? `git+worktree:${commit}:${t}` : null; }
+  } else { const t = treeDigest(repoPath); content = t ? `tree:${t}` : null; }
+  const lock = {};
+  for (const f of LOCKFILES) { try { const st = fs.statSync(path.join(repoPath, f)); if (st.isFile() && st.size <= 32 * 1024 * 1024) lock[f] = sha(fs.readFileSync(path.join(repoPath, f))); } catch { /* absent */ } }
+  return { commit, dirty, content, lockfiles: lock };
+}
+
+/** Package version + the bundle's recorded hash. Null when the scanner cannot be identified (a source checkout), which disables the cache. */
+export function scannerIdentity() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const base of [path.join(here, '..', '..', '..'), path.join(here, '..', '..', '..', '..')]) {
+      const pkg = path.join(base, 'package.json');
+      const sidecar = path.join(base, 'dist', 'agentic-security.mjs.sha256');
+      if (fs.existsSync(pkg) && fs.existsSync(sidecar)) {
+        const version = JSON.parse(fs.readFileSync(pkg, 'utf8')).version;
+        const digest = fs.readFileSync(sidecar, 'utf8').trim().split(/\s+/)[0];
+        if (version && /^[0-9a-f]{64}$/i.test(digest)) return `${version}+${digest}`;
+      }
+    }
+  } catch { /* unknown */ }
+  return null;
+}
+
+export function cacheKey({ fingerprint, config, identity }) {
+  if (!fingerprint?.content || !identity) return null;
+  return sha(JSON.stringify({ c: fingerprint.content, l: fingerprint.lockfiles, cfg: config, id: identity }));
+}
+
+export function readCache(dir, key) {
+  if (!key || !/^[0-9a-f]{64}$/.test(key)) return null;
+  try {
+    const doc = JSON.parse(fs.readFileSync(path.join(dir, `${key}.json`), 'utf8'));
+    if (doc.key !== key) return null;
+    const { digest, ...rest } = doc;
+    return digest === sha(JSON.stringify(rest)) ? doc : null;
+  } catch { return null; }
+}
+
+export function writeCache(dir, key, payload) {
+  if (!key || !/^[0-9a-f]{64}$/.test(key)) return false;
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const body = { schema: 'agentic-security/fleet-scan-cache', version: 1, key, ...payload };
+    const doc = { ...body, digest: sha(JSON.stringify(body)) };
+    const tmp = path.join(dir, `.${key}.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(doc), { mode: 0o600 });
+    fs.renameSync(tmp, path.join(dir, `${key}.json`));
+    return true;
+  } catch { return false; }
+}

package/src/posture/fleet/scan-child.js

@@ -0,0 +1,32 @@
+// Child-process entry for ONE repository's scan inside a fleet run (PRD 4, requirement 4: one hung repository must not stop the
+// fleet). `node scan-child.js <repoPath>`. It exists as its own process so the controller can kill a scan that does not finish,
+// together with everything the scan started; an in-process scan cannot be interrupted.
+//
+// It runs the scan through the existing `runFleet` for a single repository, so the per-repository entry (finding counts, owners
+// from CODEOWNERS, scan health, policy drift, provenance debt) is exactly what a fleet entry has always been, and prints that entry
+// plus a slim copy of the findings between markers. Scan state writes are disabled (`AGENTIC_SECURITY_NO_STATE=1`, set by the
+// controller): scanning a repository for the fleet must not change that repository.
+import { runFleet } from '../fleet.js';
+import { runScan } from '../../runScan.js';
+import { summarizeLineage } from './lineage-summary.js';
+
+export const BEGIN = '@@FLEET-SCAN-BEGIN@@';
+export const END = '@@FLEET-SCAN-END@@';
+const MAX_FINDINGS = 5000;
+
+const slim = (f) => ({ id: f.id ?? null, stableId: f.stableId ?? null, severity: f.severity ?? null, cwe: f.cwe ?? null, family: f.family ?? null, vuln: f.vuln ?? null, file: f.file ?? null, line: Number.isInteger(f.line) ? f.line : null, parser: f.parser ?? null });
+
+async function main(repoPath) {
+  let captured = null;
+  const res = await runFleet({ repos: [repoPath], concurrency: 1, resume: false, runScan: async (p) => { const r = await runScan(p, { provenance: false }); captured = r.scan; return r; } });
+  const entry = res.results?.[0];
+  if (!entry) throw new Error('the scan produced no entry');
+  const findings = (captured?.findings ?? []).slice(0, MAX_FINDINGS).map(slim);
+  // the Code Boundaries graph exists only when the controller asked for it (AGENTIC_SECURITY_LINEAGE_DEEP=1); it is summarized, never copied whole
+  const lineage = process.env.AGENTIC_SECURITY_LINEAGE_DEEP === '1' ? summarizeLineage(captured?.lineageGraph) : null;
+  process.stdout.write(`${BEGIN}${JSON.stringify({ entry, findings, findingsTruncated: (captured?.findings?.length ?? 0) > MAX_FINDINGS, lineage })}${END}`);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  main(process.argv[2]).then(() => process.exit(0), (e) => { process.stderr.write(String(e?.stack || e).slice(0, 4000)); process.exit(1); });
+}

package/src/posture/proof-fabric/cli.js

@@ -10,6 +10,7 @@ import { saveProof, latestProof, listProofs, findingKey, scrubDeep } from './sto
 import { selectEnvironment, hostTools, languageSupport } from './runner.js';
 import { validateReproducer } from './reproducer.js';
 import { LANGUAGES } from './reproducer.js';
+import { generateReproducer } from './generate.js';
 
 function loadFinding(root, id) {
   const p = statePath(root, 'last-scan.json');
@@ -18,7 +19,17 @@ function loadFinding(root, id) {
   return (last.findings || []).find((f) => f.id === id || f.stableId === id) ?? null;
 }
 
-export function loadReproducerFor(root, id, flagPath) { return loadReproducer(root, id, flagPath); }
+/**
+ * The reproducer for a finding: the one the person or agent supplied (or stored), else one built from the finding's own evidence.
+ * A generated reproducer is a proposal; it earns nothing until it is executed, and the result says it was generated.
+ */
+export function resolveReproducer(root, finding, flagPath) {
+  const supplied = loadReproducer(root, finding.stableId ?? finding.id, flagPath) ?? (finding.stableId && finding.id !== finding.stableId ? loadReproducer(root, finding.id, flagPath) : null);
+  if (supplied) return { ...supplied, generated: null };
+  const g = generateReproducer({ finding, root });
+  if (!g.ok) return { reproducer: null, reason: g.reason };
+  return { reproducer: g.reproducer, file: null, generated: g.basis };
+}
 
 function loadReproducer(root, id, flagPath) {
   const candidates = [flagPath && path.resolve(String(flagPath)), statePath(root, 'reproducers', `${findingKey(id)}.json`)].filter(Boolean);
@@ -49,8 +60,9 @@ export async function cmdProve(args, root, { json = false } = {}) {
   if (!id) { console.error('usage: triage exploit <finding-id> --prove [--reproducer file] [--attempts N] [--required N]'); return 4; }
   const finding = loadFinding(root, id);
   if (!finding) { console.error(`Finding ${id} not found in last scan.`); return 4; }
-  const loaded = loadReproducer(root, id, args.flags.reproducer);
-  if (!loaded) { console.error(`No reproducer for ${id}. Supply one with --reproducer <file> or place it at .agentic-security/reproducers/. Nothing was executed.`); return 4; }
+  const loaded = resolveReproducer(root, finding, args.flags.reproducer);
+  if (!loaded.reproducer) { console.error(`No reproducer for ${id}, and none could be generated from the finding: ${loaded.reason}. Supply one with --reproducer <file> or place it at .agentic-security/reproducers/. Nothing was executed.`); return 4; }
+  if (loaded.generated) console.error(`Generated a reproducer from the finding (${loaded.generated.shape}, ${loaded.generated.class}). It is a proposal: it counts only if executing it confirms the exploit.`);
   const errs = validateReproducer(loaded.reproducer);
   if (errs.length) { console.error(`Invalid reproducer: ${errs.join('; ')}`); return 4; }
   const policy = {};
@@ -62,8 +74,8 @@ export async function cmdProve(args, root, { json = false } = {}) {
   const onSig = () => ac.abort();
   process.once('SIGINT', onSig);
   let result;
-  try { result = await proveFinding({ finding, reproducer: loaded.reproducer, revision: args.flags.revision ?? null, policy, signal: ac.signal }); } finally { process.off('SIGINT', onSig); }
-  const saved = saveProof(root, { ...result, reproducer: loaded.reproducer });
+  try { result = await proveFinding({ finding, reproducer: loaded.reproducer, revision: args.flags.revision ?? null, policy, signal: ac.signal, sourceRoot: root }); } finally { process.off('SIGINT', onSig); }
+  const saved = saveProof(root, { ...result, reproducer: loaded.reproducer, ...(loaded.generated ? { generatedFrom: loaded.generated } : {}) });
   // Printed output gets the same secret-scrubbing pass as what is persisted (defense in depth: a free-text reason/note
   // field that captured something from stdout/stderr should never reach a terminal unredacted either).
   if (json || args.flags.json) console.log(JSON.stringify(scrubDeep({ ...result, stored: saved.ok ? saved.file : null }), null, 2));
@@ -74,8 +86,19 @@ export async function cmdProve(args, root, { json = false } = {}) {
 export async function cmdProof(args, root) {
   const sub = args._[1];
   if (sub === 'doctor') return doctor(args);
+  if (sub === 'generate') {
+    const gid = String(args._[2] ?? '');
+    const finding = gid ? loadFinding(root, gid) : null;
+    if (!finding) { console.error(gid ? `Finding ${gid} not found in last scan.` : 'usage: proof generate <finding-id> [--out file]'); return 4; }
+    const g = generateReproducer({ finding, root });
+    if (!g.ok) { console.error(`No reproducer could be generated: ${g.reason}`); return 1; }
+    const text = JSON.stringify({ ...g.reproducer, findingId: gid }, null, 2);
+    if (args.flags.out) { fs.writeFileSync(path.resolve(String(args.flags.out)), `${text}\n`); console.log(`Wrote ${path.resolve(String(args.flags.out))} (${g.basis.shape}, ${g.basis.class}). Nothing was executed.`); } else console.log(text);
+    for (const a of g.basis.assumptions) console.error(`assumption: ${a}`);
+    return 0;
+  }
   const id = String(args._[2] ?? '');
-  if (!id) { console.error('usage: proof show <finding-id> | proof replay <finding-id> | proof doctor'); return 4; }
+  if (!id) { console.error('usage: proof show <finding-id> | proof replay <finding-id> | proof generate <finding-id> | proof doctor'); return 4; }
   if (sub === 'show') {
     const all = listProofs(root, id);
     if (!all.length) { console.error(`No stored proof for ${id}.`); return 4; }
@@ -84,6 +107,11 @@ export async function cmdProof(args, root) {
     const good = all.find((p) => p.record && !p.tampered);
     if (!good) { console.error('No intact proof record.'); return 1; }
     if (args.flags.json) console.log(JSON.stringify(good.record, null, 2)); else console.log(formatResult(good.record));
+    // the detection generated from this finding's proof (detection-and-response loop), when there is one
+    try {
+      const det = (await import('../dnr/store.js')).latestRecord(root, id, 'detection');
+      if (det && !args.flags.json) console.log(`Detection: ${det.record.ir?.id ?? 'unknown'} (${det.record.validation?.status ?? 'not validated'}${det.record.enabled ? ', enabled' : ''})`);
+    } catch { /* the proof output does not depend on it */ }
     void latest;
     return 0;
   }

package/src/posture/proof-fabric/container.js

@@ -0,0 +1,57 @@
+// Container execution for the proof fabric (PRD 1, requirement 2). The runner prefers a container when a responsive runtime and a
+// locally present image exist, and it never pulls an image: nothing is fetched during a proof.
+//
+// What the container is allowed to be, by construction (`containerArgs`, pure and tested flag by flag):
+//   * no network at all (`--network none`); a reproducer that needs the loopback callback listener cannot run in a container and says so;
+//   * not privileged, no capabilities (`--cap-drop ALL`), no privilege escalation (`no-new-privileges`), a read-only root filesystem;
+//   * bounded CPU, memory (swap = memory), process count and a small writable /tmp;
+//   * one bind mount: the proof's own scratch directory, as `/work`. Nothing of the host's home, repository or credentials;
+//   * the host user's uid and gid, never root;
+//   * the environment is exactly the reproducer's, plus a minimal PATH/HOME.
+// The container is named, and removed (`rm -f`) on every exit path including timeout and cancellation, because killing the `docker`
+// client does not by itself stop the container.
+//
+// HONEST LIMIT: this has been exercised against a fake engine that records the arguments and runs the command locally, which proves
+// the plumbing and the flags. It has not been run against a real Docker or Podman daemon in this repository's test environment.
+import { spawnSync } from 'node:child_process';
+import { superviseSpawn } from '../../sandbox/supervise.js';
+import { scrubEnv } from '../../sandbox/trust-domains.js';
+
+export const CONTAINER_ROOT = '/work';
+// the interpreter names inside the image; the host paths the runner uses locally mean nothing in there
+export const CONTAINER_TOOLS = Object.freeze({ node: 'node', python: 'python3', java: 'java', javac: 'javac', cc: 'gcc', dotnet: 'dotnet' });
+
+export function containerArgs({ image, name, hostRoot, argv, env = {}, limits, user = null }) {
+  if (!image || !name || !hostRoot || !Array.isArray(argv) || !argv.length) throw new Error('container run needs image, name, root and argv');
+  const uid = user ?? (typeof process.getuid === 'function' ? `${process.getuid()}:${process.getgid()}` : '65534:65534');
+  const args = [
+    'run', '--rm', '--pull', 'never', '--name', name,
+    '--network', 'none', '--read-only', '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+    '--pids-limit', String(limits.pids), '--memory', `${limits.memoryMb}m`, '--memory-swap', `${limits.memoryMb}m`, '--cpus', String(limits.cpus),
+    '--tmpfs', `/tmp:rw,nosuid,size=${limits.diskMb}m`, '--user', uid,
+    '-v', `${hostRoot}:${CONTAINER_ROOT}:rw`, '--workdir', CONTAINER_ROOT,
+    '-e', 'HOME=/work', '-e', 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', '-e', 'CI=1',
+  ];
+  for (const [k, v] of Object.entries(env)) args.push('-e', `${k}=${v}`);
+  args.push(image, ...argv);
+  return args;
+}
+
+/** Run one command in a container. Returns the same shape `runInBoundary` does for the fields the runner reads. Never throws. */
+export async function runInContainer({ runtime, image, name, hostRoot, argv, env, limits, timeoutMs, signal, maxOutputBytes, user }) {
+  const args = containerArgs({ image, name, hostRoot, argv, env, limits, user });
+  const cleanup = () => { try { spawnSync(runtime, ['rm', '-f', name], { timeout: 10_000, killSignal: 'SIGKILL', stdio: 'ignore' }); } catch { /* best effort */ } };
+  let r;
+  try {
+    r = await superviseSpawn(runtime, args, { cwd: hostRoot, // the client needs its own configuration (DOCKER_HOST, contexts, XDG paths); credential-looking names are dropped
+    env: scrubEnv(process.env), timeoutMs, signal, maxOutputBytes, graceMs: 1000 });
+  } finally { cleanup(); }
+  if (r.spawnError) return { blocked: true, reasons: [`could not start the container runtime: ${r.spawnError}`] };
+  if (r.cancelled) return { blocked: true, reasons: ['cancelled'] };
+  // a runtime failure (image gone, daemon died) is exit 125/126/127 from the client before the target ran: that is not the target's verdict
+  if (!r.timedOut && [125, 126, 127].includes(r.exitCode)) return { blocked: true, reasons: [`the container runtime could not run the command (exit ${r.exitCode}): ${String(r.stderr).trim().split('\n').pop()?.slice(0, 160) ?? ''}`] };
+  return {
+    executed: true, status: 'completed', blocked: false, exitCode: r.exitCode, timedOut: r.timedOut, outputCapped: r.outputCapped,
+    targetOutput: { stdout: r.stdout, stderr: r.stderr }, termination: r.termination, backend: 'container',
+  };
+}

package/src/posture/proof-fabric/fix-proof.js

@@ -12,7 +12,7 @@ import { proveFinding } from './orchestrator.js';
 import { runAttempt } from './runner.js';
 import { reproducerDigest, sha256, canonicalize } from './reproducer.js';
 
-export async function verifyFixWithProof({ finding, reproducer, files, scanRoot, revision = null, policy = {}, staticVerification = null, siblings = null, signal, deps = {} } = {}) {
+export async function verifyFixWithProof({ finding, reproducer, files, scanRoot, revision = null, policy = {}, staticVerification = null, siblings = null, siblingSearchTruncated = [], signal, deps = {} } = {}) {
   const t0 = Date.now();
   const attemptFn = deps.attemptFn ?? runAttempt;
   const patchHash = sha256(canonicalize(files || {}));
@@ -52,6 +52,7 @@ export async function verifyFixWithProof({ finding, reproducer, files, scanRoot,
   const siblingCount = Array.isArray(siblings) ? siblings.length : null;
   if (siblingCount === null) degraded.push('sibling-search-not-run');
   else if (siblingCount > 0) degraded.push(`sibling-exposures:${siblingCount}`);
+  if (siblingCount !== null && siblingSearchTruncated?.length) degraded.push('sibling-search-incomplete');
 
   const full = degraded.length === 0;
   // Same split as fix-verify: `ok` (nothing that ran failed) earns FIX_VERIFIED; `completeness` says whether anything was skipped.

package/src/posture/proof-fabric/generate-python.js

@@ -0,0 +1,129 @@
+// Reproducer generation for Python (PRD 1), the second language of `generate.js`. Same contract: a DETERMINISTIC proposal built
+// from the flagged file alone, then run through the ordinary runner, oracle, 3-of-3 repetition and independent replay. A generated
+// reproducer is a proposal that execution either confirms or does not.
+//
+// Python is parsed by Python itself (`python3 -I -c`, the standard `ast` module, source on stdin, JSON on stdout) with a timeout, so
+// the shape rules follow the real grammar. Two shapes, as in JavaScript:
+//   script    the file reads `sys.argv[1]`: it is run with the payload as its argument (whether the flagged line is reached is then
+//             decided by execution, not assumed);
+//   function  a module-level `def` around the flagged line: a generated harness imports the file (never as `__main__`, so its main
+//             guard does not run) and calls the function with the payload in every parameter.
+// Only the standard library and sibling `.py` files in the flagged file's directory can be satisfied; any other import is refused,
+// with the package named. Anything outside returns `{ ok: false }` with the reason, and nothing is executed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { validateReproducer } from './reproducer.js';
+
+const MAX_SOURCE = 256 * 1024;
+const MAX_FILES = 8;
+const fail = (reason, extra = {}) => ({ ok: false, reason, ...extra });
+
+const ANALYZER = `
+import ast, json, sys
+src = sys.stdin.read()
+try:
+    tree = ast.parse(src)
+except SyntaxError as e:
+    print(json.dumps({"error": "syntax"})); sys.exit(0)
+line = int(sys.argv[1])
+imports = []
+for n in ast.walk(tree):
+    if isinstance(n, ast.Import):
+        for a in n.names: imports.append({"module": a.name, "level": 0})
+    elif isinstance(n, ast.ImportFrom):
+        imports.append({"module": n.module or "", "level": n.level or 0, "names": [a.name for a in n.names]})
+fns = []
+for n in ast.walk(tree):
+    if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.lineno <= line <= (n.end_lineno or n.lineno):
+        args = [a.arg for a in n.args.posonlyargs + n.args.args + n.args.kwonlyargs]
+        fns.append({"name": n.name, "start": n.lineno, "end": n.end_lineno, "args": args, "async": isinstance(n, ast.AsyncFunctionDef), "decorated": bool(n.decorator_list), "toplevel": n in tree.body, "defaults": len(n.args.defaults)})
+fns.sort(key=lambda f: f["end"] - f["start"])
+main_guard = any(isinstance(n, ast.If) and "__name__" in ast.dump(n.test) for n in tree.body)
+print(json.dumps({"imports": imports, "functions": fns, "mainGuard": main_guard, "stdlib": sorted(sys.stdlib_module_names) if hasattr(sys, "stdlib_module_names") else None}))
+`;
+
+function analyze(text, line) {
+  const r = spawnSync('python3', ['-I', '-c', ANALYZER, String(line)], { input: text, encoding: 'utf8', timeout: 10_000, maxBuffer: 4 * 1024 * 1024 });
+  if (r.error || r.status !== 0) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+function readInside(root, rel) {
+  let real; try { real = fs.realpathSync(path.resolve(root, rel)); } catch { return null; }
+  const base = fs.realpathSync(root);
+  if (!(real === base || real.startsWith(base + path.sep))) return null;
+  const st = fs.statSync(real);
+  return st.isFile() && st.size <= MAX_SOURCE ? { real, text: fs.readFileSync(real, 'utf8') } : null;
+}
+
+const HARNESS = (entry, name, args) => `# Generated by the proof fabric from the finding's own evidence. It imports the flagged module (never as __main__) and calls the function.
+import importlib.util, sys, asyncio, inspect
+payload = sys.argv[1] if len(sys.argv) > 1 else ""
+spec = importlib.util.spec_from_file_location("target", ${JSON.stringify(entry)})
+mod = importlib.util.module_from_spec(spec)
+sys.modules["target"] = mod
+spec.loader.exec_module(mod)
+fn = getattr(mod, ${JSON.stringify(name)}, None)
+if not callable(fn):
+    print("the function is not defined at module level", file=sys.stderr); sys.exit(3)
+try:
+    res = fn(${args.join(', ')})
+    if inspect.isawaitable(res): asyncio.run(asyncio.wait_for(res, 5))
+except Exception as e:
+    print("target raised:", str(e)[:200], file=sys.stderr)
+`;
+
+/** @param {{finding: object, root: string, cls: {name: string, payload: string, oracle: object, network?: string, watch?: object, needsPy?: RegExp}}} o */
+export function generatePythonReproducer({ finding, root, cls }) {
+  const rel = String(finding.file);
+  const src = readInside(root, rel);
+  if (!src) return fail('the flagged file is missing, outside the repository, or too large');
+  const info = analyze(src.text, finding.line);
+  if (!info || info.error) return fail('the flagged file could not be parsed by Python (is python3 installed and is the file valid Python 3?)');
+  const lines = src.text.split('\n');
+  const sinkLine = lines[finding.line - 1] ?? '';
+  const around = lines.slice(Math.max(0, finding.line - 3), finding.line + 2).join('\n');
+  if (cls.needsPy && !cls.needsPy.test(sinkLine) && !cls.needsPy.test(around)) return fail(`${cls.name}: the flagged code is not a write, and this class is only proven for write sinks`);
+
+  const stdlib = new Set(info.stdlib ?? []);
+  if (!info.stdlib) return fail('this Python is too old to list its standard library (3.10 or newer is needed), so imports cannot be classified');
+  const dir = path.dirname(src.real); const rootReal = fs.realpathSync(root);
+  const sources = {}; const external = [];
+  for (const imp of info.imports) {
+    const top = imp.module.split('.')[0];
+    if (imp.level === 0 && stdlib.has(top)) continue;
+    const sibling = imp.level <= 1 ? path.join(dir, `${top || (imp.names?.[0] ?? '')}.py`) : null;
+    if (sibling && fs.existsSync(sibling)) {
+      const dep = readInside(root, path.relative(rootReal, fs.realpathSync(sibling)));
+      if (!dep) return fail(`"${top}" is too large or outside the repository`);
+      const destRel = path.relative(dir, dep.real);
+      if (!sources[destRel]) { if (Object.keys(sources).length >= MAX_FILES) return fail(`the file pulls in more than ${MAX_FILES} repository files`); sources[destRel] = path.relative(rootReal, dep.real); }
+      continue;
+    }
+    external.push(top || '.'.repeat(imp.level));
+  }
+  if (external.length) return fail(`the flagged code needs ${[...new Set(external)].slice(0, 4).join(', ')}, which is not available in the proof environment; only the standard library and sibling files in the same directory can be satisfied`);
+
+  const entry = 'target.py';
+  sources[entry] = rel;
+  const assumptions = [];
+  const base = { schema: 'agentic-security/reproducer', version: 1, findingId: String(finding.stableId ?? finding.id ?? 'generated'), lang: 'python', oracle: cls.oracle, network: cls.network ?? 'none', ...(cls.watch ? { watch: cls.watch } : {}) };
+  if (cls.watch) assumptions.push('the write target is assumed to be one directory below the working directory (the payload is ../escaped.txt); if the code uses another base, the proof will not confirm it');
+
+  if (/sys\.argv\s*\[\s*1\s*\]/.test(src.text)) {
+    const reproducer = { ...base, sources, run: ['{{PYTHON}}', entry, cls.payload] };
+    const errs = validateReproducer(reproducer);
+    return errs.length ? fail(`the generated reproducer is invalid: ${errs[0]}`) : { ok: true, reproducer, basis: { shape: 'script', class: cls.name, entry: rel, line: finding.line, assumptions } };
+  }
+  const fn = info.functions.find((f) => f.toplevel);
+  if (!fn) return fail('the flagged line is not inside a module-level function, and the file does not read sys.argv[1]');
+  if (fn.decorated) return fail(`${fn.name} is decorated (a web framework route, a cache, a wrapper): calling it directly would not match how it is reached, and the framework is not available`);
+  if (!fn.args.length) return fail('the function around the flagged line takes no parameters, so the payload has no way in');
+  if (fn.async) assumptions.push('the function is a coroutine; the harness awaits it for at most 5 seconds');
+  assumptions.push('the payload is passed in every parameter (a Python parameter has no request-like stand-in), which is an approximation of how the function is really called');
+  const harness = HARNESS(entry, fn.name, fn.args.map(() => 'payload'));
+  const reproducer = { ...base, sources, files: { 'harness.py': harness }, run: ['{{PYTHON}}', 'harness.py', cls.payload] };
+  const errs = validateReproducer(reproducer);
+  return errs.length ? fail(`the generated reproducer is invalid: ${errs[0]}`) : { ok: true, reproducer, basis: { shape: 'function', class: cls.name, entry: rel, line: finding.line, function: `${fn.name}(${fn.args.join(', ')})`, assumptions } };
+}