@clear-capabilities/agentic-security-scanner 0.166.0 → 0.167.0

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

@@ -0,0 +1,108 @@
+// Serialized reproducer: the ONLY thing an independent verifier receives (besides revision, finding id and oracle).
+// It carries no reasoning, no model output and no prior results. Everything per-run (nonce, secrets, canary paths,
+// callback URL) is a placeholder substituted fresh by the trusted runner, so a replay can never reuse a stale value
+// and a target cannot learn the values in advance.
+import { createHash } from 'node:crypto';
+import { ORACLE_TYPES } from './oracles.js';
+
+const REPRODUCER_SCHEMA = 'agentic-security/reproducer';
+const REPRODUCER_VERSION = 1;
+export const LANGUAGES = Object.freeze(['javascript', 'typescript', 'python', 'java', 'c', 'cpp', 'csharp']);
+export const MAX_FILES = 64;
+export const MAX_FILE_BYTES = 256 * 1024;
+const MAX_TOTAL_BYTES = 1024 * 1024;
+const PLACEHOLDER_RE = /\{\{([A-Z_]+)(?::([a-z0-9_-]{1,32}))?\}\}/g;
+const ALLOWED_PLACEHOLDERS = new Set(['NONCE', 'SECRET', 'CANARY', 'CALLBACK_URL', 'CALLBACK_PORT', 'ROOT', 'NODE', 'PYTHON', 'JAVA', 'JAVAC', 'CC']);
+
+export function isSafeRelPath(rel) {
+  if (typeof rel !== 'string' || !rel || rel.length > 200) return false;
+  if (rel.startsWith('/') || rel.includes('\0') || rel.includes('\\')) return false;
+  if (['canary', 'tmp'].includes(rel.split('/')[0])) return false;
+  return rel.split('/').every((seg) => seg && seg !== '.' && seg !== '..' && !seg.startsWith('__oracle_'));
+}
+
+/** Canonical JSON (sorted keys) so identical reproducers hash identically regardless of key order. */
+export function canonicalize(v) {
+  if (Array.isArray(v)) return `[${v.map(canonicalize).join(',')}]`;
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(v[k])}`).join(',')}}`;
+  return JSON.stringify(v);
+}
+export const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+export const reproducerDigest = (r) => sha256(canonicalize(r));
+
+export function validateReproducer(r) {
+  const errs = [];
+  if (!r || typeof r !== 'object' || Array.isArray(r)) return ['reproducer must be an object'];
+  if (r.schema !== REPRODUCER_SCHEMA) errs.push('unknown schema');
+  if (r.version !== REPRODUCER_VERSION) errs.push('unsupported reproducer version');
+  if (typeof r.findingId !== 'string' || !r.findingId || r.findingId.length > 200) errs.push('findingId required');
+  if (!LANGUAGES.includes(r.lang)) errs.push(`unsupported language: ${String(r.lang)}`);
+  if (!r.oracle || !ORACLE_TYPES.includes(r.oracle.type)) errs.push(`unknown oracle: ${String(r.oracle?.type)}`);
+  const files = r.files ?? {};
+  if (typeof files !== 'object' || Array.isArray(files)) errs.push('files must be an object');
+  else {
+    const names = Object.keys(files);
+    if (names.length > MAX_FILES) errs.push(`file count must be at most ${MAX_FILES}`);
+    let total = 0;
+    for (const n of names) {
+      if (!isSafeRelPath(n)) { errs.push(`unsafe file path: ${n}`); continue; }
+      if (typeof files[n] !== 'string') { errs.push(`file ${n} must be a string`); continue; }
+      const b = Buffer.byteLength(files[n]);
+      total += b;
+      if (b > MAX_FILE_BYTES) errs.push(`file ${n} exceeds ${MAX_FILE_BYTES} bytes`);
+    }
+    if (total > MAX_TOTAL_BYTES) errs.push('reproducer exceeds total size limit');
+  }
+  const sourceNames = r.sources && typeof r.sources === 'object' && !Array.isArray(r.sources) ? Object.keys(r.sources) : [];
+  if (Object.keys(files).length + sourceNames.length === 0) errs.push('reproducer must declare at least one file or source');
+  for (const key of ['build', 'run']) {
+    const a = r[key];
+    if (a == null && key === 'build') continue;
+    if (!Array.isArray(a) || !a.length || !a.every((x) => typeof x === 'string' && x.length < 2000 && !x.includes('\0'))) errs.push(`${key} must be a non-empty argv array of strings (no shell string)`);
+  }
+  for (const text of [...Object.values(files || {}), ...(r.build || []), ...(r.run || [])]) {
+    if (typeof text !== 'string') continue;
+    for (const m of text.matchAll(PLACEHOLDER_RE)) if (!ALLOWED_PLACEHOLDERS.has(m[1])) errs.push(`unknown placeholder {{${m[1]}}}`);
+  }
+  if (r.watch != null) {
+    if (typeof r.watch !== 'object' || Array.isArray(r.watch)) errs.push('watch must be an object');
+    else for (const [k, v] of Object.entries(r.watch)) if (!/^[a-z0-9_-]{1,32}$/.test(k) || !isSafeRelPath(v)) errs.push(`bad watch entry: ${k}`);
+  }
+  if (r.env != null) {
+    if (typeof r.env !== 'object' || Array.isArray(r.env)) errs.push('env must be an object');
+    else for (const [k, v] of Object.entries(r.env)) {
+      if (!/^[A-Z][A-Z0-9_]{0,63}$/.test(k)) errs.push(`bad env var name: ${k}`);
+      if (typeof v !== 'string' || v.length > 4096) errs.push(`env value for ${k} must be a short string`);
+    }
+  }
+  if (r.sources != null) {
+    if (typeof r.sources !== 'object' || Array.isArray(r.sources)) errs.push('sources must be an object');
+    else for (const [dest, src] of Object.entries(r.sources)) if (!isSafeRelPath(dest) || !isSafeRelPath(src)) errs.push(`bad sources entry: ${dest}`);
+  }
+  if (r.network != null && !['none', 'callback'].includes(r.network)) errs.push('network must be none or callback');
+  return errs;
+}
+
+/** The view handed to an independent verifier: exactly the reproducer, plus identifiers. Nothing else. */
+export function verifierView({ revision, reproducer, findingId, oracle }) {
+  return Object.freeze({ revision: revision ?? null, findingId, oracle, reproducer: structuredClone(reproducer) });
+}
+
+export function substitute(text, ctx) {
+  return text.replace(PLACEHOLDER_RE, (whole, name, arg) => {
+    switch (name) {
+      case 'NONCE': return ctx.nonce;
+      case 'SECRET': return ctx.secret(arg || 'default');
+      case 'CANARY': return ctx.canary(arg || 'default');
+      case 'CALLBACK_URL': return ctx.callbackUrl ?? whole;
+      case 'CALLBACK_PORT': return String(ctx.callbackPort ?? '');
+      case 'ROOT': return ctx.root;
+      case 'NODE': return ctx.tools.node;
+      case 'PYTHON': return ctx.tools.python ?? whole;
+      case 'JAVA': return ctx.tools.java ?? whole;
+      case 'JAVAC': return ctx.tools.javac ?? whole;
+      case 'CC': return ctx.tools.cc ?? whole;
+      default: return whole;
+    }
+  });
+}

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

@@ -0,0 +1,243 @@
+// Hermetic execution of one reproducer attempt.
+//
+// Isolation preference: container (when a working runtime and a pre-pulled image exist) > local confined sandbox >
+// unavailable. The local mode is LOWER assurance and says so in every result; it is never silently substituted for a
+// container where a policy requires one (`requireContainer`). Nothing here ever executes target code unconfined.
+//
+// Defaults: outbound network denied; only a runner-controlled loopback callback listener may be reachable, and only when
+// the reproducer asks for it; no privileged containers; bounded CPU, memory, disk, process count and wall time.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes, createHash } from 'node:crypto';
+import { runInBoundary } from '../../sandbox/trust-boundary.js';
+import { detectBackend } from '../../sandbox/index.js';
+import { evaluateOracle } from './oracles.js';
+import { validateReproducer, substitute } from './reproducer.js';
+
+export const DEFAULT_LIMITS = Object.freeze({
+  timeoutMs: 20_000, buildTimeoutMs: 60_000, graceMs: 1000, maxOutputBytes: 256 * 1024,
+  cpus: 1, memoryMb: 512, pids: 128, diskMb: 64,
+});
+
+const CONTAINER_IMAGES = Object.freeze({
+  javascript: 'node:24-slim', typescript: 'node:24-slim', python: 'python:3-slim', java: 'eclipse-temurin:21',
+  c: 'gcc:latest', cpp: 'gcc:latest', csharp: 'mcr.microsoft.com/dotnet/sdk:8.0',
+});
+
+const SIGNALS = { 134: 'SIGABRT', 135: 'SIGBUS', 136: 'SIGFPE', 132: 'SIGILL', 139: 'SIGSEGV' };
+
+function findTool(name, pathEnv = process.env.PATH || '') {
+  for (const dir of pathEnv.split(path.delimiter)) {
+    if (!dir) continue;
+    const p = path.join(dir, name);
+    try { fs.accessSync(p, fs.constants.X_OK); if (fs.statSync(p).isFile()) return fs.realpathSync(p); } catch { /* next */ }
+  }
+  return null;
+}
+
+export function hostTools() {
+  return { node: process.execPath, python: findTool('python3'), java: findTool('java'), javac: findTool('javac'), cc: findTool('cc') || findTool('gcc'), dotnet: findTool('dotnet') };
+}
+
+/** Language -> tools it needs. Missing tools make the language `unsupported` with a typed reason, never a pass. */
+export function languageSupport(lang, tools = hostTools()) {
+  const need = { javascript: ['node'], typescript: ['node'], python: ['python'], java: ['java', 'javac'], c: ['cc'], cpp: ['cc'], csharp: ['dotnet'] }[lang];
+  if (!need) return { supported: false, reason: `unsupported language: ${lang}` };
+  const missing = need.filter((t) => !tools[t]);
+  return missing.length ? { supported: false, reason: `missing toolchain: ${missing.join(', ')}` } : { supported: true, reason: null };
+}
+
+/**
+ * Pick the execution environment. `docker` is injectable for tests. A container needs a responsive daemon AND the image
+ * already present: nothing is ever pulled (no network during proof).
+ */
+export function selectEnvironment({ lang, preferContainer = true, requireContainer = false, docker = null, tools = hostTools(), force } = {}) {
+  const dockerBin = docker?.bin ?? findTool('docker');
+  if (preferContainer && dockerBin) {
+    const image = docker?.images?.[lang] ?? CONTAINER_IMAGES[lang];
+    const probe = (docker?.probe ?? defaultDockerProbe)(dockerBin, image);
+    if (probe.ok) return { mode: 'container', assurance: 'high', runtime: dockerBin, image, reason: null };
+    if (requireContainer) return { mode: 'unavailable', assurance: 'none', reason: `container required but unavailable: ${probe.reason}` };
+    const local = localEnv(force);
+    return { ...local, containerSkipped: probe.reason };
+  }
+  if (requireContainer) return { mode: 'unavailable', assurance: 'none', reason: 'container required but no container runtime found' };
+  return localEnv(force);
+}
+
+function localEnv(force) {
+  const backend = detectBackend({ force });
+  if (backend === 'disabled') return { mode: 'unavailable', assurance: 'none', reason: 'no confinement backend works on this host; refusing to execute' };
+  return { mode: 'local-confined', assurance: 'lower', backend, reason: null, note: 'lower-assurance local confinement: not a container boundary' };
+}
+
+function defaultDockerProbe(bin, image) {
+  const info = spawnSync(bin, ['info', '--format', '{{.ServerVersion}}'], { encoding: 'utf8', timeout: 5000, killSignal: 'SIGKILL' });
+  if (info.status !== 0) return { ok: false, reason: 'container daemon not responding' };
+  const img = spawnSync(bin, ['image', 'inspect', image], { encoding: 'utf8', timeout: 5000, killSignal: 'SIGKILL' });
+  return img.status === 0 ? { ok: true } : { ok: false, reason: `image ${image} is not present locally (proofs never pull)` };
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+
+const digestFile = (p) => { try { return createHash('sha256').update(fs.readFileSync(p)).digest('hex'); } catch { return null; } };
+
+const LISTENER_SRC = `
+const http = require('node:http'); const fs = require('node:fs');
+const out = process.argv[1];
+const s = http.createServer((req, res) => {
+  const m = /^\\/([A-Za-z0-9_-]{8,64})/.exec(req.url || '');
+  if (m) fs.appendFileSync(out, JSON.stringify({ nonce: m[1] }) + '\\n');
+  req.resume(); res.end('ok');
+});
+s.on('error', () => process.exit(2));
+s.listen(0, '127.0.0.1', () => { process.stdout.write(String(s.address().port) + '\\n'); });
+setTimeout(() => process.exit(0), 120000).unref();
+`;
+
+async function startListener(dir) {
+  const hits = path.join(dir, 'hits.jsonl');
+  fs.writeFileSync(hits, '');
+  const child = spawn(process.execPath, ['-e', LISTENER_SRC, hits], { stdio: ['ignore', 'pipe', 'ignore'], detached: false });
+  const port = await new Promise((resolve) => {
+    let buf = '';
+    const t = setTimeout(() => resolve(null), 3000);
+    child.stdout.on('data', (d) => { buf += d; const n = Number(buf.trim()); if (n > 0) { clearTimeout(t); resolve(n); } });
+    child.on('exit', () => { clearTimeout(t); resolve(null); });
+  });
+  return {
+    port, child,
+    hits: () => { try { return fs.readFileSync(hits, 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch { return []; } },
+    stop: () => { try { child.kill('SIGKILL'); } catch { /* gone */ } },
+  };
+}
+
+function trimOut(s, max) { s = String(s ?? ''); return s.length > max ? `${s.slice(0, max)}\n[truncated]` : s; }
+
+/**
+ * Run one attempt. Never throws. Result:
+ *   { status, executed, environment, observation, oracle, durationMs, reasons[], degraded[], nonceDigest }
+ * status: 'completed' | 'build-failed' | 'blocked' | 'unsupported' | 'invalid' | 'error'
+ * Only `completed` carries an oracle verdict; everything else is incomplete evidence.
+ */
+export async function runAttempt(reproducer, opts = {}) {
+  const started = Date.now();
+  const limits = { ...DEFAULT_LIMITS, ...(opts.limits || {}) };
+  const done = (o) => ({ executed: false, observation: null, oracle: null, degraded: [], reasons: [], ...o, durationMs: Date.now() - started });
+
+  const errs = validateReproducer(reproducer);
+  if (errs.length) return done({ status: 'invalid', reasons: errs });
+  const tools = opts.tools ?? hostTools();
+  const sup = languageSupport(reproducer.lang, tools);
+  if (!sup.supported) return done({ status: 'unsupported', reasons: [sup.reason] });
+  const env = opts.environment ?? selectEnvironment({ lang: reproducer.lang, requireContainer: opts.requireContainer, preferContainer: opts.preferContainer ?? true, force: opts.force });
+  if (env.mode === 'unavailable') return done({ status: 'blocked', environment: env, reasons: [env.reason] });
+  if (env.mode === 'container') {
+    return done({ status: 'blocked', environment: env, reasons: ['container execution is selected but the container runner is not enabled in this build; use requireContainer:false for local-confined proof'] });
+  }
+  if (reproducer.network === 'callback' && env.backend !== 'userspace') {
+    return done({ status: 'unsupported', environment: env, reasons: [`loopback callback needs the userspace backend; this host uses ${env.backend}`] });
+  }
+
+  const nonce = randomBytes(12).toString('hex');
+  const base = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'proof-fabric-')));
+  const root = path.join(base, 'root');
+  const aux = path.join(base, 'aux');
+  fs.mkdirSync(root, { recursive: true });
+  fs.mkdirSync(path.join(root, 'canary'));
+  fs.mkdirSync(path.join(root, 'tmp'));
+  fs.mkdirSync(aux);
+  let listener = null;
+  try {
+    const secrets = {};
+    const canaries = {};
+    const ctx = {
+      nonce, root, tools,
+      secret: (n) => (secrets[n] ??= `SECRET-${nonce}-${n}`),
+      canary: (n) => { canaries[n] ??= { path: path.join(root, 'canary', `${nonce}-${n}`) }; return canaries[n].path; },
+    };
+    if (reproducer.network === 'callback') {
+      listener = await startListener(aux);
+      if (!listener.port) return done({ status: 'error', environment: env, reasons: ['could not start the loopback callback listener'] });
+      ctx.callbackPort = listener.port;
+      ctx.callbackUrl = `http://127.0.0.1:${listener.port}/${nonce}`;
+    }
+    // Repository sources imported at proof time (so a patch can be overlaid). Read-only, size-bounded, confined to sourceRoot.
+    const imported = {};
+    if (reproducer.sources) {
+      if (!opts.sourceRoot) return done({ status: 'invalid', environment: env, reasons: ['reproducer imports repository sources but no sourceRoot was given'] });
+      const realRoot = fs.realpathSync(opts.sourceRoot);
+      for (const [dest, src] of Object.entries(reproducer.sources)) {
+        let text;
+        if (opts.overlay && Object.hasOwn(opts.overlay, src)) text = String(opts.overlay[src]);
+        else {
+          const abs = path.resolve(realRoot, src);
+          let real; try { real = fs.realpathSync(abs); } catch { return done({ status: 'invalid', environment: env, reasons: [`source not found: ${src}`] }); }
+          if (real !== realRoot && !real.startsWith(realRoot + path.sep)) return done({ status: 'invalid', environment: env, reasons: [`source escapes the repository: ${src}`] });
+          const st = fs.statSync(real);
+          if (!st.isFile() || st.size > 256 * 1024) return done({ status: 'invalid', environment: env, reasons: [`source is not a regular file within the size limit: ${src}`] });
+          text = fs.readFileSync(real, 'utf8');
+        }
+        imported[dest] = text;
+      }
+    }
+    for (const [rel, text] of Object.entries({ ...imported, ...reproducer.files })) {
+      const dest = path.join(root, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, substitute(text, ctx));
+    }
+    const argv = (a) => a.map((x) => substitute(x, ctx));
+    const watch = {};
+    for (const [name, rel] of Object.entries(reproducer.watch || {})) {
+      const p = path.join(root, rel);
+      watch[name] = { path: p, existedBefore: fs.existsSync(p), digestBefore: digestFile(p) };
+    }
+    const runEnv = { PATH: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/opt/homebrew/bin', HOME: root, TMPDIR: path.join(root, 'tmp'), LANG: 'C.UTF-8', CI: '1' };
+    for (const [k, v] of Object.entries(reproducer.env || {})) runEnv[k] = substitute(v, ctx);
+    const boundary = { root, timeoutMs: limits.timeoutMs, graceMs: limits.graceMs, maxOutputBytes: limits.maxOutputBytes, env: runEnv, force: opts.force, signal: opts.signal, controlProbes: opts.controlProbes };
+
+    const degraded = [];
+    if (env.assurance === 'lower') degraded.push('lower-assurance-local-confinement');
+
+    if (reproducer.build) {
+      const b = await runInBoundary(argv(reproducer.build), { ...boundary, timeoutMs: limits.buildTimeoutMs, cwd: undefined });
+      if (b.blocked) return done({ status: 'blocked', environment: env, reasons: b.reasons, degraded });
+      if (b.timedOut || b.exitCode !== 0) return done({ status: 'build-failed', executed: true, environment: env, reasons: [b.timedOut ? 'build timed out' : `build exited ${b.exitCode}`], degraded, observation: { buildStderr: trimOut(b.targetOutput?.stderr, 2000) } });
+    }
+
+    const r = await runInBoundary(argv(reproducer.run), { ...boundary, ...(listener ? { networkProxyPort: listener.port } : {}) });
+    if (r.blocked) return done({ status: 'blocked', environment: env, reasons: r.reasons, degraded });
+    if (!r.executed) return done({ status: 'error', environment: env, reasons: [`target did not execute (${r.status})`], degraded });
+
+    const exitCode = r.exitCode ?? null;
+    const observation = {
+      exitCode, signal: SIGNALS[exitCode] ?? null, timedOut: !!r.timedOut,
+      stdout: trimOut(r.targetOutput?.stdout, limits.maxOutputBytes), stderr: trimOut(r.targetOutput?.stderr, limits.maxOutputBytes),
+      nonce, secrets, canaries: {}, callbacks: listener ? listener.hits() : [],
+    };
+    for (const [n, c] of Object.entries(canaries)) observation.canaries[n] = { exists: fs.existsSync(c.path), existedBefore: false };
+    for (const [n, w] of Object.entries(watch)) observation.canaries[n] = { exists: fs.existsSync(w.path), existedBefore: w.existedBefore, digestBefore: w.digestBefore, digestAfter: digestFile(w.path) };
+    if (r.outputCapped) degraded.push('output-capped');
+    if (r.timedOut) degraded.push('timed-out');
+    if (r.termination?.survivors?.length) degraded.push('surviving-processes');
+
+    const oracle = evaluateOracle(reproducer.oracle, observation);
+    // Raw secrets/nonce must not leave this function: persisted evidence carries digests only.
+    const safeObs = { ...observation, secrets: Object.fromEntries(Object.keys(secrets).map((k) => [k, '[redacted]'])), nonce: '[redacted]', callbacks: observation.callbacks.length };
+    safeObs.stdout = scrub(safeObs.stdout, nonce); safeObs.stderr = scrub(safeObs.stderr, nonce);
+    return done({
+      status: oracle.unsupported ? 'unsupported' : 'completed', executed: true, environment: { ...env, backend: r.backend ?? env.backend },
+      observation: safeObs, oracle, degraded, reasons: oracle.unsupported ? [oracle.reason] : [], controls: r.controls,
+      nonceDigest: createHash('sha256').update(nonce).digest('hex').slice(0, 16),
+    });
+  } catch (e) {
+    return done({ status: 'error', environment: env, reasons: [`runner error: ${e.message}`] });
+  } finally {
+    if (listener) listener.stop();
+    fs.rmSync(base, { recursive: true, force: true });
+  }
+}
+
+const scrub = (s, nonce) => String(s).split(nonce).join('[nonce]');

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

@@ -0,0 +1,53 @@
+// Evidence state ladder for the Universal Exploit Proof Fabric.
+//
+// Evidence state is SEPARATE from severity and confidence. It extends, never replaces, the vocabulary that already
+// exists: `proof-tier.js` (execution-proven / proof-failed / taint-proven / unproven) and the fix-verify legs
+// (`verifiedFull`, `degradedLegs`). `toProofTier` / `fromProofTier` are the explicit bridges.
+//
+// Transitions are guarded: a state can only be reached from the state directly before it (or by dropping back), so no
+// caller can jump a finding to EXPLOIT_CONFIRMED without passing REPRODUCED, or to FIX_VERIFIED without
+// FIX_REPLAY_BLOCKED. A degraded or incomplete run NEVER advances a state.
+export const EVIDENCE_STATES = Object.freeze([
+  'CANDIDATE',
+  'STATICALLY_CORROBORATED',
+  'REPRODUCER_GENERATED',
+  'REPRODUCED',
+  'EXPLOIT_CONFIRMED',
+  'FIX_REPLAY_BLOCKED',
+  'FIX_VERIFIED',
+]);
+
+export const stateRank = (s) => EVIDENCE_STATES.indexOf(s);
+
+const REQUIRES_PREDECESSOR = Object.freeze(Object.fromEntries(EVIDENCE_STATES.map((s, i) => [s, i === 0 ? null : EVIDENCE_STATES[i - 1]])));
+
+/**
+ * Advance `from` to `to`. Returns { ok, state, reason }. Moving up requires `to` to be exactly the next rung; moving
+ * down or staying is always allowed (evidence can be lost, never invented). Unknown states are rejected.
+ */
+export function advance(from, to) {
+  if (!EVIDENCE_STATES.includes(from)) return { ok: false, state: 'CANDIDATE', reason: `unknown current state: ${String(from)}` };
+  if (!EVIDENCE_STATES.includes(to)) return { ok: false, state: from, reason: `unknown target state: ${String(to)}` };
+  if (stateRank(to) <= stateRank(from)) return { ok: true, state: to, reason: null };
+  if (REQUIRES_PREDECESSOR[to] !== from) return { ok: false, state: from, reason: `cannot reach ${to} from ${from}: ${REQUIRES_PREDECESSOR[to]} is required first` };
+  return { ok: true, state: to, reason: null };
+}
+
+// Bridges to the older vocabulary so existing consumers keep working.
+export function toProofTier(state) {
+  const r = stateRank(state);
+  if (r >= stateRank('EXPLOIT_CONFIRMED')) return 'execution-proven';
+  if (r >= stateRank('STATICALLY_CORROBORATED')) return 'taint-proven';
+  return 'unproven';
+}
+
+export function fromProofTier(tier) {
+  if (tier === 'taint-proven') return 'STATICALLY_CORROBORATED';
+  // execution-proven under the older single-run marker path is one run, not the 3/3 + independent replay the fabric
+  // requires, so it maps to REPRODUCED and never to EXPLOIT_CONFIRMED.
+  if (tier === 'execution-proven') return 'REPRODUCED';
+  return 'CANDIDATE';
+}
+
+// Completeness vocabulary shared with fix-verify: FULL only when nothing was skipped.
+export const COMPLETENESS = Object.freeze(['FULL', 'DEGRADED', 'INCOMPLETE']);

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

@@ -0,0 +1,83 @@
+// Proof artifact store: `.agentic-security/proofs/<findingKey>/<recordDigest>.json`.
+//
+// Reuses the existing state machinery rather than adding another: `safeWriteState` (refuses unsafe dirs and symlinks),
+// `maybeEncryptForWrite` / `maybeDecryptForRead` (the `proofs` artifact is registered `confidential`), retention
+// (evidence class) and legal holds (a hold on `proofs` blocks purge). Nothing persisted contains a plaintext credential:
+// records are passed through a recursive secret filter first, and the runner never returns its per-run nonce or secrets.
+import fs from 'node:fs';
+import path from 'node:path';
+import { statePath, ensureStateDir, safeWriteState } from '../state-dir.js';
+import { maybeEncryptForWrite, maybeDecryptForRead } from '../encryption-provider.js';
+import { redactSecrets } from '../../llm-validator/redact.js';
+import { canonicalize, sha256 } from './reproducer.js';
+
+const PROOF_RECORD_SCHEMA = 'agentic-security/proof-record';
+const PROOFS_DIR = 'proofs';
+const MAX_RECORD_BYTES = 512 * 1024;
+
+export const findingKey = (id) => `${String(id).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80)}-${sha256(String(id)).slice(0, 8)}`;
+
+// The shared redactor catches key=value shapes; bare tokens need their own pass, so persisted evidence cannot carry one.
+const BARE_SECRET_RES = [
+  /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/g, /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, /\bSECRET-[0-9a-f]{24}-[a-z0-9_-]+\b/g,
+];
+function scrubString(text) {
+  let t = String(text);
+  try { t = redactSecrets(t).text; } catch { return '[unredactable]'; }
+  for (const re of BARE_SECRET_RES) t = t.replace(re, '[REDACTED-SECRET]');
+  return t;
+}
+
+/** Deep-copy `v` with every string passed through the secret redactor. */
+export function scrubDeep(v) {
+  if (typeof v === 'string') return scrubString(v);
+  if (Array.isArray(v)) return v.map(scrubDeep);
+  if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, scrubDeep(x)]));
+  return v;
+}
+
+function recordDigest(record) {
+  const { recordDigest: _omit, ...rest } = record;
+  return sha256(canonicalize(rest));
+}
+
+export function saveProof(scanRoot, record) {
+  const safe = scrubDeep(record);
+  safe.schema = PROOF_RECORD_SCHEMA;
+  safe.recordDigest = recordDigest(safe);
+  const text = JSON.stringify(safe, null, 2);
+  if (Buffer.byteLength(text) > MAX_RECORD_BYTES) return { ok: false, reason: 'proof record exceeds the size limit' };
+  if (!ensureStateDir(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
+  const enc = maybeEncryptForWrite(scanRoot, PROOFS_DIR, text);
+  if (!enc.ok) return { ok: false, reason: enc.reason };
+  const file = statePath(scanRoot, PROOFS_DIR, findingKey(record.findingId), `${safe.recordDigest}.json`);
+  if (!safeWriteState(file, enc.content)) return { ok: false, reason: 'state write refused' };
+  return { ok: true, file, digest: safe.recordDigest, encrypted: enc.encrypted };
+}
+
+function readRecord(file) {
+  const text = maybeDecryptForRead(fs.readFileSync(file, 'utf8'));
+  const rec = JSON.parse(text);
+  // A record whose content no longer matches its own digest was modified after it was written.
+  if (rec.recordDigest !== recordDigest(rec)) return { tampered: true, record: rec };
+  return { tampered: false, record: rec };
+}
+
+/** Newest-first records for a finding. Tampered records are returned flagged, never silently dropped or trusted. */
+export function listProofs(scanRoot, findingId) {
+  const dir = statePath(scanRoot, PROOFS_DIR, findingKey(findingId));
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.json')); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    const f = path.join(dir, n);
+    try { const { tampered, record } = readRecord(f); out.push({ file: f, tampered, record, mtime: fs.statSync(f).mtimeMs }); } catch { out.push({ file: f, tampered: true, record: null, mtime: 0 }); }
+  }
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+export function latestProof(scanRoot, findingId) {
+  return listProofs(scanRoot, findingId).find((p) => p.record) ?? null;
+}

package/src/posture/rule-compiler/cli.js

@@ -0,0 +1,141 @@
+// CLI surface: `agentic-security rules synthesize|evaluate|promote|status|rollback`.
+//
+// Distinct from the pre-existing `labs synthesize-rule` (posture/rule-synthesis.js), which proposes SUPPRESSION
+// rules from repeated false-positive triage verdicts — a different input, a different output and a different
+// command group on purpose, so the two are never confused at the CLI.
+//
+// Non-interactive by construction: no command reads stdin, every corpus evaluation is bounded (no network, no
+// model call — this is the deterministic half; a model may PROPOSE the candidate pattern this CLI is handed, but
+// it never decides promotion).
+import fs from 'node:fs';
+import { statePath } from '../state-dir.js';
+import { draftRuleIR, validateRuleIR, ruleIRDigest } from './ir.js';
+import { checkEligibility } from './eligibility.js';
+import { buildCorpus } from './corpus.js';
+import { gatePromotion, checkLeakage, PROMOTION_DEFAULTS } from './promotion.js';
+import { recordTransition, stateOf, historyFor } from './lifecycle.js';
+import { loadLedger, saveLedger, saveIR, loadIR, saveEvaluation, writeFixtures, publishCustomRule, unpublishCustomRule } from './store.js';
+
+function loadFinding(root, id) {
+  const p = statePath(root, 'last-scan.json');
+  if (!fs.existsSync(p)) return null;
+  const last = JSON.parse(fs.readFileSync(p, 'utf8'));
+  return (last.findings || []).find((f) => f.id === id || f.stableId === id) ?? null;
+}
+
+function readJsonArg(pathOrInline) {
+  if (!pathOrInline) return null;
+  try { return JSON.parse(fs.existsSync(pathOrInline) ? fs.readFileSync(pathOrInline, 'utf8') : pathOrInline); } catch { return null; }
+}
+
+export async function cmdRules(args, root) {
+  const sub = args._[1];
+  if (sub === 'synthesize') return cmdSynthesize(args, root);
+  if (sub === 'evaluate') return cmdEvaluate(args, root);
+  if (sub === 'promote') return cmdPromote(args, root);
+  if (sub === 'status') return cmdStatus(args, root);
+  if (sub === 'rollback') return cmdRollback(args, root);
+  console.error('usage: rules synthesize <finding-id> --spec <file.json> | evaluate <rule-id> | promote <rule-id> | status [rule-id] | rollback <rule-id>');
+  return 4;
+}
+
+// `--spec` carries exactly what a model or a human proposed: id/title/severity/cwe/family/languages/match/
+// remediation plus the corpus inputs (originalCode/patchedCode/nearbyCleanCode/protectedVariantsCode). This
+// command never invents a pattern; it only drafts the IR, checks eligibility and records DRAFT->CANDIDATE.
+async function cmdSynthesize(args, root) {
+  const findingId = args._[2];
+  const spec = readJsonArg(args.flags.spec);
+  if (!findingId || !spec) { console.error('usage: rules synthesize <finding-id> --spec <file.json>'); return 4; }
+  const finding = loadFinding(root, findingId);
+  if (!finding) { console.error(`Finding ${findingId} not found in last scan.`); return 4; }
+  const elig = checkEligibility(finding, { proofState: args.flags['proof-state'] || null });
+  if (!elig.eligible) { console.error(`Not eligible for rule synthesis: ${elig.reasons.join('; ')}`); return 4; }
+
+  const ir = draftRuleIR({ ...spec, originatingFindingId: finding.stableId ?? finding.id, originatingCommit: spec.originatingCommit ?? null, evidenceState: elig.evidenceState });
+  const errs = validateRuleIR(ir);
+  if (errs.length) { console.error(`Invalid rule: ${errs.join('; ')}`); return 4; }
+
+  const ledger = loadLedger(root);
+  const draft = recordTransition(ledger, { ruleId: ir.id, from: null, to: 'DRAFT', reason: `drafted from ${findingId}`, actor: args.flags.actor || 'agent' });
+  if (!draft.ok) { console.error(draft.reason); return 4; }
+  const cand = recordTransition(ledger, { ruleId: ir.id, from: 'DRAFT', to: 'CANDIDATE', reason: 'eligibility passed', evidence: { eligibility: elig }, actor: args.flags.actor || 'agent' });
+  saveLedger(root, ledger);
+  saveIR(root, { ...ir, state: 'CANDIDATE' });
+  console.log(`Rule ${ir.id}: DRAFT -> CANDIDATE (digest ${ruleIRDigest(ir).slice(0, 12)})`);
+  if (!cand.ok) console.error(cand.reason);
+  return 0;
+}
+
+async function cmdEvaluate(args, root) {
+  const id = args._[2];
+  if (!id) { console.error('usage: rules evaluate <rule-id> --corpus <file.json>'); return 4; }
+  const ir = loadIR(root, id);
+  if (!ir) { console.error(`No rule IR found for ${id}. Run rules synthesize first.`); return 4; }
+  const corpusSpec = readJsonArg(args.flags.corpus);
+  if (!corpusSpec) { console.error('No corpus supplied. Pass --corpus <file.json> with originalCode (and optionally patchedCode/nearbyCleanCode/protectedVariantsCode).'); return 4; }
+  const corpus = buildCorpus(ir, corpusSpec);
+  const leakage = checkLeakage(JSON.stringify(corpusSpec), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [] });
+  const gate = gatePromotion({ ir, corpus, leakageCheck: leakage, thresholds: args.flags.thresholds ? readJsonArg(args.flags.thresholds) : PROMOTION_DEFAULTS });
+
+  const ledger = loadLedger(root);
+  const cur = stateOf(ledger, id);
+  if (gate.pass && cur === 'CANDIDATE') recordTransition(ledger, { ruleId: id, from: 'CANDIDATE', to: 'VALIDATED', reason: 'promotion gate passed', evidence: { score: gate.evaluation.score }, actor: args.flags.actor || 'agent' });
+  saveLedger(root, ledger);
+  saveEvaluation(root, id, gate);
+  if (args.flags.json) console.log(JSON.stringify(gate, null, 2));
+  else {
+    console.log(`Rule ${id}: ${gate.pass ? 'VALIDATED' : 'gate FAILED'}`);
+    console.log(`  precision ${fmtPct(gate.evaluation.score.precision)}  recall ${fmtPct(gate.evaluation.score.recall)}  protected-failures ${gate.evaluation.score.protectedFailures}`);
+    for (const r of gate.reasons) console.log(`  - ${r}`);
+  }
+  if (gate.pass) { const f = writeFixtures(root, ir, corpus); if (f.ok) console.log(`  regression fixtures written: ${f.written.length} file(s) under .agentic-security/rule-compiler/${id}/fixtures/`); }
+  return gate.pass ? 0 : 1;
+}
+const fmtPct = (n) => (n == null ? 'unmeasured' : `${(n * 100).toFixed(1)}%`);
+
+async function cmdPromote(args, root) {
+  const id = args._[2];
+  if (!id) { console.error('usage: rules promote <rule-id>'); return 4; }
+  const ledger = loadLedger(root);
+  if (ledger.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${ledger.tamperReason}).`); return 4; }
+  if (stateOf(ledger, id) !== 'VALIDATED') { console.error(`Rule ${id} is not VALIDATED (run rules evaluate first); refusing to promote.`); return 4; }
+  const ir = loadIR(root, id);
+  if (!ir) { console.error(`No rule IR found for ${id}.`); return 4; }
+  const pub = publishCustomRule(root, ir);
+  if (!pub.ok) { console.error(`Promotion refused: ${pub.reason}`); return 4; }
+  const t = recordTransition(ledger, { ruleId: id, from: 'VALIDATED', to: 'PROMOTED', reason: args.flags.reason || 'promoted', actor: args.flags.actor || 'operator' });
+  saveLedger(root, ledger);
+  console.log(`Rule ${id}: VALIDATED -> PROMOTED. Published to ${pub.file}.`);
+  if (!t.ok) console.error(t.reason);
+  return 0;
+}
+
+async function cmdRollback(args, root) {
+  const id = args._[2];
+  if (!id) { console.error('usage: rules rollback <rule-id> [--reason text]'); return 4; }
+  const ledger = loadLedger(root);
+  const cur = stateOf(ledger, id);
+  if (cur !== 'PROMOTED') { console.error(`Rule ${id} is not PROMOTED (current: ${cur ?? 'unknown'}); nothing to roll back.`); return 4; }
+  const un = unpublishCustomRule(root, id);
+  const t = recordTransition(ledger, { ruleId: id, from: 'PROMOTED', to: 'ROLLED_BACK', reason: args.flags.reason || 'operator rollback', actor: args.flags.actor || 'operator' });
+  saveLedger(root, ledger);
+  console.log(`Rule ${id}: PROMOTED -> ROLLED_BACK.${un.ok ? '' : ` (warning: could not remove published rule file: ${un.reason})`}`);
+  return t.ok ? 0 : 1;
+}
+
+async function cmdStatus(args, root) {
+  const ledger = loadLedger(root);
+  const id = args._[2];
+  if (id) {
+    const h = historyFor(ledger, id);
+    if (!h.length) { console.error(`No history for rule ${id}.`); return 4; }
+    if (args.flags.json) console.log(JSON.stringify(h, null, 2));
+    else { console.log(`Rule ${id}: ${stateOf(ledger, id)}`); for (const e of h) console.log(`  ${e.at}  ${e.from ?? '(new)'} -> ${e.to}  (${e.reason || ''})`); }
+    return 0;
+  }
+  const ids = [...new Set(ledger.entries.map((e) => e.ruleId))];
+  if (args.flags.json) { console.log(JSON.stringify(ids.map((rid) => ({ id: rid, state: stateOf(ledger, rid) })), null, 2)); return 0; }
+  if (!ids.length) { console.log('No rules in the lifecycle ledger yet.'); return 0; }
+  for (const rid of ids) console.log(`  ${rid.padEnd(40)} ${stateOf(ledger, rid)}`);
+  return 0;
+}