@clear-capabilities/agentic-security-scanner 0.128.1 → 0.132.0

package/src/posture/attestation.js

@@ -0,0 +1,202 @@
+// R4 — determinism as a contract.
+//
+// Determinism has been an implementation property of this engine (stable sorts,
+// no Date.now() in ids, `--deterministic`) with no way for a third party to
+// VERIFY it. This module turns it into something checkable: a stable digest
+// over the finding set, bound to the engine version, ruleset version, and
+// bundle hash that produced it.
+//
+// WHAT THE DIGEST IS INDEPENDENT OF (by construction):
+//   - the ORDER findings were emitted in (entries are canonicalised, then sorted)
+//   - run ids, timestamps, durations, and every other field not on the
+//     identity allowlist below — canonicalisation is an ALLOWLIST, not a
+//     denylist, so a new non-deterministic field cannot silently leak in
+//   - path separator style, and the absolute prefix when `root` is supplied
+//
+// WHAT IT IS NOT INDEPENDENT OF (all of these are real differences):
+//   - a changed severity, file, line, rule id, cwe, or vuln title
+//   - a finding appearing or disappearing (including a duplicate — multiplicity
+//     is preserved; two identical findings are not collapsed into one)
+//   - the engine version, ruleset version, or bundle sha
+//
+// WHAT THIS PROVES, AND WHAT IT DOES NOT (read before quoting it at anyone):
+//   PROVES — two finding sets carrying the same digest under the same
+//   canonicalisation are the same set of findings, modulo emission order and
+//   the excluded volatile fields; and (when signed) that the attestation was
+//   produced on an install holding this HMAC key.
+//   DOES NOT PROVE — cross-machine reproducibility. Nothing here demonstrates
+//   that a different host, OS, Node version, or toolchain produces the same
+//   finding set; several detectors are environment-sensitive (e.g. the Python
+//   AST path is used when python3 is available and falls back to regex when it
+//   is not, which can change what is found). Two runs on two machines agreeing
+//   would be evidence FOR reproducibility, but that experiment has not been
+//   run here and this module does not assert its outcome. The signature is a
+//   symmetric per-install HMAC, so it is tamper-evidence for the operator, not
+//   third-party non-repudiation.
+//
+// Identity fields deliberately EXCLUDE `parser` and `family`: `parser` records
+// which analysis engine fired, which is environment-sensitive (see the python3
+// case above), so including it would make the digest report an environment
+// difference as a findings difference. The finding's identity — where it is
+// and what it is — is fully captured without it.
+//
+// SIGNING: reuses `integrity.js`'s per-install HMAC key handling verbatim
+// (`signLastScan`, keyed from $AGENTIC_SECURITY_HMAC_KEY or the 0600 key file
+// at $XDG_CONFIG_HOME/agentic-security/scan-key). No second key mechanism is
+// introduced. `integrity.verifyLastScan` is NOT reused because it verifies a
+// body against a sibling `.sig` FILE; an attestation carries its signature
+// inline, so verification re-signs and compares in constant time here.
+//
+// NO THROWING (posture/CLAUDE.md convention): malformed input yields an empty
+// canonical set or an `{ok:false, reason}` refusal, never an exception.
+
+import * as crypto from 'node:crypto';
+import { signLastScan } from './integrity.js';
+
+export const ATTESTATION_CANONICALISATION = 'agentic-security/run-attestation-canon-v1';
+
+const PROVES =
+  'Two finding sets with this digest, under this canonicalisation, are the same findings ' +
+  '(same rule id, severity, file, line, cwe, vuln, and multiplicity) produced by the same ' +
+  'engine version, ruleset version, and bundle — regardless of emission order.';
+const DOES_NOT_PROVE =
+  'It does not prove cross-machine reproducibility: this attestation is one run on one machine, ' +
+  'nothing here compares a second machine, OS, or Node version, and some detectors are ' +
+  'environment-sensitive. That property is tested separately by the determinism-attest / ' +
+  'determinism-compare CI jobs, which run the same commit on two operating systems and fail ' +
+  'unless the digests match — evidence about the ENGINE, not about this attestation. ' +
+  'A signature, when present, is a symmetric per-install HMAC — tamper-evidence for this ' +
+  'install, not third-party non-repudiation.';
+
+function _str(v) { return v === undefined || v === null ? '' : String(v); }
+
+// Normalise a file path: separators to '/', drop a supplied absolute root,
+// drop a leading './'. Everything else is left alone — guessing at a root we
+// were not given would make two genuinely different files collide.
+function _normPath(file, root) {
+  let p = _str(file).replace(/\\/g, '/');
+  if (root) {
+    let r = String(root).replace(/\\/g, '/').replace(/\/+$/, '');
+    if (r && p.startsWith(r + '/')) p = p.slice(r.length + 1);
+    else if (r && p === r) p = '';
+  }
+  return p.replace(/^\.\//, '');
+}
+
+/**
+ * The canonical, order-independent representation of a finding set: one
+ * tab-joined record per finding over the identity allowlist, sorted.
+ * Multiplicity is preserved (duplicates are NOT deduped).
+ */
+function canonicaliseFindings(findings, { root } = {}) {
+  const list = Array.isArray(findings) ? findings : [];
+  const rows = [];
+  for (const f of list) {
+    if (!f || typeof f !== 'object') continue;
+    rows.push([
+      _str(f.id),
+      _str(f.severity),
+      _normPath(f.file, root),
+      _str(f.line),
+      _str(f.cwe),
+      _str(f.vuln),
+    ].join('\t'));
+  }
+  return rows.sort();
+}
+
+/**
+ * Compute the run attestation.
+ *
+ * @param {object[]} findings     the finding set (any order)
+ * @param {string}   engineVersion
+ * @param {string}   rulesetVersion
+ * @param {string}   bundleSha
+ * @param {string}  [root]        scan root, used to relativise absolute paths
+ * @param {boolean} [sign]        attach a per-install HMAC over the digest
+ */
+export function computeRunAttestation({
+  findings, engineVersion, rulesetVersion, bundleSha, root, sign = false,
+} = {}) {
+  const entries = canonicaliseFindings(findings, { root });
+  const payload = JSON.stringify({
+    canonicalisation: ATTESTATION_CANONICALISATION,
+    engineVersion: _str(engineVersion),
+    rulesetVersion: _str(rulesetVersion),
+    bundleSha: _str(bundleSha),
+    findingCount: entries.length,
+    entries,
+  });
+  const digest = crypto.createHash('sha256').update(payload).digest('hex');
+  const att = {
+    digest,
+    algorithm: 'sha256',
+    findingCount: entries.length,
+    engineVersion: _str(engineVersion),
+    rulesetVersion: _str(rulesetVersion),
+    bundleSha: _str(bundleSha),
+    canonicalisation: ATTESTATION_CANONICALISATION,
+    proves: PROVES,
+    doesNotProve: DOES_NOT_PROVE,
+  };
+  if (sign) {
+    try {
+      att.signature = signLastScan(digest);
+      att.signatureScope = 'per-install-hmac';
+    } catch { /* signing is best-effort; an unsigned attestation is still valid */ }
+  }
+  return att;
+}
+
+/**
+ * Re-derive the attestation from a finding set and compare.
+ * @returns {{ok: boolean, reason: string}}
+ */
+export function verifyRunAttestation(attestation, inputs = {}) {
+  if (!attestation || typeof attestation !== 'object') {
+    return { ok: false, reason: 'no attestation supplied' };
+  }
+  if (attestation.canonicalisation !== ATTESTATION_CANONICALISATION) {
+    return {
+      ok: false,
+      reason: `unknown canonicalisation "${_str(attestation.canonicalisation)}" — ` +
+              `this build verifies "${ATTESTATION_CANONICALISATION}" only`,
+    };
+  }
+  if (typeof attestation.digest !== 'string' || !/^[0-9a-f]{64}$/.test(attestation.digest)) {
+    return { ok: false, reason: 'attestation carries no sha256 digest' };
+  }
+  for (const k of ['engineVersion', 'rulesetVersion', 'bundleSha']) {
+    if (_str(inputs[k]) !== _str(attestation[k])) {
+      return { ok: false, reason: `${k} mismatch: attested "${_str(attestation[k])}", got "${_str(inputs[k])}"` };
+    }
+  }
+  const recomputed = computeRunAttestation({
+    findings: inputs.findings,
+    engineVersion: inputs.engineVersion,
+    rulesetVersion: inputs.rulesetVersion,
+    bundleSha: inputs.bundleSha,
+    root: inputs.root,
+  });
+  if (recomputed.findingCount !== attestation.findingCount) {
+    return {
+      ok: false,
+      reason: `finding count mismatch: attested ${attestation.findingCount}, got ${recomputed.findingCount}`,
+    };
+  }
+  if (recomputed.digest !== attestation.digest) {
+    return { ok: false, reason: 'digest mismatch — the finding set is not the one attested' };
+  }
+  if (attestation.signature) {
+    let expected;
+    try { expected = signLastScan(attestation.digest); }
+    catch { return { ok: false, reason: 'signature present but no key material available to check it' }; }
+    const a = Buffer.from(String(attestation.signature), 'hex');
+    const b = Buffer.from(expected, 'hex');
+    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+      return { ok: false, reason: 'signature does not verify under this install key' };
+    }
+    return { ok: true, reason: 'digest and per-install signature verify' };
+  }
+  return { ok: true, reason: 'digest verifies (unsigned attestation)' };
+}

package/src/posture/auditor-walkthrough.js

@@ -161,11 +161,20 @@ export function evaluateFramework(scanRoot, fw, scan) {
           'mcp-tools':            '.../scanner/src/mcp/tools.js',
         };
         const target = ARTIFACT[mod];
-        if (target && fs.existsSync(path.join(scanRoot, STATE, target))) {
-          obs.push(`✓ ${mod}: ${target} present.`);
+        // A '.../' sentinel marks a source-relative artifact (project source,
+        // e.g. a hook or agent file) — resolve it against the scan root itself.
+        // Everything else is a runtime artifact under the STATE dir. Without
+        // this, `path.join(scanRoot, STATE, '.../x')` never resolves and the
+        // control falsely reads "not present" for every project.
+        const resolved = !target ? null
+          : target.startsWith('.../') ? path.join(scanRoot, target.slice(4))
+          : path.join(scanRoot, STATE, target);
+        const label = target ? target.replace(/^\.\.\.\//, '') : '(unmapped)';
+        if (resolved && fs.existsSync(resolved)) {
+          obs.push(`✓ ${mod}: ${label} present.`);
           anySignal = true;
         } else {
-          obs.push(`✗ ${mod}: expected ${target || '(unmapped)'} not present.`);
+          obs.push(`✗ ${mod}: expected ${label} not present.`);
           allCleared = false;
         }
       } else if (m.startsWith('rule:')) {

package/src/posture/compliance-policy.js

@@ -39,7 +39,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 
 const POLICY_FILE = 'compliance.policy.yml';
 

package/src/posture/corpus-enroll.js

@@ -0,0 +1,303 @@
+// R2's differentiator — auto-enrol an execution-proven finding as a permanent
+// CVE-replay corpus entry.
+//
+// The compounding asset: a finding that was PROVEN by execution becomes a
+// regression test that the baseline gate defends forever. Every exploit the
+// pipeline proves once, it can never silently stop detecting.
+//
+// THE CENTRAL RULE: nothing is written to the corpus that has not been scored.
+// The v0.106.0 failure — fixtures committed without verifying they actually
+// score, which then broke the gate for everyone — is the exact mistake this
+// module must not automate. So enrolment builds the entry in a TEMPORARY
+// directory, scans `pre/` and `post/` with the same matcher the gate uses
+// (`corpus-match.js`), and moves it into the corpus only on `pre:TP post:TN`.
+// A candidate that does not score is discarded and the reason returned. There
+// is no force flag and no "probably fine" path.
+//
+// WHY A FIX IS MANDATORY. An entry needs a `post/` that scores TN, and the
+// only honest source of one is a real fix. Enrolment therefore refuses a
+// finding with no fixed content rather than synthesising a `post/` by deleting
+// the vulnerable line — that would produce an entry that passes for a reason
+// unrelated to the vulnerability, which is worse than no entry.
+//
+// WHY `capability/` AND NOT `regression/`. `regression/` is the CI-gated tier
+// and graduation into it is a human decision with a stated policy (five
+// consecutive passing snapshots — see bench/cve-replay/CONTRIBUTING.md). An
+// automated writer promoting straight into the gated tier would let a machine
+// decide what blocks everyone's build. New entries land in `capability/`,
+// already passing, and graduate on the existing policy.
+//
+// NOTHING THROWS (posture convention): every path returns
+// `{ok:false, refused:true, reason}` instead.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { preHit, postHit, matcherFor } from './corpus-match.js';
+
+const DEFAULT_TIER = 'capability';
+
+// Entry ids must be safe to use as a directory name and stable across runs.
+const ID_SAFE = /^[A-Za-z0-9._-]+$/;
+
+function refuse(reason) { return { ok: false, refused: true, reason }; }
+
+// A finding is enrollable only if the pipeline actually RAN its exploit. This
+// re-checks the evidence rather than trusting `proofTier` alone: the tier is a
+// string on an object that may have crossed a process boundary, and the
+// consequence of trusting a forged one is a permanent corpus entry.
+export function isEnrollable(finding) {
+  if (!finding || typeof finding !== 'object') return refuse('no finding supplied');
+  if (finding.proofTier !== 'execution-proven') {
+    return refuse(
+      `only execution-proven findings may enrol; this one is '${finding.proofTier || 'untiered'}'. `
+      + 'A statically-reasoned finding has not earned a permanent regression entry.',
+    );
+  }
+  const ev = finding.proofEvidence;
+  if (!ev || ev.ran !== true) {
+    return refuse('proofEvidence does not record a run (ran !== true) — the tier is not backed by evidence');
+  }
+  if (ev.tier !== 'execution-proven') {
+    return refuse(`proofEvidence.tier ('${ev.tier}') disagrees with proofTier — refusing rather than picking one`);
+  }
+  if (!ev.observed) {
+    return refuse('proofEvidence records no observed effect — an execution-proven tier with nothing observed is not evidence');
+  }
+  return { ok: true };
+}
+
+function _slug(s, fallback) {
+  const out = String(s || '').trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return out || fallback;
+}
+
+/**
+ * The entry id. Derived from the finding so re-enrolling the same finding is
+ * idempotent (it will be refused as a duplicate) rather than accumulating
+ * near-identical entries.
+ */
+export function entryIdFor(finding) {
+  const fam = _slug(finding?.family || finding?.cwe, 'finding');
+  const sid = _slug(finding?.stableId || finding?.id, 'unknown');
+  return `proven-${fam}-${sid}`.slice(0, 120);
+}
+
+/**
+ * Build the manifest + file map for a candidate entry, without writing it.
+ *
+ * @param {object} finding      an execution-proven finding
+ * @param {object} opts
+ * @param {object} opts.preFiles   rel→content, the VULNERABLE tree
+ * @param {object} opts.postFiles  rel→content, the FIXED tree
+ */
+export function buildCandidate(finding, { preFiles, postFiles, addedAt } = {}) {
+  const gate = isEnrollable(finding);
+  if (!gate.ok) return gate;
+
+  if (!finding.cwe) return refuse('finding has no cwe — the manifest matcher would be meaningless');
+  if (!finding.vuln) return refuse('finding has no vuln — nothing to match on');
+  if (!finding.file) return refuse('finding has no file — cannot name the expected file');
+
+  const pre = preFiles && typeof preFiles === 'object' ? preFiles : null;
+  const post = postFiles && typeof postFiles === 'object' ? postFiles : null;
+  if (!pre || !Object.keys(pre).length) return refuse('no pre/ content supplied — nothing to prove the detector fires on');
+  if (!post || !Object.keys(post).length) {
+    return refuse(
+      'no post/ content supplied. An entry with no fixed tree cannot score post:TN, and '
+      + 'synthesising one by deleting the vulnerable code would pass for the wrong reason.',
+    );
+  }
+
+  // A `post` identical to `pre` cannot be a fix. Catching it here turns a
+  // guaranteed post:FP into a clear refusal.
+  const same = Object.keys(pre).length === Object.keys(post).length
+    && Object.entries(pre).every(([k, v]) => post[k] === v);
+  if (same) return refuse('post/ is byte-identical to pre/ — no fix was applied, so the entry cannot score post:TN');
+
+  for (const [label, files] of [['pre', pre], ['post', post]]) {
+    for (const [rel, content] of Object.entries(files)) {
+      if (typeof content !== 'string') return refuse(`${label}/${rel} content is not a string`);
+      if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+        return refuse(`${label}/${rel} escapes the entry directory`);
+      }
+    }
+  }
+
+  const id = entryIdFor(finding);
+  if (!ID_SAFE.test(id)) return refuse(`derived entry id '${id}' is not a safe directory name`);
+
+  const expectedFile = path.basename(String(finding.file));
+  if (!Object.keys(pre).some(rel => path.basename(rel) === expectedFile)) {
+    return refuse(`the finding's file '${expectedFile}' is not among the pre/ files — the entry would not test the finding`);
+  }
+
+  const manifest = {
+    cve: id,
+    cwe: finding.cwe,
+    family: finding.family || 'unknown',
+    language: finding.language || _languageOf(expectedFile),
+    summary: `execution-proven ${finding.family || finding.cwe}: ${String(finding.vuln).slice(0, 120)}`,
+    expected: {
+      file: expectedFile,
+      // Match on the exact vuln string this finding carried. A broader regex
+      // would let an unrelated detector satisfy the entry.
+      vuln_match: _escapeRegex(String(finding.vuln)),
+    },
+    source: 'execution-proven',
+    added_at: addedAt || new Date().toISOString().slice(0, 10),
+    provenance: {
+      stableId: finding.stableId || null,
+      proofBackend: finding.proofEvidence?.backend || null,
+      observed: finding.proofEvidence?.observed || null,
+      provenAt: finding.proofEvidence?.at || null,
+    },
+  };
+
+  return { ok: true, id, manifest, preFiles: pre, postFiles: post };
+}
+
+function _escapeRegex(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function _languageOf(file) {
+  const ext = path.extname(file).toLowerCase();
+  return {
+    '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.ts': 'typescript', '.tsx': 'typescript', '.jsx': 'javascript',
+    '.py': 'python', '.java': 'java', '.go': 'go', '.rb': 'ruby',
+    '.php': 'php', '.cs': 'csharp', '.rs': 'rust',
+  }[ext] || 'unknown';
+}
+
+function _writeTree(dir, files) {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+  }
+}
+
+/**
+ * Materialise a candidate into a staging directory and SCORE it, using the
+ * same matcher the corpus gate uses.
+ *
+ * @param {function} runScan  injected so this module stays free of an engine
+ *   import cycle and so tests can drive it without a full scan.
+ * @returns {{ok:boolean, status:string, preHit:boolean, postHit:boolean, reason?:string}}
+ */
+async function scoreCandidate(candidate, runScan, { stagingDir } = {}) {
+  const dir = stagingDir || fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-cand-'));
+  try {
+    const preDir = path.join(dir, 'pre');
+    const postDir = path.join(dir, 'post');
+    fs.mkdirSync(preDir, { recursive: true });
+    fs.mkdirSync(postDir, { recursive: true });
+    _writeTree(preDir, candidate.preFiles);
+    _writeTree(postDir, candidate.postFiles);
+    fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(candidate.manifest, null, 2) + '\n', 'utf8');
+
+    const matcher = matcherFor(candidate.manifest);
+    let pre, post;
+    try {
+      ({ scan: pre } = await runScan(preDir));
+    } catch (e) {
+      return { ok: false, status: 'scan-error', preHit: false, postHit: false, reason: `pre/ scan failed: ${e.message}` };
+    }
+    try {
+      ({ scan: post } = await runScan(postDir));
+    } catch (e) {
+      return { ok: false, status: 'scan-error', preHit: false, postHit: false, reason: `post/ scan failed: ${e.message}` };
+    }
+
+    const hitPre = preHit(pre, candidate.manifest, matcher);
+    const hitPost = postHit(post, candidate.manifest, matcher);
+    const status = `pre:${hitPre ? 'TP' : 'FN'} post:${hitPost ? 'FP' : 'TN'}`;
+
+    if (!hitPre) {
+      return {
+        ok: false, status, preHit: hitPre, postHit: hitPost, dir,
+        reason: 'the detector does not fire on pre/ — the entry would be committed already failing. '
+              + 'A PoC proved this finding at runtime but the minimised fixture does not reproduce it statically.',
+      };
+    }
+    if (hitPost) {
+      return {
+        ok: false, status, preHit: hitPre, postHit: hitPost, dir,
+        reason: 'the detector still fires on post/ — the fix does not clear the finding, so the entry cannot score TN.',
+      };
+    }
+    return { ok: true, status, preHit: hitPre, postHit: hitPost, dir };
+  } catch (e) {
+    return { ok: false, status: 'error', preHit: false, postHit: false, reason: e.message };
+  }
+}
+
+/**
+ * The full path: gate → build → score → commit.
+ *
+ * Writes into `<corpusRoot>/<tier>/<id>/` ONLY when the candidate scored
+ * `pre:TP post:TN`. Anything else leaves the corpus untouched.
+ */
+export async function enrollProvenFinding(finding, {
+  corpusRoot, preFiles, postFiles, runScan, tier = DEFAULT_TIER, addedAt, dryRun = false,
+} = {}) {
+  if (!corpusRoot) return refuse('no corpusRoot supplied');
+  if (typeof runScan !== 'function') return refuse('no runScan supplied — an entry may not be committed unscored');
+
+  const candidate = buildCandidate(finding, { preFiles, postFiles, addedAt });
+  if (!candidate.ok) return candidate;
+
+  const dest = path.join(corpusRoot, tier, candidate.id);
+  if (fs.existsSync(dest)) {
+    return refuse(`entry '${candidate.id}' already exists in ${tier}/ — refusing to overwrite a corpus entry`);
+  }
+
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'corpus-cand-'));
+  try {
+    const scored = await scoreCandidate(candidate, runScan, { stagingDir: staging });
+    if (!scored.ok) {
+      return {
+        ok: false, refused: true, id: candidate.id, status: scored.status,
+        reason: `not enrolled (${scored.status}): ${scored.reason}`,
+      };
+    }
+    if (dryRun) {
+      return { ok: true, dryRun: true, id: candidate.id, status: scored.status, dir: null, manifest: candidate.manifest };
+    }
+
+    // Scan state accumulated inside the staged trees must not be committed —
+    // it would be scanned as part of the fixture on the next run.
+    _stripState(staging);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.renameSync(staging, dest);
+    return {
+      ok: true,
+      id: candidate.id,
+      tier,
+      status: scored.status,
+      dir: dest,
+      manifest: candidate.manifest,
+      // Said explicitly because a caller that stops here leaves the repo in a
+      // state where the gate reports a nudge rather than a pass.
+      followUp: 'run `npm run bench:cve-replay:update-baseline` and commit the regenerated corpus-baseline.json',
+    };
+  } catch (e) {
+    return refuse(`enrolment failed: ${e.message}`);
+  } finally {
+    // If the rename happened, staging no longer exists and this is a no-op.
+    try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+function _stripState(dir) {
+  for (const sub of ['pre', 'post']) {
+    const s = path.join(dir, sub, '.agentic-security');
+    try { fs.rmSync(s, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+// `scoreCandidate` is deliberately NOT exported: an external caller could
+// score a candidate and then write it by some other route, which is exactly
+// the unscored-write path this module exists to make unavailable. Enrolment
+// scores and writes as one operation or not at all.
+export const _internals = { DEFAULT_TIER, scoreCandidate, _languageOf, _escapeRegex, _stripState };

package/src/posture/corpus-match.js

@@ -0,0 +1,52 @@
+// How a CVE-replay corpus entry is scored against a scan result.
+//
+// Extracted from `bench/cve-replay/runner.mjs` so the corpus GATE and corpus
+// ENROLLMENT (`corpus-enroll.js`) cannot drift apart. That drift is not
+// hypothetical: enrollment only writes an entry it has verified scores
+// `pre:TP post:TN`, and if it verified that with a different matcher than the
+// gate uses, it would cheerfully commit entries that fail CI. One
+// implementation, two callers.
+//
+// THE PRE/POST ASYMMETRY IS DELIBERATE AND PRESERVED VERBATIM. The `pre`
+// matcher accepts a hit on `vuln` OR `family` and regex-tests `cwe`; the
+// `post` matcher is strict on `vuln` and requires an exact `cwe`. This means
+// an entry faces a looser bar to score a TP than an FP, which
+// `bench/cve-replay/CONTRIBUTING.md` records as known imprecision to resolve
+// before the corpus grows toward 500. It is reproduced here rather than
+// quietly fixed: changing it would silently re-verdict entries across the
+// whole committed baseline, which is a corpus migration, not a refactor.
+//
+// The scanner emits into several arrays — `findings` (SAST), `secrets`,
+// `supplyChain` (SCA) and `logicVulns` (business-logic + behavioural) — and a
+// CVE can land in any of them, so all four are consulted.
+
+const CHANNELS = ['findings', 'secrets', 'supplyChain', 'logicVulns'];
+
+/** The regex an entry's manifest scores with. */
+export function matcherFor(manifest) {
+  return new RegExp(manifest?.expected?.vuln_match || manifest?.family || manifest?.cwe || '(?!)', 'i');
+}
+
+function _any(scan, predicate) {
+  for (const channel of CHANNELS) {
+    const arr = scan?.[channel];
+    if (Array.isArray(arr) && arr.some(predicate)) return true;
+  }
+  return false;
+}
+
+/** Did the vulnerable (`pre/`) tree produce a matching finding? */
+export function preHit(scan, manifest, matcher = matcherFor(manifest)) {
+  return _any(scan, f =>
+    (matcher.test(f.vuln || '') || matcher.test(f.family || '')) &&
+    (manifest?.cwe ? f.cwe === manifest.cwe || matcher.test(f.cwe || '') : true));
+}
+
+/** Did the fixed (`post/`) tree still produce a matching finding? */
+export function postHit(scan, manifest, matcher = matcherFor(manifest)) {
+  return _any(scan, f =>
+    matcher.test(f.vuln || '') &&
+    (manifest?.cwe ? f.cwe === manifest.cwe : true));
+}
+
+export const _internals = { CHANNELS };

package/src/posture/cross-lang-openapi.js

@@ -16,7 +16,7 @@ import { isChainWorthy, familyForBoundary } from './cross-lang-meta.js';
 // Out of scope (deferred to a follow-up): gRPC .proto introspection, GraphQL
 // resolver-to-resolver tracking, SQL/ORM round-trip, message queues.
 
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 
 function loadOpenAPI(fileContents) {
   for (const [fp, c] of Object.entries(fileContents || {})) {

package/src/posture/custom-rules.js

@@ -29,8 +29,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
-import fg from 'fast-glob';
+import * as yaml from '../util/yaml.js';
+import { globFiles } from '../util/glob.js';
 import { loadTrustedKeys, verifyRulePack } from './rule-pack-signing.js';
 
 const LANG_EXTS = {
@@ -337,7 +337,7 @@ export async function runRuleTests(scanRoot, fixtureGlob) {
     console.log(`No custom rules found in ${rulesDir(scanRoot)}`);
     return { ok: true, rules: 0, fired: 0 };
   }
-  const files = await fg(fixtureGlob, { dot: false, onlyFiles: true });
+  const files = await globFiles(fixtureGlob);
   console.log(`Loaded ${rules.length} rule(s); testing against ${files.length} file(s).\n`);
   let fired = 0;
   for (const fp of files) {