@clear-capabilities/agentic-security-scanner 0.127.0 → 0.130.0

package/src/posture/accuracy-scorecard.js

@@ -0,0 +1,317 @@
+// Accuracy scorecard (roadmap R3) — aggregation + rendering.
+//
+// WHY THIS LIVES IN src/posture/ RATHER THAN ENTIRELY IN scripts/:
+// every figure this project publishes has to be re-derivable and testable.
+// The aggregation and the rendering are pure functions of their inputs, so
+// they belong where the unit-test suite already runs (tests execute against
+// `src/` directly). The thin driver at `scripts/scorecard.mjs` does the
+// impure half — running the corpus, running the self-scan, reading the
+// bundle hash and the git commit — and hands the results here. That split is
+// what makes the "hand-computed fixture" test in
+// `test/accuracy-scorecard.test.js` possible at all.
+//
+// INTEGRITY CONTRACT (the reason the item exists — read before editing):
+//   · Nothing here invents a rate. Every rate is carried as {n, d} and
+//     rendered through formatRate(), which always prints the numerator and
+//     the denominator alongside the percentage. A denominator of 0 renders
+//     "0/0 (n/a)" — never 0% and never 100%.
+//   · Entries the run could not score (parser unavailable, scan error) are
+//     removed from every denominator AND disclosed by name. Scoring them
+//     either way would manufacture a number out of an environment fault.
+//   · No F1 is emitted. F1 needs a precision measured over a labelled
+//     real-world population; this corpus is curated known-vulnerable
+//     fixtures and their fixed counterparts, so its "precision" would be
+//     computed over a denominator that does not mean what the word implies.
+//     See renderScorecardMarkdown()'s methodology section.
+//   · Output is a deterministic function of the inputs apart from one
+//     timestamp line (TIMESTAMP_MARKER), so the document regenerates
+//     byte-identically on an unchanged tree.
+
+// The single line of the rendered document that is permitted to vary between
+// two runs on an unchanged tree. Tests and the regeneration check key on it.
+export const TIMESTAMP_MARKER = 'Generated (UTC)';
+
+/**
+ * Render a rate with its raw counts. This is the ONLY sanctioned way to put a
+ * percentage into the scorecard: a bare percentage with no visible
+ * denominator is exactly the kind of unfalsifiable claim this document exists
+ * to avoid.
+ */
+export function formatRate(n, d) {
+  if (!d) return `${n}/${d} (n/a)`;
+  return `${n}/${d} (${((n / d) * 100).toFixed(1)}%)`;
+}
+
+function emptyBucket(key) {
+  return { key, entries: 0, detection: { n: 0, d: 0 }, silence: { n: 0, d: 0 } };
+}
+
+function accumulate(bucket, status) {
+  bucket.entries++;
+  if (status.includes('pre:TP')) { bucket.detection.n++; bucket.detection.d++; }
+  else if (status.includes('pre:FN')) { bucket.detection.d++; }
+  if (status.includes('post:TN')) { bucket.silence.n++; bucket.silence.d++; }
+  else if (status.includes('post:FP')) { bucket.silence.d++; }
+}
+
+function sliceBy(scored, key) {
+  const map = new Map();
+  for (const d of scored) {
+    const k = d[key] || 'unknown';
+    if (!map.has(k)) map.set(k, emptyBucket(k));
+    accumulate(map.get(k), d.status);
+  }
+  // Sorted by key so the document is stable across runs.
+  return [...map.values()].sort((a, b) => a.key.localeCompare(b.key));
+}
+
+/**
+ * Aggregate the per-entry detail records emitted by the corpus runner.
+ *
+ * Input records: { cve, tier, cwe, language, status, error? } where status is
+ * the runner's own string form, e.g. "pre:TP post:TN", "pre:FN", "env-error".
+ */
+export function aggregateCorpus(detail) {
+  const all = [...(detail || [])];
+  const notScored = all
+    .filter(d => !d.status || !d.status.startsWith('pre:'))
+    .map(d => ({ cve: d.cve, tier: d.tier || null, language: d.language || null, status: d.status || 'unknown', error: d.error || null }))
+    .sort((a, b) => String(a.cve).localeCompare(String(b.cve)));
+  const scored = all.filter(d => d.status && d.status.startsWith('pre:'));
+
+  const overall = emptyBucket('overall');
+  for (const d of scored) accumulate(overall, d.status);
+
+  return {
+    totalEntries: all.length,
+    scoredEntries: scored.length,
+    notScored,
+    overall: { detection: overall.detection, silence: overall.silence },
+    byLanguage: sliceBy(scored, 'language'),
+    byCwe: sliceBy(scored, 'cwe'),
+    byTier: sliceBy(scored, 'tier'),
+  };
+}
+
+/**
+ * Build the machine-readable scorecard model. `inputs`:
+ *   provenance   { engineVersion, bundleSha256, commit, nodeVersion, generatedAt }
+ *   corpusDetail per-entry records from a corpus run performed THIS run
+ *   selfScan     { targets: {name:{total,byFile}}, polyglot: {total,byLanguage} }
+ *                — measured THIS run
+ *   committed    { corpusBaseline, proofCorpus } — read from committed files,
+ *                labelled as such in the output, never used to derive a rate
+ */
+export function buildScorecard(inputs) {
+  const corpus = aggregateCorpus(inputs.corpusDetail);
+  const selfScan = inputs.selfScan || {};
+  const targets = {};
+  for (const k of Object.keys(selfScan.targets || {}).sort()) {
+    targets[k] = { total: selfScan.targets[k].total, byFile: selfScan.targets[k].byFile || {} };
+  }
+  const committed = inputs.committed || {};
+  const proof = committed.proofCorpus || null;
+  return {
+    schema: 'agentic-security/accuracy-scorecard@1',
+    provenance: { ...inputs.provenance },
+    methodology: {
+      population: 'curated known-vulnerable fixtures (pre/) and their fixed counterparts (post/)',
+      detectionRateMeans: 'share of known-vulnerable fixtures where the expected finding fired',
+      silenceRateMeans: 'share of fixed counterparts where the same finding correctly did not fire',
+      notGeneralRecall: true,
+      notGeneralFalsePositiveRate: true,
+      f1Emitted: false,
+      f1OmissionReason: 'no labelled real-world population is available to measure precision over, so any F1 would combine denominators that do not describe the same population',
+    },
+    corpus: {
+      measuredThisRun: true,
+      totalEntries: corpus.totalEntries,
+      scoredEntries: corpus.scoredEntries,
+      notScored: corpus.notScored,
+      overall: corpus.overall,
+      byLanguage: corpus.byLanguage,
+      byCwe: corpus.byCwe,
+      byTier: corpus.byTier,
+    },
+    selfScan: { measuredThisRun: true, targets, polyglot: selfScan.polyglot || { total: 0, byLanguage: {} } },
+    committedInputs: {
+      corpusBaseline: committed.corpusBaseline
+        ? { source: 'bench/cve-replay/corpus-baseline.json', generatedAt: committed.corpusBaseline.generatedAt, total: committed.corpusBaseline.total, passing: committed.corpusBaseline.passing }
+        : null,
+      proofCorpus: proof
+        ? {
+          source: 'bench/proof-corpus/results/summary.json',
+          bundleSha: proof.bundleSha || null,
+          targetCount: proof.targetCount ?? null,
+          ok: proof.ok ?? null,
+          failed: proof.failed ?? null,
+          targets: (proof.targets || []).map(t => ({
+            id: t.id, commit: t.commit, status: t.status,
+            filesInScope: t.coverage?.totals?.inScope ?? null,
+            filesParsed: t.coverage?.totals?.parsed ?? null,
+            determinismChecked: t.determinism?.checked ?? null,
+            determinismIdentical: t.determinism?.identical ?? null,
+            resultsEmitted: t.determinism?.results ?? null,
+          })).sort((a, b) => String(a.id).localeCompare(String(b.id))),
+        }
+        : null,
+    },
+  };
+}
+
+function rateRow(r) {
+  return `| ${r.key} | ${r.entries} | ${formatRate(r.detection.n, r.detection.d)} | ${formatRate(r.silence.n, r.silence.d)} |`;
+}
+
+/** Render the human-readable scorecard. Deterministic apart from one line. */
+export function renderScorecardMarkdown(m) {
+  const p = m.provenance || {};
+  const c = m.corpus;
+  const L = [];
+  L.push('# Accuracy scorecard');
+  L.push('');
+  L.push('Generated by `npm run scorecard`. Every figure below comes from a run');
+  L.push('performed by that command, except where a line is explicitly labelled');
+  L.push('*committed artifact* — those carry the timestamp and commit of the run');
+  L.push('that produced them.');
+  L.push('');
+  L.push('## Provenance');
+  L.push('');
+  L.push('| Field | Value |');
+  L.push('| --- | --- |');
+  L.push(`| Engine version | ${p.engineVersion || 'unknown'} |`);
+  L.push(`| Bundle SHA-256 | \`${p.bundleSha256 || 'unknown'}\` |`);
+  L.push(`| Commit | \`${p.commit || 'unknown'}\` |`);
+  if (p.worktreeClean !== undefined) {
+    L.push(`| Worktree at measurement time | ${p.worktreeClean ? 'clean' : 'DIRTY — the commit above does not fully describe what was measured'} |`);
+  }
+  L.push(`| Node | ${p.nodeVersion || 'unknown'} |`);
+  L.push(`| Corpus entries | ${c.totalEntries} (${c.scoredEntries} scored) |`);
+  L.push(`| ${TIMESTAMP_MARKER} | ${p.generatedAt || 'unknown'} |`);
+  L.push('');
+  L.push('## What these numbers are, and what they are not');
+  L.push('');
+  L.push('The population is a curated corpus of known-vulnerable code fixtures');
+  L.push('(`pre/`) each paired with its fixed counterpart (`post/`). Two rates are');
+  L.push('reported, always with their raw numerator and denominator:');
+  L.push('');
+  L.push('- **Detection rate** — of the vulnerable fixtures, the share where the');
+  L.push('  expected finding fired. This is **not** general-purpose recall against');
+  L.push('  real-world code: the corpus is curated, each entry was added because it');
+  L.push('  represents a class worth covering, and nothing here samples the');
+  L.push('  distribution of vulnerabilities in arbitrary repositories.');
+  L.push('- **Correct-silence rate** — of the fixed counterparts, the share where');
+  L.push('  the same finding correctly did not fire. This is **not** a general');
+  L.push('  false-positive rate: the denominator is one narrowly-scoped fixed file');
+  L.push('  per entry, not a population of real code in which any rule could');
+  L.push('  misfire.');
+  L.push('');
+  L.push('The corpus is also **gated**: an entry is admitted only once it scores');
+  L.push('detected-on-`pre` and silent-on-`post`, and a committed baseline fails the');
+  L.push('build on any drift. A detection rate at the ceiling is therefore expected');
+  L.push('by construction — it is evidence that nothing regressed, not evidence that');
+  L.push('there is no headroom. What moves it is adding entries for classes not yet');
+  L.push('covered, which is why the corpus size is reported alongside the rate.');
+  L.push('');
+  L.push('**No F1 is reported, deliberately.** An F1 requires a precision measured');
+  L.push('over a labelled real-world population. This project does not have one, so');
+  L.push('a precision computed from the corpus alone would divide by a denominator');
+  L.push('that does not describe the population the word implies. The precision-side');
+  L.push('signal reported instead is the self-scan section below: exact finding');
+  L.push('counts on this repository\'s own non-fixture source, where every count is');
+  L.push('reviewed by hand and any movement is a real change. Publishing a number we');
+  L.push('cannot defend would cost more credibility than the number is worth.');
+  L.push('');
+  L.push('## Corpus results (measured this run)');
+  L.push('');
+  L.push('| Population | Detected / correctly silent |');
+  L.push('| --- | --- |');
+  L.push(`| Vulnerable fixtures (\`pre/\`) — detection | ${formatRate(c.overall.detection.n, c.overall.detection.d)} |`);
+  L.push(`| Fixed counterparts (\`post/\`) — correct silence | ${formatRate(c.overall.silence.n, c.overall.silence.d)} |`);
+  L.push('');
+  if (c.notScored.length) {
+    const word = c.notScored.length === 1 ? 'entry' : 'entries';
+    L.push('**' + c.notScored.length + ' corpus ' + word + ' could not be scored.** Excluded from every');
+    L.push('denominator above rather than counted as a miss:');
+    L.push('');
+    for (const n of c.notScored) {
+      const why = n.error ? ' — ' + n.error : '';
+      L.push('- `' + n.cve + '` (' + (n.language || 'unknown') + '): ' + n.status + why);
+    }
+    L.push('');
+  } else {
+    L.push('All corpus entries scored; no entry was excluded.');
+    L.push('');
+  }
+  L.push('### By language');
+  L.push('');
+  L.push('| Language | Entries | Detection (`pre/`) | Correct silence (`post/`) |');
+  L.push('| --- | --- | --- | --- |');
+  for (const r of c.byLanguage) L.push(rateRow(r));
+  L.push('');
+  L.push('### By CWE');
+  L.push('');
+  L.push('| CWE | Entries | Detection (`pre/`) | Correct silence (`post/`) |');
+  L.push('| --- | --- | --- | --- |');
+  for (const r of c.byCwe) L.push(rateRow(r));
+  L.push('');
+  L.push('### By corpus tier');
+  L.push('');
+  L.push('| Tier | Entries | Detection (`pre/`) | Correct silence (`post/`) |');
+  L.push('| --- | --- | --- | --- |');
+  for (const r of c.byTier) L.push(rateRow(r));
+  L.push('');
+  L.push('## Precision-side signal: self-scan (measured this run)');
+  L.push('');
+  L.push('The engine scanned this repository\'s own hand-reviewed source. These are');
+  L.push('absolute finding counts, not a rate — there is no labelled ground truth');
+  L.push('over this code, so no precision figure is derived from it. What it');
+  L.push('supports is a movement claim: any change in these counts between');
+  L.push('releases is a real change in what the engine reports on unchanged code.');
+  L.push('');
+  L.push('| Target | Findings |');
+  L.push('| --- | --- |');
+  for (const [k, v] of Object.entries(m.selfScan.targets)) L.push(`| \`${k}\` | ${v.total} |`);
+  L.push(`| \`polyglot\` fixture (expected 0) | ${m.selfScan.polyglot.total} |`);
+  L.push('');
+  L.push('Per-file counts are in `docs/scorecard.json`.');
+  L.push('');
+  L.push('## Committed artifacts referenced (not re-run by this command)');
+  L.push('');
+  const cb = m.committedInputs.corpusBaseline;
+  if (cb) {
+    L.push(`- **Corpus baseline** (*committed artifact*, \`${cb.source}\`, generated ${cb.generatedAt}):`);
+    L.push(`  ${cb.passing}/${cb.total} entries recorded as passing. The gate`);
+    L.push('  `npm run bench:cve-replay:check` fails the build on any drift from it.');
+    L.push('  The rates above are computed from this run, not from this file.');
+  }
+  const pc = m.committedInputs.proofCorpus;
+  if (pc) {
+    L.push(`- **Third-party repository run** (*committed artifact*, \`${pc.source}\`,`);
+    L.push(`  bundle \`${pc.bundleSha}\`): ${pc.ok}/${pc.targetCount} targets completed.`);
+    L.push('  Reported for scale and parse coverage only — these repositories have no');
+    L.push('  vulnerability ground truth, so no accuracy rate is derived from them.');
+    L.push('');
+    L.push('| Repository | Commit | Status | Files parsed / in scope | Results emitted | Deterministic re-run |');
+    L.push('| --- | --- | --- | --- | --- | --- |');
+    for (const t of pc.targets) {
+      const det = t.determinismChecked ? (t.determinismIdentical ? 'identical' : 'checked, not byte-identical') : 'not checked';
+      L.push(`| ${t.id} | \`${String(t.commit || '').slice(0, 12)}\` | ${t.status} | ${formatRate(t.filesParsed ?? 0, t.filesInScope ?? 0)} | ${t.resultsEmitted ?? 'n/a'} | ${det} |`);
+    }
+  }
+  L.push('');
+  L.push('## Reproducing any figure here');
+  L.push('');
+  L.push('| Figure | Command |');
+  L.push('| --- | --- |');
+  L.push('| Detection / correct-silence, and every slice | `node bench/cve-replay/runner.mjs --json` |');
+  L.push('| Corpus drift gate | `npm run bench:cve-replay:check` |');
+  L.push('| Self-scan counts | `node bench/self-scan/measure.mjs --json` |');
+  L.push('| Self-scan drift gate | `npm run bench:self-scan:check` |');
+  L.push('| This whole document | `npm run scorecard` |');
+  L.push('');
+  L.push('Running `npm run scorecard` twice on an unchanged tree produces an');
+  L.push('identical document apart from the generated-timestamp row above.');
+  L.push('');
+  return L.join('\n');
+}

package/src/posture/api-contract.js

@@ -19,7 +19,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 CONTRACT_FILE_PATTERNS = [
   { glob: /(?:openapi|swagger)\.(?:ya?ml|json)$/i, kind: 'openapi' },

package/src/posture/attestation.js

@@ -0,0 +1,199 @@
+// 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: no run on a second machine, OS, or Node ' +
+  'version is compared here, and some detectors are environment-sensitive. 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/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,7 +29,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';
 import fg from 'fast-glob';
 import { loadTrustedKeys, verifyRulePack } from './rule-pack-signing.js';