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

package/src/posture/evidence-bundle.js

@@ -0,0 +1,276 @@
+// Per-finding evidence bundles, signed so a THIRD PARTY can verify them.
+// PRD Phase 2 / D2.
+//
+// WHAT WAS MISSING
+// ----------------
+// `attestation.js` already turns a run into a checkable digest, and it is
+// explicit about its own ceiling: the signature is a per-install SYMMETRIC HMAC,
+// so it is "tamper-evidence for the operator, not third-party non-repudiation."
+// Anyone who can verify it can also forge it. That is fine for detecting local
+// corruption and useless for handing a finding to somebody else.
+//
+// This module closes that gap for the artefact that actually travels: a single
+// finding plus the evidence behind it. A buyer, an auditor, or a downstream
+// consumer can check the bundle with the PUBLIC key alone, having never had
+// access to ours.
+//
+// WHY A SEPARATE MODULE RATHER THAN EXTENDING attestation.js
+// ----------------------------------------------------------
+// They answer different questions and must not be conflated. A run attestation
+// says "this set of findings came from this engine, ruleset and bundle". An
+// evidence bundle says "THIS finding is backed by THIS evidence, and here is
+// proof the claim was not edited after the fact." One is about reproducibility,
+// the other about portability. Merging them would produce an artefact that is
+// worse at both.
+//
+// WHAT A BUNDLE PROVES, AND WHAT IT DOES NOT
+// -------------------------------------------
+// PROVES — the bundle's contents are exactly what the holder of the signing key
+// attested, unmodified. Nothing in it has been added, removed, or edited since.
+//
+// DOES NOT PROVE — that the finding is real. A signature is an integrity claim,
+// never a correctness claim. An `unproven` finding in a signed bundle is still
+// an unproven finding; the signature only stops someone silently upgrading the
+// word `unproven` to `execution-proven` in transit. Both statements are carried
+// INSIDE the bundle so they travel with it and cannot be dropped by a
+// summariser.
+//
+// The evidence chain is deliberately the honest one this engine already
+// computes: the proof tier, what the sandbox observed, which backend ran it, the
+// taint path if there is one. A bundle for a regex finding says so plainly
+// rather than dressing it up.
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+
+export const BUNDLE_SCHEMA = 'agentic-security/finding-evidence@1';
+
+/** Where the Ed25519 signing key lives. Mirrors integrity.js's key handling. */
+function keyDir() {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'agentic-security');
+}
+const PRIVATE_KEY_FILE = 'attest-key.pem';
+const PUBLIC_KEY_FILE = 'attest-key.pub.pem';
+
+export function keyPaths(dir = keyDir()) {
+  return {
+    privateKey: path.join(dir, PRIVATE_KEY_FILE),
+    publicKey: path.join(dir, PUBLIC_KEY_FILE),
+  };
+}
+
+/**
+ * Load the signing key pair, generating one on first use.
+ *
+ * Ed25519 from node:crypto — no new dependency, and deliberately not a
+ * transparency-log scheme: those need a network round trip, and this project
+ * does not make runtime cloud calls. A log-backed option can layer on later
+ * without changing the bundle format.
+ */
+export function ensureKeyPair(dir = keyDir()) {
+  const p = keyPaths(dir);
+
+  // NO existsSync-then-read. This project's own scanner flagged the first
+  // version of this function for TOCTOU (CWE-367) and it was right: between an
+  // existence check and the read, an attacker who can write this directory can
+  // swap the file, and the thing being swapped is a SIGNING KEY. Winning that
+  // race means we sign with a key the attacker controls, which defeats the
+  // entire point of the module. Read first and treat absence as the exceptional
+  // case — there is then no window between the check and the use, because there
+  // is no check.
+  try {
+    const privateKeyPem = fs.readFileSync(p.privateKey, 'utf8');
+    const publicKeyPem = fs.readFileSync(p.publicKey, 'utf8');
+    if (privateKeyPem && publicKeyPem) {
+      return { privateKeyPem, publicKeyPem, created: false, ...p };
+    }
+  } catch { /* missing or unreadable — fall through and generate */ }
+
+  const { privateKey, publicKey } = crypto.generateKeyPairSync('ed25519');
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' });
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' });
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  // `wx` — exclusive create. If another process generated a key between our
+  // failed read and this write, we must NOT clobber it: every bundle already
+  // signed with that key would silently stop verifying. On collision, re-read
+  // and use the winner's key.
+  try {
+    fs.writeFileSync(p.privateKey, privateKeyPem, { mode: 0o600, flag: 'wx' });
+    fs.writeFileSync(p.publicKey, publicKeyPem, { mode: 0o644, flag: 'w' });
+    return { privateKeyPem, publicKeyPem, created: true, ...p };
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+    // 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
+      }
+    }
+  }
+}
+
+/**
+ * Canonical bytes for signing.
+ *
+ * An ALLOWLIST, exactly as attestation.js canonicalises: a field that is not
+ * named here is not signed, so a future addition cannot silently enter the
+ * signed surface. Sorted keys, so serialisation order cannot change the
+ * signature.
+ */
+export function canonicalBytes(bundle) {
+  const signed = {
+    schema: bundle.schema,
+    finding: bundle.finding,
+    evidence: bundle.evidence,
+    engine: bundle.engine,
+    proves: bundle.proves,
+    doesNotProve: bundle.doesNotProve,
+  };
+  return Buffer.from(canonicalJson(signed), 'utf8');
+}
+
+/**
+ * Deterministic JSON: keys sorted at EVERY level, arrays order-preserving.
+ *
+ * Written by hand rather than using JSON.stringify's replacer argument, and the
+ * reason matters. The first version of this function did
+ * `JSON.stringify(signed, Object.keys(signed).sort())`, believing the array
+ * argument was a top-level field allowlist. It is not — a replacer ARRAY is a
+ * key filter applied at every nesting depth, so every nested object serialised
+ * as `{}` and the signature covered nothing but the two prose strings. A bundle
+ * whose severity was edited from `high` to `critical` verified as authentic.
+ *
+ * That is the worst possible failure for this module: a security feature that
+ * appears to work, produces a valid-looking signature, and protects nothing. It
+ * was caught by tampering with a bundle and expecting verification to fail —
+ * which is why the tamper cases in the test file are not optional extras.
+ */
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+const PROVES =
+  'The contents of this bundle are exactly what the signer attested, unmodified.';
+const DOES_NOT_PROVE =
+  'That the finding is real. A signature is an integrity claim, never a correctness ' +
+  'claim — read `evidence.proofTier` for how well-supported the finding actually is. ' +
+  'An unproven finding in a signed bundle is still an unproven finding.';
+
+/**
+ * Build an unsigned bundle from a finding.
+ *
+ * Everything here is copied from what the engine already computed. Nothing is
+ * inferred, and a missing field stays missing rather than being defaulted into
+ * something more confident-looking than the truth.
+ */
+export function buildEvidenceBundle(finding, { engineVersion, rulesetVersion, bundleSha, commit } = {}) {
+  if (!finding || typeof finding !== 'object') return null;
+  return {
+    schema: BUNDLE_SCHEMA,
+    finding: {
+      id: finding.id ?? null,
+      stableId: finding.stableId ?? null,
+      severity: finding.severity ?? null,
+      file: finding.file ?? null,
+      line: finding.line ?? null,
+      vuln: finding.vuln ?? null,
+      cwe: finding.cwe ?? null,
+      family: finding.family ?? null,
+      parser: finding.parser ?? null,
+    },
+    evidence: {
+      // The honest chain, in the vocabulary the engine already uses.
+      proofTier: finding.proofTier ?? null,
+      proofEvidence: finding.proofEvidence ?? null,
+      confidence: finding.confidence ?? null,
+      exploitability: finding.exploitability ?? null,
+      unreachable: finding.unreachable ?? null,
+      // Present only for the layers that produce them; absent means absent.
+      taintPath: finding.pathSteps ?? finding.exampleFlows ?? null,
+      discovery: finding.discovery ?? null,
+    },
+    engine: {
+      engineVersion: engineVersion ?? null,
+      rulesetVersion: rulesetVersion ?? null,
+      bundleSha: bundleSha ?? null,
+      commit: commit ?? null,
+    },
+    proves: PROVES,
+    doesNotProve: DOES_NOT_PROVE,
+  };
+}
+
+/** Sign a bundle. Returns a new object; the input is not mutated. */
+export function signEvidenceBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, canonicalBytes(bundle), privateKeyPem);
+  return {
+    ...bundle,
+    signature: {
+      algorithm: 'ed25519',
+      canonicalisation: BUNDLE_SCHEMA,
+      value: sig.toString('base64'),
+    },
+  };
+}
+
+/**
+ * Verify a bundle with a PUBLIC key. This is the whole point: the verifier
+ * never needs, and never had, the signing key.
+ *
+ * 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}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  let ok = false;
+  try {
+    ok = crypto.verify(null, canonicalBytes(bundle), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return ok
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+}

package/src/posture/exploitability-probability.js

@@ -35,6 +35,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { wilsonInterval } from './calibration.js';
 
+import { statePath } from './state-dir.js';
 // CISA KEV-derived base rate per CWE family. These are rough mid-2025
 // observations of "actually exploited in the wild" rates among findings
 // of the family, not academic numbers. Refresh annually.
@@ -138,7 +139,7 @@ function _clamp01(x) { return Math.max(0.001, Math.min(0.999, x)); }
 // (cwe × language × framework) grain.
 function _loadHistory(scanRoot) {
   if (!scanRoot) return [];
-  const fp = path.join(scanRoot, '.agentic-security', 'exploit-history.jsonl');
+  const fp = statePath(scanRoot, 'exploit-history.jsonl');
   if (!fs.existsSync(fp)) return [];
   const out = [];
   try {
@@ -188,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/feature-flags.js

@@ -21,6 +21,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const FLAG_PATTERNS = [
   // LaunchDarkly
   [/\bldClient\.variation\s*\(\s*['"`]([^'"`]+)['"`]/g, 'launchdarkly'],
@@ -44,8 +45,8 @@ const FLAG_PATTERNS = [
 
 function loadRollouts(scanRoot) {
   const candidates = [
-    '.agentic-security/feature-flag-rollouts.json',
-    '.agentic-security/feature-flags.json',
+    'feature-flag-rollouts.json',
+    'feature-flags.json',
   ];
   for (const rel of candidates) {
     const fp = path.join(scanRoot || process.cwd(), rel);

package/src/posture/findings-memory.js

@@ -15,10 +15,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE = '.agentic-security';
 
+import { statePath } from './state-dir.js';
 function _read(scanRoot, name) {
-  try { return fs.readFileSync(path.join(scanRoot, STATE, name), 'utf8'); } catch { return null; }
+  try { return fs.readFileSync(statePath(scanRoot, name), 'utf8'); } catch { return null; }
 }
 
 function _readJson(scanRoot, name) {
@@ -99,7 +99,7 @@ export function queryFindingsMemory(scanRoot, query) {
 
   // 3. Scan history.
   try {
-    const histDir = path.join(scanRoot, STATE, 'scan-history');
+    const histDir = statePath(scanRoot, 'scan-history');
     if (fs.existsSync(histDir)) {
       const files = fs.readdirSync(histDir).filter(f => f.endsWith('.json')).slice(-10);
       for (const f of files) {

package/src/posture/fix-history.js

@@ -12,7 +12,7 @@ import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { isSafeStateDir, statePath } from './state-dir.js';
+import { isSafeStateDir, statePath, stateWritesEnabled } from './state-dir.js';
 
 function historyDir(scanRoot) {
   return statePath(scanRoot, 'fix-history');
@@ -20,6 +20,9 @@ function historyDir(scanRoot) {
 function logPath(scanRoot) { return path.join(historyDir(scanRoot), 'log.json'); }
 
 function ensure(scanRoot) {
+  // Read-only scan: callers already treat `false` as "history unavailable",
+  // so the switch needs no new branch anywhere else.
+  if (!stateWritesEnabled()) return false;
   const dir = historyDir(scanRoot);
   if (!isSafeStateDir(path.dirname(dir))) return false;
   fs.mkdirSync(dir, { recursive: true });
@@ -65,7 +68,7 @@ function sha(s) { return crypto.createHash('sha256').update(s).digest('hex').sli
 // findings by `id` (the finding's canonical key from the engine) so we can
 // stash the corresponding stableId on the fix entry and verify in recover().
 function _lastScanPath(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', 'last-scan.json');
+  return statePath(scanRoot, 'last-scan.json');
 }
 function _readLastScan(scanRoot) {
   const fp = _lastScanPath(scanRoot);

package/src/posture/fix-metrics.js

@@ -34,9 +34,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { isSafeStateDir } from './state-dir.js';
+import { isSafeStateDir, stateDir, statePath, stateWritesEnabled } from './state-dir.js';
 
-const STATE_DIR = '.agentic-security';
 const LOG_FILE = 'fix-metrics.jsonl';
 
 // Below this many samples a percentile is an artifact of the sample, not a
@@ -49,7 +48,7 @@ const RELIABLE_N = 10;
 export const FIX_STAGES = Object.freeze(['rescan', 'lint', 'tests', 'honesty', 'poc']);
 
 function _logPath(scanRoot) {
-  return path.join(scanRoot, STATE_DIR, LOG_FILE);
+  return statePath(scanRoot, LOG_FILE);
 }
 
 /**
@@ -61,9 +60,10 @@ function _logPath(scanRoot) {
 export function recordFixAttempt(scanRoot, record) {
   if (!scanRoot || !record || typeof record !== 'object') return false;
   try {
-    const dir = path.join(scanRoot, STATE_DIR);
+    const dir = stateDir(scanRoot);
     if (!isSafeStateDir(dir)) return false;
-    fs.mkdirSync(dir, { recursive: true });
+    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.
     fs.appendFileSync(_logPath(scanRoot), JSON.stringify(record) + '\n', 'utf8');

package/src/posture/fix-plan.js

@@ -12,6 +12,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const MAX_FILES = 3;
 const MAX_LOC   = 100;
 
@@ -103,7 +104,7 @@ export function renderFixPlan(finding, opts = {}) {
 // Returns the absolute path of the written file, or null on error.
 export function emitFixPlanFile(scanRoot, finding, opts = {}) {
   if (!scanRoot || !finding) return null;
-  const dir = path.join(scanRoot, '.agentic-security', 'fix-plans');
+  const dir = statePath(scanRoot, 'fix-plans');
   try { fs.mkdirSync(dir, { recursive: true }); } catch { return null; }
   const id = finding.stableId || finding.id || `unknown-${Date.now().toString(36)}`;
   const fp = path.join(dir, `${id}.md`);

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/grader-calibration.js

@@ -26,18 +26,17 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const TRIAGE_FILE = '.agentic-security/triage-feedback.json';
-const SCAN_FILE   = '.agentic-security/last-scan.json';
 
+import { statePath } from './state-dir.js';
 function _loadTriageFeedback(scanRoot) {
-  const fp = path.join(scanRoot, TRIAGE_FILE);
+  const fp = statePath(scanRoot, 'triage-feedback.json');
   if (!fs.existsSync(fp)) return [];
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')).entries || []; }
   catch { return []; }
 }
 
 function _loadScanVerdicts(scanRoot) {
-  const fp = path.join(scanRoot, SCAN_FILE);
+  const fp = statePath(scanRoot, 'last-scan.json');
   if (!fs.existsSync(fp)) return [];
   try {
     const scan = JSON.parse(fs.readFileSync(fp, 'utf8'));

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/intent-context.js

@@ -29,6 +29,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const INTENT_PATH_RE = /(?:^|\/)(?:examples?|demos?|tutorials?|sandbox|playground|challenges?|ctf)(?:\/|$)/i;
 
 const FILE_HEADER_MARKERS = [
@@ -49,7 +50,7 @@ function _readSafely(fp) {
 }
 
 function _readIntentDeclaration(scanRoot) {
-  const fp = path.join(scanRoot, '.agentic-security', 'current-intent.md');
+  const fp = statePath(scanRoot, 'current-intent.md');
   if (!fs.existsSync(fp)) return null;
   const body = _readSafely(fp);
   if (!body) return null;

package/src/posture/learning.js

@@ -22,11 +22,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const FILE = '.agentic-security/triage-feedback.json';
+import { statePath, stateWritesEnabled } from './state-dir.js';
 
 export function loadFeedback(scanRoot) {
   if (!scanRoot) return { entries: [] };
-  const fp = path.join(scanRoot, FILE);
+  const fp = statePath(scanRoot, 'triage-feedback.json');
   if (!fs.existsSync(fp)) return { entries: [] };
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')) || { entries: [] }; }
   catch { return { entries: [] }; }
@@ -34,7 +34,8 @@ export function loadFeedback(scanRoot) {
 
 export function saveFeedback(scanRoot, data) {
   if (!scanRoot) return;
-  const fp = path.join(scanRoot, FILE);
+  const fp = statePath(scanRoot, 'triage-feedback.json');
+  if (!stateWritesEnabled()) return;
   fs.mkdirSync(path.dirname(fp), { recursive: true });
   fs.writeFileSync(fp, JSON.stringify(data, null, 2));
 }