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

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

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

@@ -0,0 +1,95 @@
+// Regression integration for promoted rules (PRD 3, requirement 8): a promoted rule joins a corpus every later rule and every later
+// run is held to, instead of being checked once at promotion and forgotten.
+//
+//   shared false-positive corpus   the SAFE code of every promoted rule (its patched, nearby-clean and protected variants) plus any file
+//                                  the operator drops in `.agentic-security/rule-compiler/fp-corpus/`. A new candidate must not fire
+//                                  on any of it, so rule N+1 cannot reintroduce the false positive rule N was built to avoid.
+//   regression run                 `rules regress` re-scores every PROMOTED rule against its own corpus, then against the shared false
+//                                  positive corpus, and reports any rule that no longer clears its gate (the matcher, the loader or
+//                                  another rule changed underneath it).
+// The rule-specific unit tests are the fixtures written at evaluation (the existing `rule test` convention); this module adds the cross-rule
+// part, which a per-rule check cannot see.
+import fs from 'node:fs';
+import path from 'node:path';
+import { statePath } from '../state-dir.js';
+import { buildCorpus, scoreRule } from './corpus.js';
+import { evaluateRule } from './promotion.js';
+import { runRule, normalizeCustomRule } from '../custom-rules.js';
+import { compileToCustomRule } from './ir.js';
+import { loadIR, loadCorpus, loadProvenance } from './store.js';
+import { stateOf } from './lifecycle.js';
+
+const FP_DIR = 'rule-compiler/fp-corpus';
+const MAX_FP_FILE = 256 * 1024;
+const MAX_FP_FILES = 500;
+const EXT_OF = { '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.ts': 'typescript', '.py': 'python', '.go': 'go', '.rb': 'ruby', '.java': 'java', '.rs': 'rust', '.cs': 'csharp', '.php': 'php' };
+
+/** Operator-supplied false positives (real code a rule should never flag). Plain files; symlinks and oversized files are ignored. */
+function operatorFalsePositives(root) {
+  const dir = statePath(root, ...FP_DIR.split('/'));
+  const out = [];
+  let names = [];
+  try { names = fs.readdirSync(dir).sort(); } catch { return out; }
+  for (const n of names.slice(0, MAX_FP_FILES)) {
+    const f = path.join(dir, n);
+    try {
+      const st = fs.lstatSync(f);
+      if (!st.isFile() || st.isSymbolicLink() || st.size > MAX_FP_FILE) continue;
+      out.push({ label: `operator-fp:${n}`, file: n, language: EXT_OF[path.extname(n).toLowerCase()] ?? 'any', code: fs.readFileSync(f, 'utf8') });
+    } catch { /* unreadable: skipped */ }
+  }
+  return out;
+}
+
+function promotedRuleIds(ledger) {
+  return [...new Set(ledger.entries.map((e) => e.ruleId))].filter((id) => stateOf(ledger, id) === 'PROMOTED');
+}
+
+/** The shared false-positive corpus as seen by `exceptId`: the safe code of every OTHER promoted rule, plus the operator's files. */
+export function sharedFalsePositiveCorpus(root, ledger, exceptId = null) {
+  const items = [];
+  for (const id of promotedRuleIds(ledger)) {
+    if (id === exceptId) continue;
+    const ir = loadIR(root, id); const spec = loadCorpus(root, id);
+    if (!ir || !spec || typeof spec.originalCode !== 'string') continue;
+    let corpus; try { corpus = buildCorpus(ir, spec); } catch { continue; }
+    for (const n of corpus.negatives) items.push({ label: `rule:${id}:${n.label}`, language: ir.languages[0] ?? 'any', code: n.code });
+  }
+  return [...items, ...operatorFalsePositives(root)];
+}
+
+const FILE_FOR_LANG = { 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' };
+
+/** Which shared false-positive items does this rule fire on? A rule is only run against items written in a language it applies to. */
+export function falsePositiveHits(ir, items) {
+  const { ok, doc } = compileToCustomRule(ir);
+  if (!ok) return [{ label: '(rule does not compile)' }];
+  const rule = normalizeCustomRule(doc);
+  if (!rule) return [{ label: '(rule would be rejected by the loader)' }];
+  const hits = [];
+  for (const it of items) {
+    const lang = it.language && it.language !== 'any' ? it.language : (ir.languages[0] ?? 'any');
+    if (!ir.languages.includes('any') && !ir.languages.includes(lang)) continue;
+    if (runRule(rule, FILE_FOR_LANG[lang] ?? 'x.txt', it.code).length > 0) hits.push({ label: it.label });
+  }
+  return hits;
+}
+
+/** Re-score every promoted rule (or one) against its own corpus and the shared false-positive corpus. */
+export function regressRules(root, ledger, { only = null, thresholds } = {}) {
+  const results = [];
+  for (const id of promotedRuleIds(ledger)) {
+    if (only && id !== only) continue;
+    const ir = loadIR(root, id); const spec = loadCorpus(root, id);
+    if (!ir || !spec || typeof spec.originalCode !== 'string') { results.push({ id, status: 'unverifiable', reasons: [!ir ? 'the rule IR is missing' : 'no evaluated corpus was kept for this rule (run rules evaluate --corpus again)'] }); continue; }
+    let ev; let corpus;
+    try { corpus = buildCorpus(ir, spec); ev = evaluateRule(ir, corpus, thresholds); } catch (e) { results.push({ id, status: 'broken', reasons: [`cannot be scored: ${String(e.message).slice(0, 120)}`] }); continue; }
+    const fp = falsePositiveHits(ir, sharedFalsePositiveCorpus(root, ledger, id));
+    const baseline = loadProvenance(root, id)?.benchmarkResults ?? null;
+    const reasons = [...ev.reasons];
+    if (fp.length) reasons.push(`fires on ${fp.length} item(s) of the shared false-positive corpus: ${fp.slice(0, 3).map((h) => h.label).join(', ')}${fp.length > 3 ? ', ...' : ''}`);
+    if (baseline && ev.score.recall != null && baseline.recall != null && ev.score.recall < baseline.recall) reasons.push(`recall fell from ${(baseline.recall * 100).toFixed(1)}% to ${(ev.score.recall * 100).toFixed(1)}% since promotion`);
+    results.push({ id, status: reasons.length ? 'regressed' : 'ok', reasons, precision: ev.score.precision, recall: ev.score.recall, protectedFailures: ev.score.protectedFailures, fpCorpusHits: fp.length });
+  }
+  return results;
+}

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

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { statePath, ensureStateDir, safeWriteState } from '../state-dir.js';
 import { newLedger, verifyLedger } from './lifecycle.js';
 import { compileToCustomRule } from './ir.js';
+import { verifyRulePack, loadTrustedKeys, signRulePack } from '../rule-pack-signing.js';
 
 const DIR = 'rule-compiler';
 const EXT = { javascript: 'js', typescript: 'ts', python: 'py', go: 'go', ruby: 'rb', java: 'java', rust: 'rs', csharp: 'cs', php: 'php', any: 'txt' };
@@ -100,13 +101,40 @@ export function publishCustomRule(scanRoot, ir) {
     ...(doc.match.pattern ? [`    pattern: ${JSON.stringify(doc.match.pattern)}`] : []),
     ...(doc.match.allOf ? [`    allOf:`, ...doc.match.allOf.map((p) => `      - ${JSON.stringify(p)}`), `    window: ${doc.match.window}`] : []),
     ...(doc.match.notMatch ? [`    notMatch: ${JSON.stringify(doc.match.notMatch)}`] : []),
+    ...(doc.match.fileRequires ? [`    fileRequires:`, ...doc.match.fileRequires.map((p) => `      - ${JSON.stringify(p)}`)] : []),
+    ...(doc.match.guardedBy ? [`    guardedBy: ${JSON.stringify(doc.match.guardedBy)}`, `    guardWindow: ${doc.match.guardWindow}`] : []),
+    ...(doc.match.excludeLine ? [`    excludeLine:`, ...doc.match.excludeLine.map((p) => `      - ${JSON.stringify(p)}`)] : []),
     `  message: ${JSON.stringify(doc.message)}`,
     '',
   ].join('\n');
   return { ok: safeWriteState(f, yamlText), file: f };
 }
 
+/** Sign a published rule with the operator's key (the same Ed25519 scheme `agentic-security-rule sign` uses). The key is never stored here. */
+export function signPublishedRule(file, privateKeyB64) {
+  try { signRulePack(file, privateKeyB64); return { ok: true }; } catch (e) { return { ok: false, reason: String(e.message).slice(0, 120) }; }
+}
+
+/**
+ * Will the scanner actually LOAD this promoted rule? Publishing a file is not the same as the scanner trusting it: rule packs are
+ * signature-checked (posture/rule-pack-signing.js) so that a rule dropped into a repository cannot run in someone's CI. A promoted rule
+ * the scanner would refuse is not a capability yet, so this is reported next to the lifecycle state instead of being assumed.
+ */
+export function packTrust(scanRoot, id) {
+  const file = statePath(scanRoot, 'rules', `${id}.yml`);
+  if (!fs.existsSync(file)) return { live: false, reason: 'not published', remediation: null };
+  let r;
+  const origErr = console.error; console.error = () => {};
+  try { r = verifyRulePack(file, loadTrustedKeys(scanRoot)); } finally { console.error = origErr; }
+  if (r.ok) return { live: true, via: r.passThrough ? 'signed, accepted in pass-through mode (no trusted keys are configured)' : `signed by ${r.keyId}`, reason: null, remediation: null };
+  if (r.reason === 'unsigned' && r.allowUnsigned) return { live: true, via: 'unsigned, accepted because AGENTIC_SECURITY_ALLOW_UNSIGNED_PACKS=1', reason: null, remediation: null };
+  const remediation = r.reason === 'unsigned'
+    ? `sign it (agentic-security-rule sign ${path.relative(process.cwd(), file) || file} with your key, or re-run promote with --sign-key <base64>), or opt in for this environment with AGENTIC_SECURITY_ALLOW_UNSIGNED_PACKS=1`
+    : (r.remediation ?? 'see the signing setup in bin/agentic-security-rule.js');
+  return { live: false, reason: r.reason, remediation };
+}
+
 export function unpublishCustomRule(scanRoot, id) {
   const f = statePath(scanRoot, 'rules', `${id}.yml`);
-  try { if (fs.existsSync(f)) fs.unlinkSync(f); return { ok: true }; } catch (e) { return { ok: false, reason: e.message }; }
+  try { for (const x of [f, `${f}.sig`]) if (fs.existsSync(x)) fs.unlinkSync(x); return { ok: true }; } catch (e) { return { ok: false, reason: e.message }; }
 }

package/src/posture/rule-pack-signing.js

@@ -198,9 +198,11 @@ export function signRulePack(rulePackPath, privateKeyB64) {
   const body = fs.readFileSync(rulePackPath);
   const privBytes = Buffer.from(privateKeyB64, 'base64');
   if (privBytes.length !== 32) throw new Error('private key must be 32 bytes (raw ed25519)');
+  // A raw 32-byte Ed25519 seed as a PKCS#8 key. (A JWK with only `d`, which this used to build, is rejected by current Node: it also
+  // requires the public `x`, so signing failed with "Invalid JWK OKP key" and no rule pack could be signed through this workflow.)
   const keyObj = crypto.createPrivateKey({
-    key: { kty: 'OKP', crv: 'Ed25519', d: privBytes.toString('base64url') },
-    format: 'jwk',
+    key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), privBytes]),
+    format: 'der', type: 'pkcs8',
   });
   const sig = crypto.sign(null, body, keyObj);
   fs.writeFileSync(rulePackPath + '.sig', sig);