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

package/src/posture/falsification.js

@@ -16,6 +16,10 @@
 // the deterministic core runs fully offline.
 
 import { isValidSanitizerFor } from '../dataflow/sanitizer-proof.js';
+import {
+  recordProducer, assertSeparation, recordVerdict, consensusOf, producerIdOf,
+  VERIFIER_FALSIFICATION, VERIFIER_LLM_REVIEW,
+} from './verification-separation.js';
 
 const DEMOTE_FACTOR = 0.4;               // mirror proof-gate.js
 const TIERS = ['low', 'medium', 'high']; // confidence / exploitability tier order
@@ -76,6 +80,15 @@ export function classifyFinding(finding, fileContents) {
   return { verdict: 'survived', reasons: ['no context-matched control found between source and sink'] };
 }
 
+// Map a falsification-style verdict onto the verification vocabulary.
+// 'blocked'/'refuted' = the finding was disproved on this lens; 'survived' =
+// the attempt to disprove it failed, so the finding stands on this lens.
+function _verdictFor(v) {
+  if (v === 'blocked' || v === 'refuted' || v === 'false-positive') return 'refuted';
+  if (v === 'survived' || v === 'upheld' || v === 'true-positive') return 'upheld';
+  return 'undecided';
+}
+
 /**
  * Default-on annotator. Adds `finding.falsification = { verdict, reasons }` to
  * every taint-style finding; demotes + quarantines the ones falsified as blocked.
@@ -95,6 +108,23 @@ export function annotateFalsification(findings, fileContents, opts = {}) {
     catch { res = { verdict: 'unproven', reasons: ['classification error'] }; }
     f.falsification = { verdict: res.verdict, reasons: res.reasons };
 
+    // R7 — enforced separation. The detector produced this finding; the
+    // falsification pass is a *different* party, and records its verdict only
+    // after the separation check passes. Recall-preserving: a 'refuted'
+    // verdict is recorded, never acted on by deletion or severity change.
+    try {
+      recordProducer(f, producerIdOf(f));
+      if (assertSeparation(f, VERIFIER_FALSIFICATION).ok) {
+        recordVerdict(f, {
+          verifierId: VERIFIER_FALSIFICATION,
+          lens: 'control-flow',
+          verdict: _verdictFor(res.verdict),
+          reason: res.reasons && res.reasons[0],
+        });
+      }
+      f.verification.consensus = consensusOf(f);
+    } catch { /* verification bookkeeping is advisory; never break the scan */ }
+
     if (res.verdict === 'blocked') {
       f.quarantined = true;
       if (typeof f.confidence === 'number') {
@@ -113,7 +143,21 @@ export function annotateFalsification(findings, fileContents, opts = {}) {
     for (const f of survivors) {
       try {
         const llm = opts.llmReview(f);
-        if (llm) f.falsification.llm = llm;
+        if (llm) {
+          f.falsification.llm = llm;
+          // A second, independently-identified verifier arguing the opposing
+          // case — this is what makes a contested finding visible as contested
+          // rather than resolved by whoever spoke last.
+          if (assertSeparation(f, VERIFIER_LLM_REVIEW).ok) {
+            recordVerdict(f, {
+              verifierId: VERIFIER_LLM_REVIEW,
+              lens: 'llm-review',
+              verdict: _verdictFor(llm.verdict),
+              reason: llm.reason,
+            });
+            f.verification.consensus = consensusOf(f);
+          }
+        }
       } catch { /* the LLM tier is advisory; never let it break the scan */ }
     }
   }

package/src/posture/fix-verify.js

@@ -6,6 +6,10 @@
 //   1. The original finding's stableId no longer fires on the patched file.
 //   2. No new findings at severity ≥ medium were introduced by the patch.
 //   3. The project's existing linter (when present) passes on the patched file.
+//   4. The project's own test suite (when detectable) still passes. This is
+//      the R5 gap-closer: a patch that silently deletes the feature would
+//      satisfy (1) and (2) just as well as a real fix — only running the
+//      tests catches that. See `test-runner.js` for detection + execution.
 //
 // If any of those fail, the caller is expected to NOT apply the patch and
 // instead surface a "fix plan" — a numbered list of steps the engineer can
@@ -16,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { runFullScan } from '../engine.js';
 import { gateFixOutput } from './fix-honesty-gate.js';
+import { runProjectTests } from './test-runner.js';
 
 const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 
@@ -119,27 +124,75 @@ function runLinter(cwd, cmd, args) {
 // dishonest or over-claiming fix fails the gate. When `fixMeta` is absent
 // (the deterministic MCP write path, which has no claims to check) the honesty
 // gate is skipped and behavior is unchanged.
+// R5 (partial) — the test-suite stage. Runs the target project's own tests,
+// in the target project's own directory, against whatever is currently on
+// disk there. See `test-runner.js`'s header comment for why that run is
+// deliberately NOT routed through the R1 PoC-confinement sandbox: this is
+// the project's own already-trusted suite, not untrusted synthesized code.
+//
+// Caveat that matters for callers: `verifyPatch` above re-scans the
+// candidate patch purely in memory (no write to disk), but a test runner
+// needs real files — there is no cheap way to hand a runner an in-memory
+// overlay. So this leg reports on the CURRENT on-disk tree, not the
+// candidate `files` map, when `verifyFix` is used as a pre-write preview
+// (e.g. the `verify_fix` MCP tool). Callers that apply the patch first and
+// then re-verify get the strongest signal; that ordering is not enforced
+// here — it's the caller's responsibility, same as it already is for the
+// closed-loop `fix-verify-loop.js` path.
+// Does the caller's candidate patch differ from what is on disk right now?
+// If so, any test run necessarily exercised the pre-patch tree. Compared by
+// content so a patch that happens to match disk (already applied) is correctly
+// treated as NOT pre-patch.
+function _candidateDiffersFromDisk(scanRoot, files) {
+  if (!files || typeof files !== 'object') return false;
+  for (const [rel, content] of Object.entries(files)) {
+    if (typeof content !== 'string') continue;
+    try {
+      const abs = path.resolve(scanRoot, rel);
+      if (fs.readFileSync(abs, 'utf8') !== content) return true;
+    } catch {
+      return true; // candidate file absent on disk -> definitely not applied
+    }
+  }
+  return false;
+}
+
 export async function verifyFix({
   scanRoot,
   originalFindingStableId,
   files,
   depFileContents,
   fixMeta,
+  testTimeoutMs,
 } = {}) {
   const rescan = await verifyPatch({ scanRoot, originalFindingStableId, files, depFileContents });
   const lint = runProjectLinter(scanRoot, Object.keys(files || {}));
+  const tests = runProjectTests(scanRoot, testTimeoutMs != null ? { timeoutMs: testTimeoutMs } : {});
+  // True when a candidate patch was supplied but has not been written, so the
+  // suite necessarily ran against the pre-patch tree. Surfaced in the summary
+  // and on the result so a caller cannot mistake it for a verified patch.
+  const _testedPrePatch = !tests.skipped && _candidateDiffersFromDisk(scanRoot, files);
+  const testsOk = tests.skipped ? true : tests.passed === true;
   let honesty = null;
   if (fixMeta && typeof fixMeta === 'object') {
     try { honesty = gateFixOutput(fixMeta); } catch { honesty = null; }
   }
-  const ok = rescan.ok && (lint.ok || lint.skipped) && (honesty ? honesty.ok : true);
+  const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && (honesty ? honesty.ok : true);
   const summary = [
     `re-scan: ${rescan.ok ? 'PASS' : 'FAIL — ' + rescan.reason}`,
     `linter:  ${lint.runner === 'none' ? 'skipped (no linter config)'
               : lint.skipped ? `${lint.runner} not installed`
               : lint.ok ? `${lint.runner} PASS`
               : `${lint.runner} FAIL (exit ${lint.exitCode})`}`,
+    // Say which tree the suite actually ran against. `files` is a candidate
+    // patch held in memory; the runner needs real files, so it sees whatever is
+    // on disk. Reporting a bare "PASS" here would let a caller believe the
+    // PATCH passed the tests when the suite may have run on unpatched code.
+    `tests:   ${tests.skipped ? `skipped (${tests.reason})`
+              : tests.timedOut ? 'FAIL (timed out)'
+              : tests.passed ? `PASS${_testedPrePatch ? ' — on the CURRENT on-disk tree, NOT the candidate patch' : ''}`
+              : `FAIL (exit ${tests.exitCode})`}`,
     honesty ? `honesty: ${honesty.ok ? `PASS (${honesty.tier})` : 'FAIL — ' + honesty.violations.join('; ')}` : null,
   ].filter(Boolean).join('\n');
-  return { ok, rescan, lint, honesty, summary };
+  return { ok, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, summary };
 }

package/src/posture/license-policy.js

@@ -14,7 +14,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 DEFAULT_POLICY = {
   allow: [],

package/src/posture/profile.js

@@ -5,7 +5,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 { statePath, safeWriteState, resolveProjectRoot } from './state-dir.js';
 
 export const PROFILES = ['vibecoder', 'pro'];

package/src/posture/proof-tier.js

@@ -0,0 +1,33 @@
+// How strongly a finding is backed by evidence.
+//
+//   execution-proven — a proof-of-concept RAN inside the sandbox and produced
+//                      the predicted observable effect. The strongest claim.
+//   proof-failed     — a proof-of-concept ran and did NOT demonstrate the bug.
+//                      A triage signal, NOT an automatic false-positive verdict:
+//                      absence of proof is not proof of absence.
+//   taint-proven     — the analyser's static reasoning found it; nothing executed.
+//   unproven         — no analyser backing recorded.
+export const PROOF_TIERS = Object.freeze([
+  'execution-proven', 'proof-failed', 'taint-proven', 'unproven',
+]);
+
+// Parsers that represent real analysis rather than a plain pattern match.
+const _ANALYSED = new Set(['IR-TAINT', 'MULTI-SINK']);
+
+export function proofTierOf(finding) {
+  if (finding?.proofTier) return finding.proofTier;
+  return _ANALYSED.has(finding?.parser) ? 'taint-proven' : 'unproven';
+}
+
+export function attachProofTier(finding, evidence) {
+  if (!PROOF_TIERS.includes(evidence?.tier)) {
+    throw new Error(`unknown proof tier: ${evidence?.tier}`);
+  }
+  let tier = evidence.tier;
+  // Guard the central honesty rule: nothing that did not RUN may be called
+  // execution-proven or proof-failed. Fall back to the finding's static standing.
+  if (!evidence.ran && (tier === 'execution-proven' || tier === 'proof-failed')) {
+    tier = proofTierOf({ ...finding, proofTier: undefined });
+  }
+  return { ...finding, proofTier: tier, proofEvidence: { ...evidence, tier } };
+}

package/src/posture/relevance.js

@@ -0,0 +1,379 @@
+// R6 (threat-model-first scoping) + R9 (attack-surface-forward analysis).
+//
+// Every other precision mechanism in this engine kills a false positive by
+// PATTERN — a sanitizer on the path, a proof that didn't reproduce, a
+// confidence model fit to labelled families. This module kills one by
+// RELEVANCE: a finding sitting on a path an attacker can actually reach,
+// inside something the threat model says is worth attacking, matters more
+// than one that is neither. It is a different axis, and it composes with
+// (never replaces) the sink-driven taint engine.
+//
+//   R9 — start at the attack surface and reason FORWARD. `entrypoint-
+//        inventory.js` already enumerates every attacker-reachable entry
+//        point (HTTP/queue/cron/CLI/env/upload/webhook). Here that inventory
+//        stops being a report and starts being an input: we walk the module
+//        import graph out from every entry-point file and record which files
+//        are reachable from the attack surface at all.
+//   R6 — `threat-model.js` already derives assets, trust boundaries and a
+//        STRIDE classification. Here that model re-ranks: a finding on a
+//        modelled asset, or one classified into a modelled STRIDE bucket,
+//        outranks an identical finding that is in neither.
+//
+// ── Recall-preserving contract (non-negotiable) ────────────────────────────
+// Same precedent as `falsification.js` and `dataflow/proof-gate.js`:
+//   • Never removes a finding. The array in is the array out, same length,
+//     same order, same objects.
+//   • Never touches `severity`. Ever. Severity is the customer's triage
+//     contract; relevance is an ordinal re-rank underneath it.
+//   • Never asserts `unreachable` without POSITIVE evidence. "I could not
+//     determine it" is `entrypointReachable: null` / `relevanceTier:
+//     'unknown'` — a distinct state from "I determined it is not reachable".
+//     A negative verdict additionally requires the intra-repo import graph to
+//     be provably COMPLETE: one unresolved relative import anywhere means the
+//     graph has a hole an attacker's path could be hiding in, and every
+//     would-be `unreachable` degrades to `unknown`.
+//   • Demotion has a floor. An unreachable finding's exploitability is scaled,
+//     never zeroed — a wrong reachability call must cost rank, not visibility.
+//
+// Fields set on each finding:
+//   entrypointReachable : true | false | null   (null ≠ false)
+//   relevance           : number 0..1
+//   relevanceTier       : 'direct' | 'indirect' | 'unreachable' | 'unknown'
+//   relevanceFactors    : string[]  (human-readable, like exploitabilityFactors)
+
+// ── Tunables ───────────────────────────────────────────────────────────────
+const BASE_SCORE = {
+  direct: 0.75,
+  indirect: 0.50,
+  unreachable: 0.15,
+  unknown: 0.40,
+};
+// Cap so that no accumulation of R6 bonuses can push an evidenced-unreachable
+// finding into the same band as a reachable one.
+const UNREACHABLE_CAP = 0.30;
+
+// Exploitability re-rank multipliers (R6's "re-rank exploitability").
+const EXPLOIT_MULT = { direct: 1.15, indirect: 1.0, unreachable: 0.6, unknown: 1.0 };
+const EXPLOIT_FLOOR = 0.05;   // demotion never zeroes a finding out
+
+const IMPORT_EXTS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '/index.js', '/index.ts', '/index.mjs'];
+const MAX_FILES = 5000;       // graph-size guard: bail to 'unknown' beyond this
+
+// ── Source-level import extraction ─────────────────────────────────────────
+// Static, literal specifiers only. Anything non-literal is recorded as a hole.
+const RE_IMPORT_FROM = /\bimport\s[^;'"`]*?from\s*['"]([^'"]+)['"]/g;
+const RE_IMPORT_BARE = /\bimport\s*['"]([^'"]+)['"]/g;
+const RE_EXPORT_FROM = /\bexport\s[^;'"`]*?from\s*['"]([^'"]+)['"]/g;
+const RE_REQUIRE = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_DYN_IMPORT = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+const RE_PY_FROM = /^\s*from\s+([.\w]+)\s+import\s/gm;
+const RE_PY_IMPORT = /^\s*import\s+([.\w]+)/gm;
+const RE_JAVA_IMPORT = /^\s*import\s+(?:static\s+)?([\w.]+);/gm;
+// Non-literal module loads: the graph cannot see through these.
+const RE_DYNAMIC_HOLE = /\brequire\s*\(\s*[^'")\s]|\bimport\s*\(\s*[^'")\s]/;
+
+function _entries(fileContents) {
+  if (!fileContents) return [];
+  if (fileContents instanceof Map) {
+    return [...fileContents.entries()].filter(([k, v]) => typeof k === 'string' && typeof v === 'string');
+  }
+  if (typeof fileContents === 'object') {
+    return Object.entries(fileContents).filter(([k, v]) => typeof k === 'string' && typeof v === 'string');
+  }
+  return [];
+}
+
+function _norm(p) {
+  const parts = String(p).replace(/\\/g, '/').split('/');
+  const out = [];
+  for (const seg of parts) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') { out.pop(); continue; }
+    out.push(seg);
+  }
+  return out.join('/');
+}
+
+function _dirOf(file) {
+  const i = String(file).replace(/\\/g, '/').lastIndexOf('/');
+  return i < 0 ? '' : String(file).slice(0, i);
+}
+
+// Resolve one specifier to a key in `known`. Returns the key, or null.
+function _resolve(spec, fromFile, known, suffixIndex) {
+  if (!spec) return null;
+  const relative = spec.startsWith('.');
+  const base = relative ? _norm(`${_dirOf(fromFile)}/${spec}`) : null;
+
+  if (relative) {
+    for (const ext of IMPORT_EXTS) {
+      const cand = base + ext;
+      if (known.has(cand)) return cand;
+    }
+    // Also try the raw (already-extensioned) form as written.
+    if (known.has(base)) return base;
+    return null;
+  }
+
+  // Non-relative: python dotted module, java FQCN, or a bare package name.
+  const dotted = spec.replace(/\./g, '/');
+  for (const ext of ['.py', '.java', '.js', '.ts', '/__init__.py']) {
+    const hit = suffixIndex.get(dotted + ext);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Build the attack-surface reachability view.
+ *
+ * @returns {{
+ *   entryFiles: Set<string>, unauthEntryFiles: Set<string>,
+ *   reachableFiles: Set<string>, knownFiles: Set<string>,
+ *   graphComplete: boolean, holes: number,
+ * }}
+ */
+function buildReachabilityGraph(fileContents, opts = {}) {
+  const knownFiles = new Set();
+  const entryFiles = new Set();
+  const unauthEntryFiles = new Set();
+  const reachableFiles = new Set();
+  let graphComplete = false;
+  let holes = 0;
+
+  try {
+    const files = _entries(fileContents);
+    if (files.length === 0 || files.length > MAX_FILES) {
+      return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete: false, holes: 1 };
+    }
+    for (const [k] of files) knownFiles.add(k);
+
+    // Index by path suffix so a python/java module name can find its file.
+    const suffixIndex = new Map();
+    for (const k of knownFiles) {
+      const norm = k.replace(/\\/g, '/');
+      const segs = norm.split('/');
+      for (let i = 0; i < segs.length; i++) {
+        const suf = segs.slice(i).join('/');
+        if (!suffixIndex.has(suf)) suffixIndex.set(suf, k);
+      }
+    }
+
+    // 1) Entry-point files, from the inventory and/or the raw route list.
+    const inv = opts.entrypointInventory;
+    const invEntries = inv && Array.isArray(inv.entrypoints) ? inv.entrypoints
+      : Array.isArray(opts.entrypoints) ? opts.entrypoints : [];
+    for (const e of invEntries) {
+      if (!e || typeof e.file !== 'string' || !e.file) continue;
+      entryFiles.add(e.file);
+      if (e.trust !== 'authenticated') unauthEntryFiles.add(e.file);
+    }
+    for (const r of (Array.isArray(opts.routes) ? opts.routes : [])) {
+      if (!r || typeof r.file !== 'string' || !r.file) continue;
+      entryFiles.add(r.file);
+      if (r.hasAuth !== true) unauthEntryFiles.add(r.file);
+    }
+
+    // 2) Import edges. A hole is an edge the graph cannot see: an unresolved
+    //    intra-repo (relative) specifier, or a non-literal module load. Holes
+    //    are recorded PER FILE because only holes in files that turn out to be
+    //    REACHABLE can hide a path into somewhere we'd otherwise call
+    //    unreachable — a hidden edge always originates in the importing file,
+    //    so a hole inside an already-unreachable file cannot make anything
+    //    reachable. Anything else would make a negative verdict impossible in
+    //    any real repository (one `require(varName)` anywhere would veto all).
+    const edges = new Map();
+    const holeFiles = new Set();
+    for (const [file, src] of files) {
+      const out = new Set();
+      if (RE_DYNAMIC_HOLE.test(src)) { holes++; holeFiles.add(file); }
+      for (const re of [RE_IMPORT_FROM, RE_EXPORT_FROM, RE_IMPORT_BARE, RE_REQUIRE, RE_DYN_IMPORT,
+        RE_PY_FROM, RE_PY_IMPORT, RE_JAVA_IMPORT]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(src))) {
+          const spec = m[1];
+          if (!spec) continue;
+          const target = _resolve(spec, file, knownFiles, suffixIndex);
+          if (target && target !== file) out.add(target);
+          // Only an unresolved INTRA-repo (relative) specifier is a hole:
+          // a bare package name points at a third-party module that was
+          // never part of `fileContents` in the first place.
+          else if (!target && spec.startsWith('.')) { holes++; holeFiles.add(file); }
+        }
+      }
+      edges.set(file, out);
+    }
+
+    // 3) Forward BFS from the attack surface.
+    const queue = [...entryFiles].filter(f => knownFiles.has(f));
+    for (const f of queue) reachableFiles.add(f);
+    while (queue.length) {
+      const cur = queue.shift();
+      for (const next of (edges.get(cur) || [])) {
+        if (reachableFiles.has(next)) continue;
+        reachableFiles.add(next);
+        queue.push(next);
+      }
+    }
+
+    // A negative verdict is admissible only when we actually found an attack
+    // surface AND no file reachable from it has an invisible edge.
+    let reachableHole = false;
+    for (const f of reachableFiles) if (holeFiles.has(f)) { reachableHole = true; break; }
+    graphComplete = !reachableHole && entryFiles.size > 0;
+  } catch (_) {
+    return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete: false, holes: holes || 1 };
+  }
+  return { entryFiles, unauthEntryFiles, reachableFiles, knownFiles, graphComplete, holes };
+}
+
+// ── R6: threat-model bonuses ───────────────────────────────────────────────
+function _threatBonus(f, threatModel, factors) {
+  let bonus = 0;
+  if (!threatModel || typeof threatModel !== 'object') return bonus;
+
+  const assets = Array.isArray(threatModel.assets) ? threatModel.assets : [];
+  for (const a of assets) {
+    if (!a || a.file !== f.file) continue;
+    const exposed = a.exposure === 'public-api' || a.exposure === 'external-api';
+    bonus += exposed ? 0.10 : 0.07;
+    factors.push(`modelled asset in file: ${a.category || a.name || 'asset'}${exposed ? ` (${a.exposure})` : ''}`);
+    break;
+  }
+
+  const boundaries = Array.isArray(threatModel.trustBoundaries) ? threatModel.trustBoundaries : [];
+  if (boundaries.some(b => b && b.file === f.file)) {
+    bonus += 0.05;
+    factors.push('trust boundary crossed in this file');
+  }
+
+  const stride = threatModel.stride && typeof threatModel.stride === 'object' ? threatModel.stride : null;
+  if (stride) {
+    for (const [cat, items] of Object.entries(stride)) {
+      if (!Array.isArray(items)) continue;
+      if (items.some(it => it && it.file === f.file && (it.line === f.line || it.vuln === f.vuln))) {
+        bonus += 0.08;
+        factors.push(`modelled STRIDE threat: ${cat}`);
+        break;
+      }
+    }
+  }
+  return bonus;
+}
+
+/**
+ * Pure scorer. Does NOT mutate the finding.
+ *
+ * @param graph  the object returned by buildReachabilityGraph (or a subset
+ *               with entryFiles / reachableFiles / knownFiles / graphComplete).
+ * @returns {{ tier, score, reachable, factors }}
+ */
+function scoreRelevance(f, graph, threatModel) {
+  const factors = [];
+  const g = graph || {};
+  const entryFiles = g.entryFiles instanceof Set ? g.entryFiles : new Set();
+  const reachableFiles = g.reachableFiles instanceof Set ? g.reachableFiles : new Set();
+  const knownFiles = g.knownFiles instanceof Set ? g.knownFiles : new Set();
+  const unauthEntryFiles = g.unauthEntryFiles instanceof Set ? g.unauthEntryFiles : new Set();
+  const file = f && typeof f.file === 'string' ? f.file : null;
+
+  let tier;
+  let reachable;
+  if (!file || entryFiles.size === 0) {
+    tier = 'unknown';
+    reachable = null;
+    factors.push(entryFiles.size === 0
+      ? 'no attack surface enumerated — reachability not determinable'
+      : 'finding has no file — reachability not determinable');
+  } else if (entryFiles.has(file)) {
+    tier = 'direct';
+    reachable = true;
+    factors.push('finding sits in an entry-point file (direct attack surface)');
+    if (unauthEntryFiles.has(file)) factors.push('entry point is unauthenticated');
+  } else if (reachableFiles.has(file)) {
+    tier = 'indirect';
+    reachable = true;
+    factors.push('reachable from an entry point via the module import graph');
+  } else if (g.graphComplete === true && knownFiles.has(file)) {
+    tier = 'unreachable';
+    reachable = false;
+    factors.push('no import path from any enumerated entry point (import graph complete)');
+  } else {
+    tier = 'unknown';
+    reachable = null;
+    factors.push(knownFiles.has(file)
+      ? 'import graph incomplete — no reachability verdict admissible'
+      : 'file not present in the scanned set — reachability not determinable');
+  }
+
+  let score = BASE_SCORE[tier];
+  score += _threatBonus(f || {}, threatModel, factors);
+  if (tier === 'direct' && unauthEntryFiles.has(file)) score += 0.10;
+  if (tier === 'unreachable') score = Math.min(score, UNREACHABLE_CAP);
+  score = Math.max(0, Math.min(1, score));
+
+  return { tier, score: Math.round(score * 1000) / 1000, reachable, factors };
+}
+
+/**
+ * Default-on annotator. Recall-preserving: never removes a finding, never
+ * touches severity, never asserts 'unreachable' without positive evidence.
+ *
+ * @param ctx.fileContents          Map|object of scanned sources
+ * @param ctx.entrypointInventory   output of buildEntrypointInventory()
+ * @param ctx.routes                route list (fallback attack surface)
+ * @param ctx.threatModel           output of buildThreatModel()
+ */
+export function annotateRelevance(findings, ctx = {}) {
+  if (!Array.isArray(findings)) return findings;
+  let graph;
+  try {
+    const c = ctx && typeof ctx === 'object' ? ctx : {};
+    graph = buildReachabilityGraph(c.fileContents, {
+      entrypointInventory: c.entrypointInventory,
+      entrypoints: c.entrypoints,
+      routes: c.routes,
+    });
+  } catch (_) {
+    graph = { entryFiles: new Set(), unauthEntryFiles: new Set(), reachableFiles: new Set(), knownFiles: new Set(), graphComplete: false, holes: 1 };
+  }
+  const threatModel = ctx && typeof ctx === 'object' ? ctx.threatModel : null;
+
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    try {
+      const r = scoreRelevance(f, graph, threatModel);
+      f.entrypointReachable = r.reachable;
+      f.relevance = r.score;
+      f.relevanceTier = r.tier;
+      f.relevanceFactors = r.factors;
+
+      // R6 re-rank: exploitability is an ordinal priority, so scaling it by
+      // relevance is exactly the intended re-ranking. Severity is untouched,
+      // and demotion has a floor — a wrong call costs rank, not visibility.
+      const mult = EXPLOIT_MULT[r.tier];
+      if (typeof f.exploitability === 'number' && Number.isFinite(f.exploitability) && mult !== 1) {
+        const adjusted = Math.max(EXPLOIT_FLOOR, Math.min(1, f.exploitability * mult));
+        f.exploitability = Math.round(adjusted * 100) / 100;
+        if (typeof f.priorityScore === 'number') f.priorityScore = f.exploitability;
+        if (Array.isArray(f.exploitabilityFactors)) f.exploitabilityFactors.push(`relevance:${r.tier}`);
+        // Keep the tier label consistent with the re-ranked score. Same
+        // thresholds as annotateExploitability; severity is NOT derived here.
+        if (f.exploitability >= 0.80) f.exploitabilityTier = 'critical';
+        else if (f.exploitability >= 0.60) f.exploitabilityTier = 'high';
+        else if (f.exploitability >= 0.35) f.exploitabilityTier = 'medium';
+        else f.exploitabilityTier = 'low';
+      }
+    } catch (_) {
+      f.entrypointReachable = null;
+      f.relevance = BASE_SCORE.unknown;
+      f.relevanceTier = 'unknown';
+      f.relevanceFactors = ['relevance scoring failed — no verdict'];
+    }
+  }
+  return findings;
+}
+
+// Test-only surface (underscore-prefixed: not part of the public API).
+export const _internals = { buildReachabilityGraph, scoreRelevance, BASE_SCORE, EXPLOIT_MULT };

package/src/posture/rule-overrides.js

@@ -9,7 +9,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 { verifyLastScan } from './integrity.js';
 import { statePath } from './state-dir.js';
 

package/src/posture/sca-policy.js

@@ -38,7 +38,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 DEFAULT_POLICY = {
   acceptRisk: [],