@clear-capabilities/agentic-security-scanner 0.176.0 → 0.178.0

package/src/posture/fleet/enterprise-graph.js

@@ -22,7 +22,7 @@ const AUTH_CWES = new Set(['CWE-287', 'CWE-306', 'CWE-285', 'CWE-862', 'CWE-863'
 const edgeId = (type, from, to) => `edge:${type}:${from}:${to}`;
 const hash = (v) => createHash('sha256').update(JSON.stringify(v)).digest('hex');
 
-export function buildEnterpriseGraph({ manifest, dependencyGraph, discovered = null }) {
+export function buildEnterpriseGraph({ manifest, dependencyGraph, discovered = null, lineage = null }) {
   const nodes = new Map();
   const edges = new Map();
   const addNode = (n) => nodes.set(n.id, n);
@@ -50,7 +50,48 @@ export function buildEnterpriseGraph({ manifest, dependencyGraph, discovered = n
   // Edges found in the code. They share an id with a declared edge of the same type and endpoints, so the evidence list shows both; an
   // edge with ONLY discovered evidence is marked `discovered: true` so a query can say it rests on a code literal, not on a declaration.
   for (const d of discovered?.edges ?? []) for (const evidence of d.evidence) addEdge(d.type, d.from, d.to, evidence, true);
-  for (const e of edges.values()) e.discovered = e.evidence.every((x) => x.source === 'discovered-code-literal');
+  // Code Boundaries (each repository's own data flow graph, summarized): data classes the code handles, and destinations it sends to.
+  // These add to what the manifest declared and never replace it; a class the manifest did not declare is listed on the node so a path
+  // that exists only because of it can say so.
+  const aliasesOf = new Map([...manifest.repositories, ...(manifest.resources ?? [])].map((n) => [n.id, [n.id, ...(n.aliases ?? [])].map((a) => String(a).toLowerCase())]));
+  for (const [repoId, sum] of lineage ?? []) {
+    const node = nodes.get(repoId);
+    if (!node || !sum) continue;
+    const declared = new Set(node.dataClasses);
+    const found = (sum.dataClasses ?? []).filter((c) => !declared.has(c));
+    node.dataClasses = [...declared, ...found];
+    node.discoveredDataClasses = found;
+    const cb = (extra) => ({ source: 'code-boundaries', repo: repoId, declared: false, file: null, ...extra });
+    for (const d of sum.externalDestinations ?? []) {
+      if (!d.host) continue;
+      const first = d.host.split('.')[0];
+      for (const [target, names] of aliasesOf) {
+        if (target === repoId || !(names.includes(d.host) || names.includes(first))) continue;
+        const tn = nodes.get(target);
+        addEdge(tn?.type === 'external-provider' ? 'uses-provider' : 'calls', repoId, target, cb({ host: d.host, nodeKind: 'external' }), true);
+      }
+    }
+    for (const q of sum.queues ?? []) {
+      for (const [target, names] of aliasesOf) {
+        const tn = nodes.get(target);
+        if (tn?.type !== 'queue' || !names.includes(String(q.topic).toLowerCase())) continue;
+        if (q.operation === 'consume') addEdge('consumes', target, repoId, cb({ topic: q.topic }), true); else addEdge('produces', repoId, target, cb({ topic: q.topic }), true);
+      }
+    }
+    for (const st of sum.stores ?? []) {
+      for (const key of [st.host, st.database]) {
+        if (!key) continue;
+        const k = String(key).toLowerCase();
+        for (const [target, names] of aliasesOf) {
+          const tn = nodes.get(target);
+          if (tn?.type !== 'database' || !(names.includes(k) || names.includes(k.split('.')[0]))) continue;
+          addEdge('connects-to', repoId, target, cb({ store: st.subtype, name: key }), true);
+        }
+      }
+    }
+  }
+  const FOUND_IN_CODE = new Set(['discovered-code-literal', 'code-boundaries']);
+  for (const e of edges.values()) e.discovered = e.evidence.every((x) => FOUND_IN_CODE.has(x.source));
   return { schema: ENTERPRISE_GRAPH_SCHEMA, version: 1, organization: manifest.organization, nodes: [...nodes.values()], edges: [...edges.values()], digest: null };
 }
 
@@ -97,7 +138,7 @@ export function attackPaths({ graph, toDataClass, from = INTERNET, involving = n
     if (results.length >= maxPaths) { truncated = true; return; }
     if (targets.has(id) && nodePath.length > 1) {
       const inv = involving ? nodePath.filter((n) => involving.all.has(n)) : [];
-      if (!involving || inv.length) results.push({ nodes: [...nodePath], edges: edgePath.map((e) => e.id), involving: inv, discoveredEdges: edgePath.filter((e) => e.discovered).map((e) => e.id), evidence: edgePath.flatMap((e) => e.evidence.map((x) => ({ edge: e.id, ...x }))) });
+      if (!involving || inv.length) results.push({ nodes: [...nodePath], edges: edgePath.map((e) => e.id), involving: inv, discoveredEdges: edgePath.filter((e) => e.discovered).map((e) => e.id), discoveredDataClassNodes: nodePath.filter((n) => (nodeOf(graph, n)?.discoveredDataClasses ?? []).includes(toDataClass)), evidence: edgePath.flatMap((e) => e.evidence.map((x) => ({ edge: e.id, ...x }))) });
     }
     if (nodePath.length > maxDepth) { truncated = true; return; }
     for (const e of out.get(id) ?? []) if (!nodePath.includes(e.to)) walk(e.to, [...nodePath, e.to], [...edgePath, e]);

package/src/posture/fleet/job-runner.js

@@ -25,8 +25,8 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export const DEFAULTS = Object.freeze({ leaseMs: 30_000, heartbeatMs: 10_000, retryDelayMs: 2_000, pollMs: 100 });
 
 /** The default scan: one supervised child process per repository. Throws `{code: 'TIMEOUT'|'ERROR', message}`. */
-export async function childScan(repoPath, { timeoutMs, signal }) {
-  const r = await superviseSpawn(process.execPath, [SCAN_CHILD, repoPath], { cwd: repoPath, env: { ...process.env, AGENTIC_SECURITY_NO_STATE: '1' }, timeoutMs, signal, maxOutputBytes: 96 * 1024 * 1024 });
+export async function childScan(repoPath, { timeoutMs, signal, lineage = false }) {
+  const r = await superviseSpawn(process.execPath, [SCAN_CHILD, repoPath], { cwd: repoPath, env: { ...process.env, AGENTIC_SECURITY_NO_STATE: '1', ...(lineage ? { AGENTIC_SECURITY_LINEAGE_DEEP: '1' } : {}) }, timeoutMs, signal, maxOutputBytes: 96 * 1024 * 1024 });
   const fail = (code, message) => Object.assign(new Error(message), { code });
   if (r.timedOut) throw fail('TIMEOUT', `no result within ${Math.round(timeoutMs / 1000)}s`);
   if (r.cancelled) throw fail('CANCELLED', 'cancelled');
@@ -69,7 +69,7 @@ export function planRun({ manifest, manifestHash, store, runId = null, config =
  * Run (or continue) a planned run until no job is queued or leased by a live worker. Returns when the work is done, the signal
  * aborts, or `maxWaitMs` passes with only other workers' leases outstanding.
  */
-export async function runJobs({ manifest, store, runId, root, scan = childScan, workers = manifest.workers, leaseMs = DEFAULTS.leaseMs, heartbeatMs = DEFAULTS.heartbeatMs, retryDelayMs = DEFAULTS.retryDelayMs, pollMs = DEFAULTS.pollMs, maxWaitMs = null, signal, now = () => Date.now(), onEvent = () => {}, cacheDir = null, artifactDir = null, useCache = true }) {
+export async function runJobs({ manifest, store, runId, root, scan = childScan, scanOptions = {}, workers = manifest.workers, leaseMs = DEFAULTS.leaseMs, heartbeatMs = DEFAULTS.heartbeatMs, retryDelayMs = DEFAULTS.retryDelayMs, pollMs = DEFAULTS.pollMs, maxWaitMs = null, signal, now = () => Date.now(), onEvent = () => {}, cacheDir = null, artifactDir = null, useCache = true }) {
   const repoById = new Map(manifest.repositories.map((r) => [r.id, r]));
   const cacheD = cacheDir ?? statePath(root, 'fleet', 'cache');
   const artD = artifactDir ?? statePath(root, 'fleet', 'artifacts', runId);
@@ -102,7 +102,7 @@ export async function runJobs({ manifest, store, runId, root, scan = childScan,
       onEvent({ type: 'start', repo: job.repoId, attempt: job.attempts });
       const cached = useCache ? readCache(cacheD, job.cacheKey) : null;
       if (cached) {
-        const a = writeArtifact(job, { entry: cached.entry, findings: cached.findings, findingsTruncated: !!cached.findingsTruncated, cached: true });
+        const a = writeArtifact(job, { entry: cached.entry, findings: cached.findings, findingsTruncated: !!cached.findingsTruncated, lineage: cached.lineage ?? null, cached: true });
         const status = cached.entry?.scanHealth && cached.entry.scanHealth.status !== 'complete' ? 'partial' : 'succeeded';
         if (store.complete(job.jobId, job.epoch, { status, artifactSha256: a.sha256, summary: { total: cached.entry?.total ?? null, cached: true, artifact: path.basename(a.file) }, now: now() })) onEvent({ type: 'done', repo: job.repoId, cached: true, status });
         continue;
@@ -113,15 +113,15 @@ export async function runJobs({ manifest, store, runId, root, scan = childScan,
       let lost = false;
       const hb = setInterval(() => { if (!store.heartbeat(job.jobId, job.epoch, { now: now(), leaseMs })) { lost = true; ac.abort(); } }, heartbeatMs);
       try {
-        const out = await scan(repo.path, { timeoutMs: job.timeoutMs, signal: ac.signal });
+        const out = await scan(repo.path, { timeoutMs: job.timeoutMs, signal: ac.signal, ...scanOptions });
         clearInterval(hb);
         if (lost) { onEvent({ type: 'fenced', repo: job.repoId }); continue; }
         if (!out?.entry) throw Object.assign(new Error('the scan returned no entry'), { code: 'ERROR' });
         if (out.entry.ok === false) throw Object.assign(new Error(out.entry.error || 'the scan failed'), { code: 'ERROR' });
-        const a = writeArtifact(job, { entry: out.entry, findings: out.findings ?? [], findingsTruncated: !!out.findingsTruncated });
+        const a = writeArtifact(job, { entry: out.entry, findings: out.findings ?? [], findingsTruncated: !!out.findingsTruncated, lineage: out.lineage ?? null });
         const status = out.entry.scanHealth && out.entry.scanHealth.status !== 'complete' ? 'partial' : 'succeeded';
         if (store.complete(job.jobId, job.epoch, { status, artifactSha256: a.sha256, summary: { total: out.entry.total ?? null, cached: false, artifact: path.basename(a.file) }, now: now() })) {
-          if (useCache && status === 'succeeded') writeCache(cacheD, job.cacheKey, { entry: out.entry, findings: out.findings ?? [], findingsTruncated: !!out.findingsTruncated });
+          if (useCache && status === 'succeeded') writeCache(cacheD, job.cacheKey, { entry: out.entry, findings: out.findings ?? [], findingsTruncated: !!out.findingsTruncated, lineage: out.lineage ?? null });
           onEvent({ type: 'done', repo: job.repoId, cached: false, status });
         } else onEvent({ type: 'fenced', repo: job.repoId });
       } catch (e) {

package/src/posture/fleet/job-store.js

@@ -89,7 +89,9 @@ export async function createSqliteJobStore({ file }) {
   const { DatabaseSync } = await import('node:sqlite');
   if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   const db = new DatabaseSync(file);
-  db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;');
+  // the busy timeout comes FIRST: the very next statements (switching the journal mode, creating tables) take locks, and another process
+  // opening the same file at the same instant must wait for them instead of failing with "database is locked"
+  db.exec('PRAGMA busy_timeout = 5000; PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;');
   db.exec(SCHEMA);
   const tx = (fn) => { db.exec('BEGIN IMMEDIATE'); try { const r = fn(); db.exec('COMMIT'); return r; } catch (e) { try { db.exec('ROLLBACK'); } catch { /* already rolled back */ } throw e; } };
   const q = (sql, ...p) => db.prepare(sql).all(...p);

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/scan-child.js

@@ -8,6 +8,7 @@
 // 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@@';
@@ -21,7 +22,9 @@ async function main(repoPath) {
   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);
-  process.stdout.write(`${BEGIN}${JSON.stringify({ entry, findings, findingsTruncated: (captured?.findings?.length ?? 0) > MAX_FINDINGS })}${END}`);
+  // 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) {

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

@@ -127,7 +127,8 @@ const P = new Proxy({}, { get: (_t, k) => (k === Symbol.toPrimitive ? () => payl
 const res = new Proxy(function () {}, { get: () => res, apply: () => res });
 const fn = ${pick};
 if (typeof fn !== 'function') { console.error('the exported value is not a function'); process.exit(3); }
-try { await Promise.race([Promise.resolve(fn(${args.join(', ')})), new Promise((r) => setTimeout(r, 5000))]); } catch (e) { console.error('target threw:', String(e && e.message).slice(0, 200)); }
+let timer; try { await Promise.race([Promise.resolve(fn(${args.join(', ')})), new Promise((r) => { timer = setTimeout(r, 5000); })]); } catch (e) { console.error('target threw:', String(e && e.message).slice(0, 200)); }
+clearTimeout(timer);
 `;
 }
 

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

@@ -29,11 +29,33 @@ const CONTAINER_IMAGES = Object.freeze({
 
 const SIGNALS = { 134: 'SIGABRT', 135: 'SIGBUS', 136: 'SIGFPE', 132: 'SIGILL', 139: 'SIGSEGV' };
 
+// only language toolchains are probed; the container engine has its own, richer health check (`container.js`)
+const PROBED_TOOLS = new Set(['java', 'javac', 'python3', 'cc', 'gcc', 'dotnet']);
+const probeCache = new Map();
+/** A launcher that exists is not a toolchain that works: macOS ships /usr/bin/java and /usr/bin/python3 as stubs that only prompt for an
+ * install. A tool counts only if it answers its version flag, within a short timeout, with exit 0. */
+function toolWorks(file, name) {
+  if (probeCache.has(file)) return probeCache.get(file);
+  const args = name === 'java' || name === 'javac' ? ['-version'] : ['--version'];
+  let ok = false;
+  try { const r = spawnSync(file, args, { stdio: 'ignore', timeout: 8000 }); ok = r.status === 0; } catch { ok = false; }
+  probeCache.set(file, ok);
+  return ok;
+}
+
 function findTool(name, pathEnv = process.env.PATH || '') {
-  for (const dir of pathEnv.split(path.delimiter)) {
+  const dirs = pathEnv.split(path.delimiter);
+  // a configured JDK wins over whatever stub sits on PATH
+  if ((name === 'java' || name === 'javac') && process.env.JAVA_HOME) dirs.unshift(path.join(process.env.JAVA_HOME, 'bin'));
+  for (const dir of dirs) {
     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 */ }
+    try {
+      fs.accessSync(p, fs.constants.X_OK);
+      if (!fs.statSync(p).isFile()) continue;
+      const real = fs.realpathSync(p);
+      if (!PROBED_TOOLS.has(name) || toolWorks(real, name)) return real;
+    } catch { /* next */ }
   }
   return null;
 }

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

@@ -1,4 +1,4 @@
-// CLI surface: `agentic-security rules synthesize|evaluate|promote|status|rollback`.
+// CLI surface: `agentic-security rules synthesize|evaluate|promote|status|rollback|cost|regress`.
 //
 // 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
@@ -9,6 +9,8 @@
 // it never decides promotion).
 import fs from 'node:fs';
 import { statePath } from '../state-dir.js';
+import { packTrust, signPublishedRule } from './store.js';
+import { sharedFalsePositiveCorpus, falsePositiveHits, regressRules } from './regression.js';
 import { draftRuleIR, validateRuleIR, ruleIRDigest } from './ir.js';
 import { checkEligibility } from './eligibility.js';
 import { buildCorpus } from './corpus.js';
@@ -39,6 +41,7 @@ export async function cmdRules(args, root) {
   if (sub === 'status') return cmdStatus(args, root);
   if (sub === 'rollback') return cmdRollback(args, root);
   if (sub === 'cost') return cmdCost(args, root);
+  if (sub === 'regress') return cmdRegress(args, root);
   console.error('usage: rules synthesize <finding-id> --spec <file.json> [--auto] [--max-attempts N] | evaluate <rule-id> | promote <rule-id> | status [rule-id] | rollback <rule-id> | cost <rule-id>');
   return 4;
 }
@@ -61,13 +64,13 @@ async function cmdSynthesize(args, root) {
   const corpusSpec = { originalCode: spec.originalCode, patchedCode: spec.patchedCode ?? null, nearbyCleanCode: spec.nearbyCleanCode ?? [], protectedVariantsCode: spec.protectedVariantsCode ?? [] };
   const leak = checkLeakage(JSON.stringify(corpusSpec), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [], fileNames: spec.fileNames ?? [] });
   if (!leak.ok) { console.error(`Refusing: the material for this rule shows benchmark or answer-key signals (${leak.offendingTerms.join('; ')}). Nothing was written.`); return 4; }
-  if (args.flags.auto || !spec.match) {
+  if (args.flags.auto || (!spec.match && !spec.sink)) {
     if (!isStr(spec.originalCode)) { console.error('Automatic proposal needs originalCode (the vulnerable snippet) in the spec.'); return 4; }
     const { id, title, severity, cwe, family, languages, remediation } = spec;
     synthesis = synthesizeCandidate({ base: { id, title, severity, cwe, family, languages, remediation, originatingFindingId: finding.stableId ?? finding.id, evidenceState: elig.evidenceState }, corpusSpec, proposed: spec.match ?? null, maxAttempts: Number(args.flags['max-attempts']) || 6, leakageOk: true });
     for (const a of synthesis.attempts) console.log(`  attempt ${a.n}: ${a.strategy.padEnd(34)} ${a.valid ? `precision ${fmtPct(a.score.precision)}  recall ${fmtPct(a.score.recall)}  protected-failures ${a.score.protectedFailures}${a.pass ? '  PASS' : ''}` : `invalid (${a.errors[0]})`}`);
     if (!synthesis.best) { console.error('No valid candidate could be proposed from this material.'); return 1; }
-    finalSpec = { ...spec, match: synthesis.best.match };
+    finalSpec = { ...spec, ...(synthesis.best.match ? { match: synthesis.best.match } : {}), ...(synthesis.best.structure ?? {}) };
     console.log(synthesis.best.pass ? `  candidate meets the promotion gate on this corpus (not yet recorded as VALIDATED).` : `  no attempt met the gate; the best is kept as a CANDIDATE only: ${synthesis.best.reasons.join('; ')}`);
   }
   const ir = draftRuleIR({ ...finalSpec, originatingFindingId: finding.stableId ?? finding.id, originatingCommit: spec.originatingCommit ?? null, evidenceState: elig.evidenceState });
@@ -95,10 +98,17 @@ async function cmdEvaluate(args, root) {
   const corpusSpec = readJsonArg(args.flags.corpus) ?? loadCorpus(root, id);
   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);
+  // the corpus a rule is evaluated on is the evidence for it: keep it, so `rules regress` and the shared false-positive corpus use the SAME code
+  if (args.flags.corpus) saveCorpus(root, id, { ...(loadCorpus(root, id) ?? {}), ...corpusSpec });
   const leakage = checkLeakage(JSON.stringify({ ...corpusSpec, fileNames: undefined, discoveryCost: undefined }), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [], fileNames: corpusSpec.fileNames ?? [] });
   const gate = gatePromotion({ ir, corpus, leakageCheck: leakage, thresholds: args.flags.thresholds ? readJsonArg(args.flags.thresholds) : PROMOTION_DEFAULTS });
 
   const ledger = loadLedger(root);
+  // the shared false-positive corpus: the safe code of every other promoted rule, plus the operator's own files. Part of the gate.
+  const fpItems = sharedFalsePositiveCorpus(root, ledger, id);
+  const fpHits = falsePositiveHits(ir, fpItems);
+  gate.fpCorpus = { items: fpItems.length, hits: fpHits.map((h) => h.label) };
+  if (fpHits.length) { gate.pass = false; gate.reasons.push(`fires on ${fpHits.length} of ${fpItems.length} item(s) in the shared false-positive corpus: ${fpHits.slice(0, 3).map((h) => h.label).join(', ')}${fpHits.length > 3 ? ', ...' : ''}`); }
   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);
@@ -134,6 +144,9 @@ async function cmdPromote(args, root) {
   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; }
+  // other rules may have been promoted since this one was evaluated: hold it to the false-positive corpus as it is NOW
+  const fpNow = falsePositiveHits(ir, sharedFalsePositiveCorpus(root, ledger, id));
+  if (fpNow.length) { console.error(`Promotion refused: ${id} fires on ${fpNow.length} item(s) of the shared false-positive corpus (${fpNow.slice(0, 3).map((h) => h.label).join(', ')}). Re-evaluate or narrow the rule.`); return 1; }
   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' });
@@ -141,10 +154,29 @@ async function cmdPromote(args, root) {
   const prov = loadProvenance(root, id);
   if (prov) saveProvenance(root, id, { ...prov, promotionEvent: { at: new Date().toISOString(), actor: args.flags.actor || 'operator', reason: args.flags.reason || 'promoted', ruleHash: ruleIRDigest(ir) } });
   console.log(`Rule ${id}: VALIDATED -> PROMOTED. Published to ${pub.file}.`);
+  // Publishing is not trusting. Rule packs are signature-checked so a rule dropped into a repository cannot run in someone's CI; sign this
+  // one with the operator's key when there is one, and say plainly whether the scanner will load it.
+  const key = args.flags['sign-key'] ?? process.env.AGENTIC_SECURITY_PRIVATE_KEY;
+  if (key) { const sg = signPublishedRule(pub.file, key); console.log(sg.ok ? `  signed: ${pub.file}.sig` : `  could not sign (${sg.reason}); the rule is published unsigned`); }
+  const trust = packTrust(root, id);
+  console.log(trust.live ? `  The scanner will load it (${trust.via}).` : `  NOT LIVE YET: the scanner will refuse this rule (${trust.reason}). To make it live: ${trust.remediation}.`);
   if (!t.ok) console.error(t.reason);
   return 0;
 }
 
+/** `rules regress [rule-id]`: re-score every PROMOTED rule against its own corpus and the shared false-positive corpus. Exit 1 on any regression. */
+async function cmdRegress(args, root) {
+  const ledger = loadLedger(root);
+  if (ledger.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${ledger.tamperReason}).`); return 4; }
+  const only = args._[2] ?? null;
+  const results = regressRules(root, ledger, { only, thresholds: args.flags.thresholds ? readJsonArg(args.flags.thresholds) : undefined });
+  if (args.flags.json) console.log(JSON.stringify({ results }, null, 2));
+  else if (!results.length) console.log(only ? `No promoted rule ${only}.` : 'No rule is PROMOTED; nothing to regress.');
+  else for (const r of results) { console.log(`${r.id}: ${r.status.toUpperCase()}${r.precision != null ? `  precision ${fmtPct(r.precision)}  recall ${fmtPct(r.recall)}  false-positive corpus hits ${r.fpCorpusHits}` : ''}`); for (const m of r.reasons) console.log(`  - ${m}`); }
+  if (only && !results.length) return 4;
+  return results.every((r) => r.status === 'ok') ? 0 : 1;
+}
+
 async function cmdRollback(args, root) {
   const id = args._[2];
   if (!id) { console.error('usage: rules rollback <rule-id> [--reason text]'); return 4; }
@@ -165,16 +197,18 @@ async function cmdStatus(args, root) {
     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 || ''})`); 
+    else { console.log(`Rule ${id}: ${stateOf(ledger, id)}`);
+      if (stateOf(ledger, id) === 'PROMOTED') { const tr = packTrust(root, id); console.log(tr.live ? `  live: yes (${tr.via})` : `  live: NO, the scanner refuses it (${tr.reason}). ${tr.remediation}.`); }
+      for (const e of h) console.log(`  ${e.at}  ${e.from ?? '(new)'} -> ${e.to}  (${e.reason || ''})`); 
       const syn = loadSynthesis(root, id);
       if (syn?.attempts?.length) { console.log(`  synthesis: ${syn.attempts.length} attempt(s), best ${syn.best ? `${syn.best.strategy}${syn.best.pass ? ' (met the gate)' : ' (did not meet the gate)'}` : 'none'}`); }
     }
     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 (args.flags.json) { console.log(JSON.stringify(ids.map((rid) => ({ id: rid, state: stateOf(ledger, rid), ...(stateOf(ledger, rid) === 'PROMOTED' ? { live: packTrust(root, rid).live } : {}) })), 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)}`);
+  for (const rid of ids) console.log(`  ${rid.padEnd(40)} ${stateOf(ledger, rid)}${stateOf(ledger, rid) === 'PROMOTED' && !packTrust(root, rid).live ? '  (NOT LIVE: the scanner refuses it)' : ''}`);
   return 0;
 }
 

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

@@ -9,17 +9,13 @@
 // the score a rule gets here is the score it will actually produce once promoted.
 import { generateVariants } from './mutation.js';
 import { compileToCustomRule } from './ir.js';
-import { runRule } from '../custom-rules.js';
+import { runRule, normalizeCustomRule } from '../custom-rules.js';
 
+/** The rule exactly as the scanner would load it: through the loader's own normalizer, not a second implementation. */
 function toRuntimeRule(ir) {
   const { ok, doc, errs } = compileToCustomRule(ir);
   if (!ok) throw new Error(`cannot build corpus for an invalid rule IR: ${errs.join('; ')}`);
-  const regexes = doc.match.allOf ? doc.match.allOf.map((p) => new RegExp(p, 'g')) : [new RegExp(doc.match.pattern, 'g')];
-  return {
-    id: doc.id, title: doc.title, severity: doc.severity, cwe: doc.cwe, languages: doc.languages, message: doc.message,
-    regexes, requireAll: !!doc.match.allOf, windowLines: doc.match.window ?? 5,
-    notMatch: doc.match.notMatch ? new RegExp(doc.match.notMatch) : null,
-  };
+  return normalizeCustomRule(doc);
 }
 
 const EXT = { javascript: 'x.js', typescript: 'x.ts', python: 'x.py', go: 'x.go', ruby: 'x.rb', java: 'x.java', rust: 'x.rs', csharp: 'x.cs', php: 'x.php', any: 'x.txt' };

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

@@ -4,9 +4,20 @@
 // regex/allOf/notMatch/window engine; this module only adds PROVENANCE metadata around it.
 //
 // A rule's match semantics are deliberately the same closed vocabulary custom-rules.js
-// already supports (pattern | allOf+window | notMatch) — no new matching primitive is
-// introduced, so a promoted rule is exactly as auditable as a hand-written one.
+// already supports (pattern | allOf+window | notMatch, plus the structural fields below): no
+// separate matching engine is introduced, so a promoted rule is exactly as auditable as a hand-written one.
+//
+// The structural fields are REAL, not annotations: each is a regular expression and each compiles to a constraint the
+// runtime matcher enforces.
+//   source, propagator, sink   together they become a windowed co-occurrence (allOf) anchored on the SINK; a sink alone is the pattern
+//   sanitizer, dominatingGuard a hit is dropped when either matches within `guardWindow` lines before (or on) it
+//   frameworkConstraint        a file-level precondition (the file must contain it, wherever it is)
+//   exclusions                 a hit is dropped when its own line matches one
+//   languages                  the rule only runs on files of those languages
+// An explicit `match` always wins over a derived one. An AST pattern is NOT a field: the existing engine has no AST matcher for rules to
+// compile to, and a field the matcher ignored would be the old mistake (an annotation that looks like a constraint).
 import { sha256 } from '../proof-fabric/reproducer.js';
+import { normalizeCustomRule } from '../custom-rules.js';
 
 const RULE_IR_SCHEMA = 'agentic-security/rule-ir';
 const RULE_IR_VERSION = 1;
@@ -28,8 +39,9 @@ export function validateRuleIR(ir) {
   if (!isStr(ir.family)) errs.push('family required');
   if (!Array.isArray(ir.languages) || !ir.languages.length || !ir.languages.every((l) => VALID_LANGS.has(l))) errs.push('languages must be a non-empty array from the supported set');
   const m = ir.match;
-  if (!m || typeof m !== 'object') errs.push('match required');
-  else {
+  if (m == null && !isStr(ir.sink)) errs.push('match required (or at least a sink, from which one is derived)');
+  else if (m != null && typeof m !== 'object') errs.push('match must be an object');
+  else if (m) {
     const hasPattern = isStr(m.pattern);
     const hasAllOf = Array.isArray(m.allOf) && m.allOf.length > 0 && m.allOf.every(isStr);
     if (!hasPattern && !hasAllOf) errs.push('match needs a pattern or a non-empty allOf');
@@ -39,12 +51,20 @@ export function validateRuleIR(ir) {
       try { new RegExp(re); } catch { errs.push(`invalid regex: ${re}`); }
     }
   }
-  // Declarative-only hint fields (sink/source/propagator/sanitizer/dominatingGuard/frameworkConstraint): free text,
-  // never executable, carried for provenance/review only and NOT consulted by the matcher.
+  // Structural fields: each is a regular expression the matcher enforces (see the header). Free text is rejected, so a field can
+  // never look like a constraint while being ignored.
   for (const k of ['sink', 'source', 'propagator', 'sanitizer', 'dominatingGuard', 'frameworkConstraint']) {
-    if (ir[k] != null && !isStr(ir[k])) errs.push(`${k} must be a string when present`);
+    if (ir[k] == null) continue;
+    if (!isStr(ir[k])) { errs.push(`${k} must be a regular-expression string when present`); continue; }
+    try { new RegExp(ir[k]); } catch { errs.push(`${k} is not a valid regular expression`); }
+  }
+  if ((ir.source || ir.propagator) && !ir.sink && !ir.match) errs.push('a source or propagator needs a sink');
+  if (ir.window != null && !(Number.isInteger(ir.window) && ir.window > 0 && ir.window <= 200)) errs.push('window must be an integer in 1..200');
+  if (ir.guardWindow != null && !(Number.isInteger(ir.guardWindow) && ir.guardWindow > 0 && ir.guardWindow <= 200)) errs.push('guardWindow must be an integer in 1..200');
+  if (ir.exclusions != null) {
+    if (!(Array.isArray(ir.exclusions) && ir.exclusions.every(isStr))) errs.push('exclusions must be an array of regular-expression strings');
+    else for (const re of ir.exclusions) { try { new RegExp(re); } catch { errs.push(`invalid exclusion regex: ${re}`); } }
   }
-  if (ir.exclusions != null && !(Array.isArray(ir.exclusions) && ir.exclusions.every(isStr))) errs.push('exclusions must be an array of strings');
   if (!ir.provenance || typeof ir.provenance !== 'object') errs.push('provenance required');
   else {
     if (!isStr(ir.provenance.originatingFindingId)) errs.push('provenance.originatingFindingId required');
@@ -74,14 +94,37 @@ export function draftRuleIR({ id, title, severity, cwe, family, languages, match
 export function compileToCustomRule(ir) {
   const errs = validateRuleIR(ir);
   if (errs.length) return { ok: false, errs };
+  const alt = (...parts) => { const p = parts.filter(isStr); return p.length ? p.map((x) => `(?:${x})`).join('|') : null; };
+  // the base match: explicit wins; otherwise source -> propagator -> sink as a windowed co-occurrence, or a sink alone
+  let base = ir.match;
+  if (!base) {
+    // the SINK leads: the matcher anchors on the first pattern, and the finding, the guard window and the line exclusions all belong at
+    // the sink, where the flaw manifests. The window is symmetric, so the order of the others does not affect co-occurrence.
+    const chain = [ir.sink, ir.propagator, ir.source].filter(isStr);
+    base = chain.length > 1 ? { allOf: chain, window: ir.window ?? 8 } : { pattern: ir.sink };
+  }
+  const guard = alt(ir.sanitizer, ir.dominatingGuard);
   const doc = {
     id: `rule-compiler/${ir.id}`,
     title: ir.title,
     severity: ir.severity,
     cwe: ir.cwe,
     languages: ir.languages,
-    match: { ...(ir.match.pattern ? { pattern: ir.match.pattern } : {}), ...(ir.match.allOf ? { allOf: ir.match.allOf, window: ir.match.window ?? 5 } : {}), ...(ir.match.notMatch ? { notMatch: ir.match.notMatch } : {}) },
+    match: {
+      ...(base.pattern ? { pattern: base.pattern } : {}),
+      ...(base.allOf ? { allOf: base.allOf, window: base.window ?? 5 } : {}),
+      ...(base.notMatch ? { notMatch: base.notMatch } : {}),
+      ...(isStr(ir.frameworkConstraint) ? { fileRequires: [ir.frameworkConstraint] } : {}),
+      ...(guard ? { guardedBy: guard, guardWindow: ir.guardWindow ?? base.window ?? 5 } : {}),
+      ...(Array.isArray(ir.exclusions) && ir.exclusions.length ? { excludeLine: ir.exclusions } : {}),
+    },
     message: ir.remediation || `${ir.title} (${ir.cwe}, compiled from ${ir.provenance.originatingFindingId})`,
   };
+  // The loader has its own safety checks (nested quantifiers and so on). A rule it would refuse must not be reported as compiled,
+  // or it would score well here and silently never fire in a scan.
+  const origError = console.error; let loaderSaid = '';
+  console.error = (...a) => { loaderSaid = a.join(' '); };
+  let normalized; try { normalized = normalizeCustomRule(doc); } finally { console.error = origError; }
+  if (!normalized) return { ok: false, errs: [`the scanner's rule loader would reject this rule${loaderSaid ? `: ${loaderSaid.replace(/^agentic-security:\s*/, '').slice(0, 160)}` : ''}`] };
   return { ok: true, doc };
 }

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

@@ -62,7 +62,7 @@ export function proposeCandidates({ vulnerableCode, patchedCode = null }) {
   const vuln = onlyIn(vulnerableCode, patchedCode);
   const lines = vuln.length ? vuln : String(vulnerableCode).split('\n').filter(meaningful).map((l) => l.trim()).filter((l) => callNames(l).length);
   const out = []; const seen = new Set();
-  const add = (strategy, match) => { const k = JSON.stringify(match); if (!seen.has(k)) { seen.add(k); out.push({ strategy, match }); } };
+  const add = (strategy, match, structure = null) => { const k = JSON.stringify([match, structure]); if (!seen.has(k)) { seen.add(k); out.push({ strategy, ...(match ? { match } : {}), ...(structure ? { structure } : {}) }); } };
   for (const l of lines.slice(0, 3)) add('line-shape', { pattern: generalizeLine(l) });
   for (const l of lines.slice(0, 3)) {
     const sink = sinkOf(l);
@@ -71,6 +71,9 @@ export function proposeCandidates({ vulnerableCode, patchedCode = null }) {
   const sink = lines.map(sinkOf).find(Boolean);
   const src = SOURCES.find((s) => new RegExp(s).test(vulnerableCode));
   if (sink && src) add('source-and-sink', { allOf: [`${esc(sink)}\\s*\\(`, src], window: 6 });
+  // the same evidence as an explicit structure: a source and a sink the matcher enforces, so a sanitizer found in the patched code can
+  // later be added as a LOCAL guard (dropping one hit) instead of a file-level exclusion (silencing the whole file)
+  if (sink && src) add('structural', null, { source: src, sink: `${esc(sink)}\\s*\\(`, window: 6 });
   if (sink) add('sink-call', { pattern: `${esc(sink)}\\s*\\(` });
   return out;
 }
@@ -104,29 +107,31 @@ export function synthesizeCandidate({ base, corpusSpec, proposed = null, maxAtte
   for (const p of proposeCandidates({ vulnerableCode: corpusSpec.originalCode, patchedCode: corpusSpec.patchedCode })) queue.push(p);
   const names = safeNames({ vulnerableCode: corpusSpec.originalCode, patchedCode: corpusSpec.patchedCode });
   const attempts = []; const tried = new Set();
-  const tryOne = (strategy, match) => {
-    const key = JSON.stringify(match);
+  const tryOne = (strategy, match, structure = null) => {
+    const key = JSON.stringify([match, structure]);
     if (tried.has(key) || attempts.length >= cap) return null;
     tried.add(key);
-    const ir = draftRuleIR({ ...base, match });
+    const ir = draftRuleIR({ ...base, ...(match ? { match } : {}), ...(structure ?? {}) });
     const errs = validateRuleIR(ir);
-    if (errs.length) { attempts.push({ n: attempts.length + 1, strategy, match, valid: false, errors: errs, pass: false, reasons: errs }); return null; }
+    if (errs.length) { attempts.push({ n: attempts.length + 1, strategy, match: match ?? null, structure, valid: false, errors: errs, pass: false, reasons: errs }); return null; }
     const corpus = buildCorpus(ir, corpusSpec);
     const ev = evaluateRule(ir, corpus, thresholds);
-    const rec = { n: attempts.length + 1, strategy, match, valid: true, pass: ev.pass && leakageOk, reasons: ev.reasons, score: summary(ev.score), ir, corpusSizes: { positives: corpus.positives.length, negatives: corpus.negatives.length } };
+    const rec = { n: attempts.length + 1, strategy, match: match ?? null, structure, valid: true, pass: ev.pass && leakageOk, reasons: ev.reasons, score: summary(ev.score), ir, corpusSizes: { positives: corpus.positives.length, negatives: corpus.negatives.length } };
     attempts.push(rec);
     return { rec, ev };
   };
   for (let qi = 0; qi < queue.length && attempts.length < cap; qi++) {
-    const first = tryOne(queue[qi].strategy, queue[qi].match);
+    const q = queue[qi];
+    const first = tryOne(q.strategy, q.match, q.structure);
     if (!first) continue;
     if (first.rec.pass) break;
     // revise from the failure: a negative that fired means the safe version is not excluded yet
     const fired = first.ev.score.negatives.filter((n) => n.fired);
     const rx = safeRegex(names);
-    if (fired.length && rx && !queue[qi].match.notMatch) { const r = tryOne(`${queue[qi].strategy}+exclude-safe`, { ...queue[qi].match, notMatch: rx }); if (r?.rec.pass) break; }
+    if (fired.length && rx && q.structure && !q.structure.sanitizer) { const r = tryOne(`${q.strategy}+sanitizer`, null, { ...q.structure, sanitizer: rx }); if (r?.rec.pass) break; }
+    else if (fired.length && rx && q.match && !q.match.notMatch) { const r = tryOne(`${q.strategy}+exclude-safe`, { ...q.match, notMatch: rx }); if (r?.rec.pass) break; }
   }
   const valid = attempts.filter((a) => a.valid);
   const best = valid.length ? [...valid].sort((a, b) => quality({ pass: b.pass, score: b.score }) - quality({ pass: a.pass, score: a.score }))[0] : null;
-  return { attempts: attempts.map(({ ir, ...rest }) => rest), best: best ? { strategy: best.strategy, match: best.match, pass: best.pass, score: best.score, reasons: best.reasons } : null, exhausted: !attempts.some((a) => a.pass) };
+  return { attempts: attempts.map(({ ir, ...rest }) => rest), best: best ? { strategy: best.strategy, match: best.match, structure: best.structure, pass: best.pass, score: best.score, reasons: best.reasons } : null, exhausted: !attempts.some((a) => a.pass) };
 }