@clear-capabilities/agentic-security-scanner 0.136.2 → 0.136.9

package/src/posture/evidence-bundle.js

@@ -104,12 +104,25 @@ export function ensureKeyPair(dir = keyDir()) {
     return { privateKeyPem, publicKeyPem, created: true, ...p };
   } catch (e) {
     if (e.code !== 'EEXIST') throw e;
-    return {
-      privateKeyPem: fs.readFileSync(p.privateKey, 'utf8'),
-      publicKeyPem: fs.readFileSync(p.publicKey, 'utf8'),
-      created: false,
-      ...p,
-    };
+    // We lost the race on the private key — someone else's 'wx' won.
+    // Their public-key write follows immediately after their private-key
+    // write but is not itself atomic with it, so it may not have landed
+    // yet: a bare read here would throw an uncaught ENOENT on a genuinely
+    // transient state, not a real error. Retry briefly rather than crash.
+    const sleepBuf = new Int32Array(new SharedArrayBuffer(4));
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return {
+          privateKeyPem: fs.readFileSync(p.privateKey, 'utf8'),
+          publicKeyPem: fs.readFileSync(p.publicKey, 'utf8'),
+          created: false,
+          ...p,
+        };
+      } catch (readErr) {
+        if (readErr.code !== 'ENOENT' || attempt >= 50) throw readErr;
+        Atomics.wait(sleepBuf, 0, 0, 10); // 10ms; ~500ms total budget
+      }
+    }
   }
 }
 
@@ -227,9 +240,26 @@ export function signEvidenceBundle(bundle, privateKeyPem) {
  * Returns {ok, reason}. Never throws — a malformed bundle from an untrusted
  * source is an expected input, not an exceptional one.
  */
+// The complete set of top-level keys a legitimately-built, signed bundle can
+// carry — buildEvidenceBundle's six plus signEvidenceBundle's `signature`.
+// EA-03 (Stage-0 audit, 2026): canonicalBytes SIGNS an allowlist of fields;
+// verifyEvidenceBundle never checked for keys OUTSIDE that allowlist, so a
+// bundle with a fabricated `verdict`/`proofLevel`/anything-else stapled on
+// after signing verified as authentic — the signature simply never covered
+// those bytes. Rejecting unknown keys here closes that; it must exactly match
+// what buildEvidenceBundle+signEvidenceBundle actually produce, or a
+// legitimate bundle would start failing verification.
+const BUNDLE_TOP_LEVEL_KEYS = new Set([
+  'schema', 'finding', 'evidence', 'engine', 'proves', 'doesNotProve', 'signature',
+]);
+
 export function verifyEvidenceBundle(bundle, publicKeyPem) {
   if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
   if (bundle.schema !== BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  const unknownKeys = Object.keys(bundle).filter(k => !BUNDLE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
   const sig = bundle.signature;
   if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
   if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };

package/src/posture/exploitability-probability.js

@@ -189,9 +189,21 @@ export function annotateExploitProbability(findings, ctx = {}) {
     p = _clamp01(p);
     // Wilson CI: prefer historical CI when we have one, otherwise derive
     // a wider CI from the prior (n=10 implied sample at base rate).
+    //
+    // The point estimate (exploitProbability) is ALWAYS the per-finding,
+    // factor-adjusted `p` computed above — never the population-level
+    // historical hit rate. This module's own header scopes historical data
+    // explicitly to the CI ("Wilson CI computed from operator's historical
+    // hit rate... when enough samples exist"); overwriting the point
+    // estimate too collapsed every finding in a CWE×language slice with
+    // enough history to the SAME number regardless of its own reachability/
+    // sanitizer/auth signals — a maximally-dangerous finding and a
+    // maximally-safe one scored identically, while exploitProbabilityWhy
+    // kept listing factors that, in that branch, had zero effect on the
+    // reported number.
     const hist = _historicalCi(history, cwe, f.language || (f.file || '').split('.').pop());
     if (hist) {
-      f.exploitProbability = hist.p;
+      f.exploitProbability = p;
       f.exploitProbabilityCI95 = hist.ci;
       f.exploitProbabilitySlice = hist.slice;
       f.exploitProbabilityN = hist.n;

package/src/posture/falsification.js

@@ -22,7 +22,19 @@ import {
 } from './verification-separation.js';
 
 const DEMOTE_FACTOR = 0.4;               // mirror proof-gate.js
-const TIERS = ['low', 'medium', 'high']; // confidence / exploitability tier order
+// Stage 3 correctness audit (detection depth): this ladder was missing
+// 'critical' — exploitability.js sets f.exploitabilityTier = 'critical' at
+// score >= 0.80 (the tier falsification most needs to demote, since it's
+// exactly the findings a false "survives" verdict would most overstate).
+// _dropTier('critical') hit the `i <= 0` "unknown tier, leave unchanged"
+// branch (indexOf returns -1 for an unrecognized value), so a falsified
+// finding at the critical exploitability tier kept its full tier — the
+// demotion silently no-op'd for the highest tier in the system. 'very-low'
+// (confidence.js's own floor tier) is included too, for the same reason
+// confidenceTier is demoted by this same function — it was already
+// unchanged-at-floor by the same `i <= 0` fallback, so this is a
+// completeness fix there, not a behavior change.
+const TIERS = ['very-low', 'low', 'medium', 'high', 'critical']; // confidence / exploitability tier order
 
 function _dropTier(tier) {
   const i = TIERS.indexOf(tier);
@@ -66,7 +78,16 @@ export function classifyFinding(finding, fileContents) {
   }
   // A sanitizer that doesn't match the sink context does NOT block the flow —
   // the finding survives (this is a real bug, not a mitigation).
-  if (finding.sanitizerMismatch === true) {
+  //
+  // Stage 3 correctness audit (detection depth): this was `=== true`, but
+  // the field's real producer (engine.js's applySanitizerEffectiveness)
+  // sets `f.sanitizerMismatch = f.sanitizerType` — a STRING sanitizer-type
+  // label ("Type Guard", "JWT Algo Pinning", ...), never the literal
+  // boolean `true`. Every OTHER consumer of this field (confidence.js,
+  // exploitability.js, engine.js's own scoring) checks it via plain
+  // truthiness; this strict-equality check could never match a real
+  // finding, making the whole branch dead code.
+  if (finding.sanitizerMismatch) {
     return { verdict: 'survived', reasons: ['wrong-context sanitizer does not neutralize this sink'] };
   }
   const window = _pathWindow(finding, fileContents);

package/src/posture/fix-metrics.js

@@ -62,7 +62,7 @@ export function recordFixAttempt(scanRoot, record) {
   try {
     const dir = stateDir(scanRoot);
     if (!isSafeStateDir(dir)) return false;
-    if (!stateWritesEnabled()) return;
+    if (!stateWritesEnabled()) return false;
   fs.mkdirSync(dir, { recursive: true });
     // One writeSync of one newline-terminated line: a concurrent reader sees
     // whole records or nothing, and a torn tail is dropped on read.

package/src/posture/fix-verify-loop.js

@@ -38,7 +38,16 @@ function _detectRunner(scanRoot) {
     } catch { return null; }
   })();
   if (pkg && pkg.scripts && pkg.scripts.test && !/no test specified/.test(String(pkg.scripts.test))) {
-    return { runner: 'npm', cmd: 'npm', args: ['test', '--silent', '--', '--passWithNoTests'] };
+    // --passWithNoTests is Jest-specific CLI syntax — appending it
+    // unconditionally broke every non-Jest npm test script (mocha, vitest,
+    // ava, tap, or a plain node script) with an "unrecognized option" exit,
+    // failing verification for a reason that has nothing to do with
+    // whether the patch actually broke anything. Only add it when Jest is
+    // actually the configured runner.
+    const usesJest = /\bjest\b/.test(String(pkg.scripts.test))
+      || Boolean(pkg.devDependencies?.jest) || Boolean(pkg.dependencies?.jest);
+    const args = usesJest ? ['test', '--silent', '--', '--passWithNoTests'] : ['test', '--silent'];
+    return { runner: 'npm', cmd: 'npm', args };
   }
   if (has('pytest.ini') || has('pyproject.toml') || has('setup.cfg')) {
     return { runner: 'pytest', cmd: 'pytest', args: ['-q', '--no-header', '-x'] };

package/src/posture/iac-reachability.js

@@ -1,22 +1,28 @@
 // IaC → application code reachability bridge (Sentinel-parity FR-DET-4).
 //
-// Detects publicly-exposed cloud resources in IaC (Terraform / CloudFormation
-// / Kubernetes) and correlates them with application-code references to the
-// same resource (by name, ARN, or hostname). Application-code findings on
-// resources that IaC has exposed get a severity bump and an explicit
-// "exposed-via-iac" tag.
+// Detects publicly-exposed cloud resources in IaC and correlates them with
+// application-code references to the same resource (by name, ARN, or
+// hostname). Application-code findings on resources that IaC has exposed get
+// a severity bump and an explicit "exposed-via-iac" tag.
 //
-// Patterns detected:
+// **Terraform only.** Only `parseTerraform` exists in this file — this header
+// previously also listed CloudFormation and five Kubernetes patterns as
+// detected; neither has any parser function anywhere here (found via
+// Stage-0 doc audit, 2026; confirmed by grep for `function parse*` in this
+// file, which returns exactly one hit). The pattern list below is therefore
+// the Terraform-only reality, not the originally-documented superset:
 //
 //   S3 bucket with public-read ACL / public-access-block disabled
 //   RDS / DocumentDB / Redshift with publicly_accessible = true
 //   Security group with 0.0.0.0/0 ingress on a sensitive port
 //   ALB / NLB / API Gateway with internet-facing scheme
-//   K8s Service of type LoadBalancer with no NetworkPolicy
-//   K8s Ingress with no auth annotation
 //   Lambda function URL with auth_type = NONE
 //   ECS task with assignPublicIp = ENABLED
 //
+// NOT IMPLEMENTED despite being previously documented here: CloudFormation
+// support, K8s Service/LoadBalancer + NetworkPolicy correlation, K8s Ingress
+// auth-annotation checking.
+//
 // Output: { exposedResources: [{name, kind, file, line, severity}], findings: [...new findings] }
 
 const SENSITIVE_PORTS = new Set([22, 23, 25, 110, 143, 3306, 3389, 5432, 6379, 27017, 9200, 9300, 1521, 5984, 11211]);

package/src/posture/integrity.js

@@ -52,19 +52,37 @@ function _readOrGenerateKey() {
       if (/^[0-9a-fA-F]{32,}$/.test(hex)) { _keySource = 'per-install'; return Buffer.from(hex, 'hex'); }
     }
   } catch { /* fall through to generate */ }
-  // Generate, mode 0600.
+  // Generate, mode 0600. `wx` — exclusive create, same TOCTOU fix
+  // evidence-bundle.js's ensureKeyPair() already applies to its own key
+  // material: on first use, two concurrent processes can both pass the
+  // existsSync check above as false and both reach here. Without exclusive
+  // create, the last writer's key silently wins on disk while every OTHER
+  // process keeps signing with the key it generated and lost — a key that
+  // now exists nowhere, so every signature made under it fails to verify
+  // forever after, indistinguishable from real tampering.
   const buf = crypto.randomBytes(32);
   try {
     fs.mkdirSync(_keyDir(), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(fp, buf.toString('hex') + '\n', { mode: 0o600 });
+    fs.writeFileSync(fp, buf.toString('hex') + '\n', { mode: 0o600, flag: 'wx' });
     _keySource = 'per-install-new';
-  } catch {
-    // Could not persist — this key lives for this process only, so nothing
-    // signed with it will verify on any later run. Callers must be able to see
-    // that, or a permanently-unverifiable signature looks like a valid one.
+    return buf;
+  } catch (e) {
+    if (e.code === 'EEXIST') {
+      // Another process won the race and persisted its key first — use
+      // THAT key instead of the one we generated, or we'd return a key
+      // that matches nothing on disk.
+      try {
+        const hex = fs.readFileSync(fp, 'utf8').trim();
+        if (/^[0-9a-fA-F]{32,}$/.test(hex)) { _keySource = 'per-install'; return Buffer.from(hex, 'hex'); }
+      } catch { /* fall through to ephemeral */ }
+    }
+    // Could not persist (or the winner's key was unreadable/malformed) —
+    // this key lives for this process only, so nothing signed with it will
+    // verify on any later run. Callers must be able to see that, or a
+    // permanently-unverifiable signature looks like a valid one.
     _keySource = 'ephemeral';
+    return buf;
   }
-  return buf;
 }
 
 // REMOVED (2026-08-08): the legacy hostname-derived key.

package/src/posture/model-rescan.js

@@ -74,4 +74,69 @@ export function summarizeDelta(changed) {
   return lines.join('\n');
 }
 
+// Stage 6 correctness audit: diffValidatorRuns/persistRescanReport/
+// summarizeDelta above were fully built, but nothing in the codebase ever
+// produced a `{model, results: {findingId: {verdict, reason}}}` run file
+// for them to consume — commands/labs.md's `--model-rescan` mode was
+// disclosed as genuinely unwired rather than fabricated. This is the
+// missing producer: runs the SAME findings through the LLM validator twice
+// — once under whatever model the environment currently resolves to
+// ("from"), once under `toModel` ("to", via the existing per-role env
+// override `AGENTIC_SECURITY_LLM_MODEL_VALIDATE` — no new plumbing needed,
+// llm-validator/providers.js already supports it) — and turns the two runs
+// into a real delta report. Reuses validateMany's own candidate filter
+// (critical/high severity, low confidence, or AST parser) rather than
+// re-validating every finding, matching normal validation scope. When no
+// LLM endpoint is configured, validateMany degrades every finding to
+// 'unvalidated' with no network call — this function inherits that
+// no-network-by-default behavior rather than working around it.
+export async function runModelRescan(scanRoot, { toModel } = {}) {
+  if (!toModel) return { ok: false, reason: 'no --model given to rescan with' };
+  const scan = _readJson(scanRoot, 'last-scan.json');
+  if (!scan) return { ok: false, reason: 'no .agentic-security/last-scan.json — run a scan first' };
+  const findings = Array.isArray(scan.findings) ? scan.findings : [];
+  if (!findings.length) return { ok: false, reason: 'last scan has no findings to re-validate' };
+
+  const fileContents = {};
+  for (const f of findings) {
+    if (!f.file || fileContents[f.file] !== undefined) continue;
+    try { fileContents[f.file] = fs.readFileSync(path.join(scanRoot, f.file), 'utf8'); }
+    catch { /* file may have moved/been deleted since the scan; validateMany skips it */ }
+  }
+
+  const { validateMany } = await import('../llm-validator/index.js');
+  const { resolveProvider } = await import('../llm-validator/providers.js');
+
+  const runFor = async (envKey, modelOverride) => {
+    const prev = envKey ? process.env[envKey] : undefined;
+    if (envKey) process.env[envKey] = modelOverride;
+    let resolvedModel = 'unvalidated';
+    try {
+      const r = resolveProvider({ role: 'validate' });
+      if (r.ok) resolvedModel = r.config.model;
+      const clones = findings.map(f => ({ ...f }));
+      await validateMany(clones, { fileContents, scanRoot });
+      const results = {};
+      for (const f of clones) {
+        const id = f.stableId || f.id;
+        if (!id) continue;
+        results[id] = { verdict: f.validator_verdict || 'unvalidated', reason: f.validator_reasoning || null };
+      }
+      return { model: resolvedModel, results };
+    } finally {
+      if (envKey) {
+        if (prev === undefined) delete process.env[envKey];
+        else process.env[envKey] = prev;
+      }
+    }
+  };
+
+  const runA = await runFor(null, null);
+  const runB = await runFor('AGENTIC_SECURITY_LLM_MODEL_VALIDATE', toModel);
+
+  const changed = diffValidatorRuns(runA, runB);
+  const reportPath = persistRescanReport(scanRoot, runA.model, runB.model, changed);
+  return { ok: true, from: runA.model, to: runB.model, changed, reportPath, summary: summarizeDelta(changed) };
+}
+
 export const _internals = {};

package/src/posture/mttr.js

@@ -10,6 +10,11 @@
 import * as crypto from 'node:crypto';
 
 // Stable fingerprint for cross-scan finding identity. Mirrors the dedupe key.
+// Exported so a caller can compute the "removed since baseline" (i.e. fixed)
+// set that computeMTTR needs, using the exact same identity function
+// buildBaselineMap uses internally — a caller-side reimplementation would
+// risk drifting from this one and silently under/over-counting fixes.
+export function fingerprintFinding(f) { return _fingerprint(f); }
 function _fingerprint(f) {
   const file = (f.file || '').split(' -> ').pop();
   const line = f.line || f.source?.line || f.sink?.line || 0;

package/src/posture/poc-inprocess.js

@@ -119,14 +119,33 @@ function _binding(finding, call) {
 // The request property the handler reads. Anchored to the request identifier
 // the export actually binds, so a file that reads `req.query` while exporting
 // `(request, response)` does not produce a PoC built on the wrong name.
-function _requestSource(content, reqIdent) {
+//
+// A handler that reads more than one request property (extremely common —
+// e.g. a harmless query param for pagination alongside the actual body
+// param used in the sink) used to always get the first property found in a
+// fixed query>body>params priority, with no relationship to which one
+// actually reaches the sink — silently building a PoC against an inert
+// parameter while the real injection point went untouched. When sinkLine
+// is known, prefer whichever match sits closest to it (line proximity is a
+// cheap, effective proxy for "this is the value that flows into the sink a
+// few lines below/above it"); otherwise fall back to the old first-found
+// behavior for callers that can't supply a line.
+function _requestSource(content, reqIdent, sinkLine) {
   const esc = reqIdent.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const candidates = [];
   for (const prop of ['query', 'body', 'params']) {
-    const re = new RegExp(`\\b${esc}\\.${prop}\\.(\\w+)`);
-    const m = content.match(re);
-    if (m) return { prop, key: m[1] };
+    const re = new RegExp(`\\b${esc}\\.${prop}\\.(\\w+)`, 'g');
+    let m;
+    while ((m = re.exec(content))) {
+      const line = content.slice(0, m.index).split('\n').length;
+      candidates.push({ prop, key: m[1], line });
+    }
   }
-  return null;
+  if (!candidates.length) return null;
+  if (typeof sinkLine === 'number') {
+    candidates.sort((a, b) => Math.abs(a.line - sinkLine) - Math.abs(b.line - sinkLine));
+  }
+  return { prop: candidates[0].prop, key: candidates[0].key };
 }
 
 // The sink must interpolate into a SHELL, not an argv array. `exec`/`execSync`
@@ -184,7 +203,7 @@ export function synthesizeInProcessPoc(finding, fileContent) {
     return { ok: false, reason: 'no exported two-argument (req, res) handler found — nothing to call without inventing an interface' };
   }
 
-  const src = _requestSource(fileContent, reqIdent);
+  const src = _requestSource(fileContent, reqIdent, finding.line);
   if (!src) {
     return { ok: false, reason: `the handler does not read query/body/params off '${reqIdent}', so the injection point is unknown` };
   }
@@ -392,7 +411,7 @@ function _sqlInjectionPoc(finding, fileContent) {
   if (!found) return NO_HANDLER;
   const { call, reqIdent } = found;
 
-  const src = _requestSource(fileContent, reqIdent);
+  const src = _requestSource(fileContent, reqIdent, finding.line);
   if (!src) {
     return { ok: false, reason: `the handler does not read query/body/params off '${reqIdent}', so the injection point is unknown` };
   }
@@ -490,7 +509,7 @@ function _pathTraversalPoc(finding, fileContent) {
   if (!READ_SINK.test(fileContent)) {
     return { ok: false, reason: 'no readFile/sendFile sink in the file, so there is no served content to observe coming back' };
   }
-  const src = _requestSource(fileContent, reqIdent);
+  const src = _requestSource(fileContent, reqIdent, finding.line);
   if (!src) {
     return { ok: false, reason: `the handler does not read query/body/params off '${reqIdent}', so the traversal point is unknown` };
   }

package/src/posture/regression-test-gen.js

@@ -103,18 +103,30 @@ test('${finding.vuln.replace(/'/g, "\\'")}', async () => {
 }
 
 function _renderPytest(finding, poc) {
+  // Same finding-specific extraction _renderJest uses, not the hardcoded
+  // SQL-injection payload every call used to emit regardless of the actual
+  // vulnerability class. poc.code is assumed to follow this project's own
+  // URL_/METHOD/PAYLOAD synthesis convention (poc-generator.js), same as
+  // the JS PoCs this extraction already works against.
+  const url = _extractUrl(poc.code) || 'http://localhost:3000';
+  const method = (_extractMethod(poc.code) || 'POST').toLowerCase();
+  const payload = _extractPayloadValue(poc.code) || 'PoC';
   return `# Regression test for ${finding.vuln} (${finding.cwe || 'unknown CWE'}).
-# Auto-generated from P1.1 PoC.
+# Auto-generated from P1.1 PoC; fails on vulnerable code, passes after the fix.
 
 import requests
 
 
 def test_${(finding.stableId || finding.id || 'finding').replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 40)}():
-    url = 'http://localhost:3000'
-    r = requests.post(url, json={'input': "' UNION SELECT username, password FROM users--"})
-    # After the fix, the response should not contain SQL-syntax-error evidence.
+    url = ${JSON.stringify(url)}
+    payload = ${JSON.stringify(payload)}
+    r = requests.${method}(url, json={'input': payload}) if ${JSON.stringify(method)} != 'get' \\
+        else requests.get(url, params={'input': payload})
+    # The assertion below is the "exploit demonstrated" signal — when this
+    # test PASSES, the vuln is still present. After the fix, this assertion
+    # SHOULD fail. Inverse the assertion in a green build.
     text = r.text
-    demonstrated = 'syntax error' in text.lower() or '<script>' in text
+    demonstrated = 'PoC' in text or 'syntax error' in text.lower() or '<script>' in text
     assert not demonstrated, f'Vulnerability still present: {text[:200]}'
 `;
 }
@@ -127,10 +139,13 @@ function _extractMethod(code) {
   const m = String(code || '').match(/METHOD = (['"])([A-Z]+)\1/);
   return m ? m[2] : null;
 }
-function _extractPayloadLine(code) {
+function _extractPayloadValue(code) {
   const m = String(code || '').match(/PAYLOAD = `([^`]+)`/);
-  if (m) return `const PAYLOAD = ${JSON.stringify(m[1])};`;
-  return `const PAYLOAD = 'PoC';`;
+  return m ? m[1] : null;
+}
+function _extractPayloadLine(code) {
+  const v = _extractPayloadValue(code);
+  return `const PAYLOAD = ${JSON.stringify(v || 'PoC')};`;
 }
 
 /**

package/src/posture/reverse-blast-radius.js

@@ -96,7 +96,11 @@ export function annotateScaReverseBlast(findings, fileContents) {
   if (!Object.keys(map).length) return findings;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
-    const pkg = f.package || f.dependency || f.pkg;
+    // SCA findings (engine.js's queryOSV) carry the package name as `.name`
+    // — `.package`/`.dependency`/`.pkg` are never set anywhere in this
+    // codebase; kept as a fallback in case a caller supplies a differently-
+    // shaped finding.
+    const pkg = f.name || f.package || f.dependency || f.pkg;
     if (!pkg || !map[pkg]) continue;
     f.reverseExposure = {
       importerCount: map[pkg].directImporters.length,

package/src/posture/risk-dollars.js

@@ -110,8 +110,25 @@ function _impactFor(finding, cfg) {
   return table.default;
 }
 
+// SCA entries carry reachabilityTier/routeReachable (engine.js's SCA
+// reachability pass); SAST findings never do — they carry relevanceTier/
+// entrypointReachable instead (posture/relevance.js). Without this
+// fallback, _reachDiscount always read 'unknown' (0.3) for every SAST
+// finding, regardless of whether it was actually route-reachable.
+function _relevanceTierToReachTier(relevanceTier) {
+  switch (relevanceTier) {
+    case 'direct':      return 'route-reachable';
+    case 'indirect':    return 'function-reachable';
+    case 'unreachable': return 'unreachable';
+    default:            return null;
+  }
+}
+
 function _reachDiscount(finding) {
-  const tier = finding.reachabilityTier || finding.routeReachable && 'route-reachable' || 'unknown';
+  const tier = finding.reachabilityTier
+    || (finding.routeReachable && 'route-reachable')
+    || _relevanceTierToReachTier(finding.relevanceTier)
+    || 'unknown';
   return REACH_DISCOUNT[tier] || 0.3;
 }
 

package/src/posture/secret-history.js

@@ -31,17 +31,26 @@ export function scanHistoryDiff(diffText, commit, detectFn) {
   if (!added.trim()) return [];
   let findings = [];
   try { findings = detectFn(`git-history@${commit}`, added) || []; } catch { return []; }
-  return findings.map((f) => ({
-    ...f,
-    id: `secret-history:${commit}:${f.id || f.vuln || 'secret'}`,
-    file: `git-history@${commit}`,
-    line: 0,
-    commit,
-    _historical: true,
-    vuln: `${f.vuln || 'Hardcoded Secret'} (in git history)`,
-    description: `${f.description || 'A credential was committed.'} Found in commit ${commit}; even if removed from HEAD it remains recoverable from git and must be rotated.`,
-    remediation: 'Rotate the credential now, then purge it from history (git filter-repo / BFG) and move it to a secrets manager. Removing it from HEAD alone is insufficient.',
-  }));
+  return findings.map((f) => {
+    const remediation = 'Rotate the credential now, then purge it from history (git filter-repo / BFG) and move it to a secrets manager. Removing it from HEAD alone is insufficient.';
+    return {
+      ...f,
+      id: `secret-history:${commit}:${f.id || f.vuln || 'secret'}`,
+      file: `git-history@${commit}`,
+      line: 0,
+      commit,
+      _historical: true,
+      vuln: `${f.vuln || 'Hardcoded Secret'} (in git history)`,
+      description: `${f.description || 'A credential was committed.'} Found in commit ${commit}; even if removed from HEAD it remains recoverable from git and must be rotated.`,
+      remediation,
+      // report/index.js's _remediationOf checks `.fix` before `.remediation`
+      // — the underlying detector already set `.fix` to a generic "remove
+      // the line" string, which would otherwise silently shadow this
+      // history-specific instruction ("removing it from HEAD alone is
+      // insufficient") in every report format.
+      fix: remediation,
+    };
+  });
 }
 
 /**

package/src/posture/security-trend.js

@@ -35,7 +35,13 @@ function _snapshotFromScan(scan, label) {
     medium: findings.filter(f => f.severity === 'medium').length,
     low: findings.filter(f => f.severity === 'low').length,
     kev: findings.filter(f => f.kev).length,
-    ids: new Set(findings.map(f => f.id).filter(Boolean)),
+    // stable-id.js exists specifically because the default `id` embeds file
+    // path + line number, so any refactor that shifts a line rotates the id
+    // — using it here would report the same unfixed vulnerability as one
+    // "fixed" finding and one "introduced" finding on every such shift.
+    // stableId omits the exact line by design; fall back to `id` only for
+    // finding shapes that never got a stableId annotated.
+    ids: new Set(findings.map(f => f.stableId || f.id).filter(Boolean)),
   };
 }
 

package/src/posture/stack-playbook.js

@@ -185,6 +185,18 @@ function _buildPlaybook(stack) {
     ]});
   }
 
+  // Express
+  if (stack.has('express')) {
+    sections.push({ title: 'Express', items: [
+      'Use helmet() to set security headers (X-Frame-Options, X-Content-Type-Options, HSTS) — Express sets none of these by default',
+      'Never use body-parser / express.json() without a size limit — set `limit` explicitly to prevent request-body DoS',
+      'Apply express-rate-limit to authentication and any expensive routes',
+      'Validate and sanitize all req.params / req.query / req.body — Express does not validate input for you',
+      'Set `app.disable(\'x-powered-by\')` so error responses and headers do not advertise the framework/version to attackers',
+      'Use a CSRF middleware (e.g. csrf-csrf) on any route that relies on cookie-based sessions',
+    ]});
+  }
+
   // Django
   if (stack.has('django')) {
     sections.push({ title: 'Django', items: [
@@ -202,7 +214,16 @@ function _buildPlaybook(stack) {
 function _findingFromItem(scanRoot, stackName, item, idx) {
   return {
     id: `stack-playbook:${stackName.replace(/\s+/g, '_').toUpperCase()}:${idx}`,
-    title: `[${stackName} Security Checklist] ${item.slice(0, 80)}`,
+    // The findings schema requires `vuln` (root CLAUDE.md); this used to set
+    // `title` instead, which isn't a schema field at all. engine.js's generic
+    // no-vuln-name filter (`_shouldKeep`) treats any non-SCA finding with no
+    // `vuln` string as unenriched noise and drops it — silently, for every
+    // stack, confirmed live via a real scan whose logicVulns went from 6
+    // playbook findings right after they were pushed to 0 by the time the
+    // scan returned. `vuln` is now the actionable string this finding is
+    // actually about; `description`/`remediation` (already correct) keep
+    // the fuller text.
+    vuln: `[${stackName} Security Checklist] ${item.slice(0, 80)}`,
     severity: 'info',
     file: 'package.json',
     line: 1,

package/src/posture/threat-model-grounding.js

@@ -13,8 +13,8 @@
 //     SOC2 / HIPAA / GDPR) adds compliance-tag fields to findings in
 //     matching families (PII → HIPAA/GDPR; auth → SOC2 CC6.1; etc.).
 //   - **Stated attacker** — "## Attacker model" / "## Threat actor"
-//     section sets f.attackerProfile = 'script-kiddie' | 'apt' | 'insider'
-//     for use in downstream prioritization.
+//     section sets f.threatModel.attacker = 'script-kiddie' | 'apt' |
+//     'insider' for use in downstream prioritization.
 //
 // Opt-out: AGENTIC_SECURITY_NO_THREAT_MODEL_GROUNDING=1
 

package/src/posture/validator-metrics.js

@@ -92,15 +92,22 @@ export function recordTriage(scanRoot, { family, verdict, stableId }) {
   const data = _read(scanRoot);
   data.productionTriage = data.productionTriage || {};
   const row = data.productionTriage[family] = data.productionTriage[family] || { tp: 0, fp: 0, wontfix: 0, lastAt: null };
+  void stableId;
+  // Already frozen from a previous call — `_capped: true` was persisted at
+  // the moment the cap was crossed (below), so this is a deliberate,
+  // visible freeze: nothing new is written, but nothing was silently lost
+  // either. Previously the crossing call itself never called _write, so
+  // `_capped` never reached disk and EVERY call after the cap — not just
+  // more of the same verdict, any verdict — silently vanished with the
+  // on-disk row frozen one write short of the real crossing point.
+  if (row._capped) return row;
   row[verdict] = (row[verdict] || 0) + 1;
   row.lastAt = new Date().toISOString();
   // Cap per-family rows so a runaway triage script can't bloat the file.
+  // The crossing call still writes — that's what makes the freeze visible.
   if ((row.tp || 0) + (row.fp || 0) + (row.wontfix || 0) > 10_000) {
-    // Stop accumulating; the trend is well-established by now.
     row._capped = true;
-    return row;
   }
-  void stableId;
   _write(scanRoot, data);
   return row;
 }