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

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' };
@@ -41,6 +42,22 @@ export function loadIR(scanRoot, id) {
   try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; }
 }
 
+function saveJson(scanRoot, id, name, doc) {
+  if (!ensureStateDir(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
+  const f = path.join(ruleDir(scanRoot, id), name);
+  return { ok: safeWriteState(f, JSON.stringify(doc, null, 2)), file: f };
+}
+function loadJson(scanRoot, id, name) { try { return JSON.parse(fs.readFileSync(path.join(ruleDir(scanRoot, id), name), 'utf8')); } catch { return null; } }
+/** The corpus a rule was synthesized on, kept so `rules evaluate <id>` needs no flag and the evidence is the same corpus. */
+export const saveCorpus = (r, id, spec) => saveJson(r, id, 'corpus.json', spec);
+export const loadCorpus = (r, id) => loadJson(r, id, 'corpus.json');
+/** Every synthesis attempt: strategy, match, score and why it did not pass. */
+export const saveSynthesis = (r, id, syn) => saveJson(r, id, 'synthesis.json', syn);
+export const loadSynthesis = (r, id) => loadJson(r, id, 'synthesis.json');
+/** The rule's provenance record (PRD 3 requirement 7). */
+export const saveProvenance = (r, id, doc) => saveJson(r, id, 'provenance.json', doc);
+export const loadProvenance = (r, id) => loadJson(r, id, 'provenance.json');
+
 export function saveEvaluation(scanRoot, id, evaluation) {
   if (!ensureStateDir(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
   const f = path.join(ruleDir(scanRoot, id), 'evaluation.json');
@@ -84,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);