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

package/src/posture/privacy-framework.js

@@ -0,0 +1,262 @@
+// NIST Privacy Framework 1.1 — assessment + remediation planning.
+//
+// The bundled control set (`compliance-frameworks/nist-privacy-1-1.json`) is
+// rendered by `auditor-walkthrough.js` like every other framework. This module
+// adds the half a walkthrough cannot give you: a gap becomes a FINDING carrying
+// a concrete remediation, so it flows through the same triage and `/fix` path
+// as any other finding rather than sitting in a narrative nobody actions.
+//
+// THE INTEGRITY RULE THIS MODULE EXISTS TO ENFORCE
+// -----------------------------------------------
+// NIST ships a `Code Testable?` rating per control — yes / partial / no. On the
+// 104 controls: 23 yes, 33 partial, **48 no**.
+//
+// That rating says whether a control COULD be assessed from source code. It does
+// NOT say this engine assesses it. Conflating the two is how a compliance tool
+// starts reporting governance controls — "the organization's privacy values are
+// communicated" — as PASSED because no scanner rule fired against them. Silence
+// is not evidence, and a clean report over 48 controls nobody measured is worse
+// than no report: it is a false assurance that someone will hand to an auditor.
+//
+// So every control lands in exactly one of four buckets, and the bucket is
+// always stated:
+//
+//   satisfied     mapped to a real engine signal, and that signal is clean
+//   gap           mapped to a real engine signal, and that signal is dirty
+//                 → this is the only bucket that produces a finding
+//   engine-gap    NIST rates it code-testable, but this engine has no signal
+//                 → disclosed BY NAME, never counted as satisfied
+//   manual        NIST rates it not code-testable (governance, policy, process)
+//                 → out of scope for any scanner, stated as such
+//
+// `engine-gap` is the bucket that keeps this honest. It is the difference
+// between "we checked and it is fine" and "nobody checked", and it is reported
+// with the same prominence as a failure because to a reader relying on the
+// output they are the same thing.
+
+import { loadFramework, evaluateFramework } from './auditor-walkthrough.js';
+import { statePath, safeWriteState } from './state-dir.js';
+
+export const PRIVACY_FRAMEWORK_ID = 'nist-privacy-1-1';
+
+/** Bucket names, in report order (worst first). */
+export const BUCKETS = Object.freeze(['gap', 'engine-gap', 'manual', 'satisfied']);
+
+/**
+ * Remediation per control family. Deliberately ACTIONABLE — a command or a
+ * concrete artifact — rather than a restatement of the control text, which is
+ * what a compliance report usually offers and what makes them ignorable.
+ *
+ * Keyed by the control-id prefix so a new control in an existing category
+ * inherits sensible guidance instead of silently getting none.
+ */
+const REMEDIATION = [
+  [/^PR\.DS-P1$/, 'Encrypt data at rest with an AEAD cipher. Replace ECB mode and static IVs; run `/fix --family crypto-weak-cipher` to apply the deterministic swaps.'],
+  [/^PR\.DS-P2$/, 'Enforce TLS 1.2+ and stop disabling certificate verification. `/fix --family crypto-tls-no-verify` patches the verify-off call sites.'],
+  [/^PR\.AA-P1$/, 'Remove hardcoded credentials and add authentication to unauthenticated routes. `/fix --rotate-secret` handles the secrets; auth gaps need a route-level decision.'],
+  [/^PR\.AA-P4$/, 'Sign and verify identity assertions with a modern algorithm — no `none` alg, no weak-hash HMAC.'],
+  [/^PR\.AA-05$/, 'Add object-level authorization on endpoints that read or mutate personal data. Review the IDOR and authz findings individually; these are not safely auto-patchable.'],
+  [/^PR\.PS-P1$/, 'Tighten IaC: drop privileged pod security contexts and over-permissive IAM policies.'],
+  [/^PR\.PS-P2$/, 'Upgrade dependencies carrying known advisories. `/fix --sca` proposes the version bumps.'],
+  [/^PR\.PS-P4$/, 'Resolve dependency-confusion exposure by pinning internal scopes to your private registry.'],
+  [/^PR\.IR-P1$/, 'Restrict network and cluster access — no cluster-admin bindings, no wildcard IAM.'],
+  [/^PR\.DS-P8$/, 'Record an SBOM snapshot per release so dependency substitution is detectable.'],
+  [/^CT\.DP-P/, 'Reduce what is observable: minimise PII reaching logs, responses, and third parties; de-identify where the data action does not need identity.'],
+  [/^CT\.DM-P6$/, 'Transmit over TLS with a standard, current cipher suite.'],
+  [/^CT\.DM-P9$/, 'Retain scan history and the MCP audit log so data-processing activity is reviewable.'],
+  [/^CT\.DM-P10$/, 'Keep fix history so the technical measures you applied are demonstrably tested, not asserted.'],
+  [/^CT\.PO-P/, 'Declare the policy in `.agentic-security/compliance.policy.yml` so it is verified on every scan rather than remembered.'],
+  [/^CM\.AW-P4$/, 'Preserve the audit log — it is the record of disclosure this control asks for.'],
+  [/^CM\.AW-P6$/, 'Keep SBOM snapshots and signed scan state so provenance and lineage survive review.'],
+  [/^ID\.IM-P/, 'Produce the inventory artifacts: run a scan so the SBOM, threat model, and PII field map exist and are current.'],
+  [/^ID\.RA-P3$/, 'Triage the PII-exposure findings — each is a problematic data action this control asks you to identify.'],
+  [/^ID\.BE-P3$/, 'Generate the threat model so priority systems and their requirements are recorded.'],
+  [/^GV\.PO-P2$/, 'Commit a compliance policy file so privacy expectations are enforced in CI, not just documented.'],
+];
+
+/** The remediation for a control, or null when none is defined. */
+export function remediationFor(controlId) {
+  for (const [re, text] of REMEDIATION) if (re.test(controlId)) return text;
+  return null;
+}
+
+/**
+ * Bucket one evaluated control.
+ *
+ * `evaluateFramework` returns 'present' | 'partial' | 'manual'. That vocabulary
+ * cannot distinguish "no mapping because it is a governance control" from "no
+ * mapping because we never built the check" — which is exactly the distinction
+ * that decides whether a reader should worry. `codeTestable` supplies it.
+ */
+export function bucketOf(result, { assessable = true } = {}) {
+  const c = result.control || {};
+  const mapped = Array.isArray(c.mapsTo) && c.mapsTo.length > 0;
+  if (mapped) {
+    // VACUOUS SATISFACTION GUARD. `evaluateFramework` clears a `family:`
+    // mapping when no findings of that family are open — which is also true of
+    // a scan that examined nothing at all. Without this, pointing the tool at
+    // an empty directory reports privacy controls as SATISFIED, on the strength
+    // of having looked at zero files. That is the same false assurance the
+    // manual bucket exists to prevent, arriving by a different route, and it
+    // was caught by this module's own test rather than in review.
+    if (!assessable) return 'engine-gap';
+    return result.status === 'present' ? 'satisfied' : 'gap';
+  }
+  return String(c.codeTestable || 'no').toLowerCase() === 'no' ? 'manual' : 'engine-gap';
+}
+
+/** Severity for a gap. Privacy controls are graded by what the gap exposes. */
+function severityFor(controlId) {
+  if (/^PR\.(DS|AA)/.test(controlId)) return 'high';   // encryption, identity, access
+  if (/^CT\.DP/.test(controlId)) return 'medium';      // data minimisation
+  return 'low';
+}
+
+/**
+ * Assess a scan against NIST Privacy Framework 1.1.
+ *
+ * Returns `{ frameworkId, controls[], summary, findings[] }`. Never throws:
+ * posture modules degrade to a null result rather than failing a scan.
+ */
+export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
+  const fw = loadFramework(scanRoot, PRIVACY_FRAMEWORK_ID);
+  if (!fw) return null;
+
+  let evaluation;
+  try { evaluation = evaluateFramework(scanRoot, fw, scan || {}); } catch { return null; }
+
+  // Did the scan actually examine anything? A clean signal from a run that read
+  // no files is not evidence — see the guard in bucketOf.
+  const filesScanned = Number(scan && (scan.filesScanned ?? scan._scanMeta?.filesScanned)) || 0;
+  const assessable = filesScanned > 0
+    || (Array.isArray(scan?.findings) && scan.findings.length > 0)
+    || (Array.isArray(scan?.components) && scan.components.length > 0);
+
+  const controls = [];
+  const findings = [];
+  const summary = { gap: 0, 'engine-gap': 0, manual: 0, satisfied: 0, total: 0 };
+
+  for (const r of evaluation) {
+    const c = r.control || {};
+    const bucket = bucketOf(r, { assessable });
+    summary[bucket] += 1;
+    summary.total += 1;
+
+    const row = {
+      id: c.id,
+      function: c.function || null,
+      category: c.category || null,
+      summary: c.summary || '',
+      codeTestable: c.codeTestable || 'no',
+      bucket,
+      observations: r.observations || [],
+    };
+    if (bucket === 'engine-gap') {
+      // Named, not counted as a pass. See the header.
+      row.disclosure = (Array.isArray(c.mapsTo) && c.mapsTo.length && !assessable)
+        ? 'This control is mapped, but the scan examined no files — a clean signal from a run that read nothing is not evidence. NOT assessed.'
+        : `NIST rates this control code-testable (${row.codeTestable}), but this engine has no signal for it. It was NOT assessed.`;
+    }
+    if (bucket === 'manual') {
+      row.disclosure = 'NIST rates this control not code-testable — it is a governance, policy, or process control and is outside any scanner\'s reach.';
+    }
+    controls.push(row);
+
+    if (bucket !== 'gap') continue;
+    const remediation = remediationFor(c.id)
+      || 'Review the observations for this control and close the underlying findings.';
+    findings.push({
+      id: `privacy-framework:${c.id}`,
+      severity: severityFor(c.id),
+      // A compliance gap is a property of the project, not of one line. The
+      // framework file is cited so the finding still has a real, openable
+      // location rather than a fabricated one.
+      file: '.agentic-security/compliance/nist-privacy-1-1',
+      line: 0,
+      vuln: `NIST Privacy Framework ${c.id} not satisfied — ${c.summary}`,
+      cwe: 'CWE-359',
+      description: [
+        `Control ${c.id} (${c.category || c.function || 'privacy'}) is mapped to engine signals that are currently failing.`,
+        ...(r.observations || []),
+      ].join(' '),
+      remediation,
+      parser: 'COMPLIANCE',
+      family: 'privacy-compliance',
+      complianceControl: { framework: PRIVACY_FRAMEWORK_ID, id: c.id, codeTestable: c.codeTestable || 'no' },
+    });
+  }
+
+  return {
+    frameworkId: PRIVACY_FRAMEWORK_ID,
+    frameworkName: fw.name,
+    controls,
+    summary,
+    findings,
+    // Carried in the result so a consumer cannot present the numbers without
+    // it. `satisfied` is a share of the ASSESSED controls, never of all 104.
+    assessable,
+    interpretation:
+      (!assessable ? 'The scan examined no files, so NO control was assessed. ' : '') +
+      `${summary.satisfied} of ${summary.satisfied + summary.gap} assessed controls satisfied. ` +
+      `${summary['engine-gap']} controls NIST rates code-testable were NOT assessed by this engine, and ` +
+      `${summary.manual} are governance controls outside any scanner's reach. ` +
+      'Neither group is evidence of compliance.',
+    ...(opts.includeFindings === false ? { findings: [] } : {}),
+  };
+}
+
+/**
+ * Render the assessment as Markdown, worst bucket first.
+ *
+ * Order is deliberate: gaps, then the controls nobody assessed, then governance,
+ * then satisfied. A report that opens with what passed invites the reader to
+ * stop there, which is precisely the wrong reading of a document where most
+ * controls carry no engine evidence at all.
+ */
+function renderPrivacyMarkdown(result) {
+  if (!result) return '';
+  const L = [];
+  L.push(`# ${result.frameworkName} — assessment`);
+  L.push('');
+  L.push(result.interpretation);
+  L.push('');
+  L.push('| Bucket | Controls | Meaning |');
+  L.push('| --- | --- | --- |');
+  L.push(`| Gap | ${result.summary.gap} | Mapped to an engine signal, and that signal is failing |`);
+  L.push(`| Not assessed | ${result.summary['engine-gap']} | Code-testable, but this engine has no signal — **not** a pass |`);
+  L.push(`| Manual | ${result.summary.manual} | Governance/policy control, outside any scanner's reach |`);
+  L.push(`| Satisfied | ${result.summary.satisfied} | Mapped, and the signal is clean |`);
+  L.push('');
+  L.push('> A control in *Not assessed* or *Manual* is not evidence of compliance.');
+  L.push('> This document organizes scanner evidence; it does not certify anything.');
+  L.push('> A licensed assessor is responsible for the attestation.');
+  L.push('');
+  for (const bucket of BUCKETS) {
+    const rows = result.controls.filter(c => c.bucket === bucket);
+    if (!rows.length) continue;
+    L.push(`## ${bucket} (${rows.length})`);
+    L.push('');
+    for (const c of rows) {
+      L.push(`### ${c.id} — ${c.summary}`);
+      L.push(`- NIST code-testable: **${c.codeTestable}**`);
+      if (c.disclosure) L.push(`- ${c.disclosure}`);
+      for (const o of c.observations || []) L.push(`- ${o}`);
+      const rem = bucket === 'gap' ? remediationFor(c.id) : null;
+      if (rem) L.push(`- **Remediation:** ${rem}`);
+      L.push('');
+    }
+  }
+  return L.join('\n');
+}
+
+/**
+ * Persist the assessment. Through the seam, so a read-only scan writes nothing
+ * while still RETURNING the assessment — the switch changes what is written,
+ * never what is reported.
+ */
+export function persistPrivacyFramework(scanRoot, result) {
+  if (!result) return null;
+  safeWriteState(statePath(scanRoot, 'privacy-framework.json'), JSON.stringify(result, null, 2));
+  safeWriteState(statePath(scanRoot, 'privacy-framework.md'), renderPrivacyMarkdown(result));
+  return result;
+}

package/src/posture/proof-artifact.js

@@ -0,0 +1,101 @@
+// Proof-artifact provenance (PRD Epic 1.4 + 7.4).
+//
+// An `execution-proven` finding is only worth more than a pattern match if a
+// reader can tell WHAT was proven and check that the claim was not edited after
+// the fact. This module turns the evidence a proof run produced into two things
+// a report can carry:
+//
+//   1. `proofLevel` — the PRD's public vocabulary, mapped from the engine's
+//      internal `proofTier`. The engine's names are about analysis provenance;
+//      the PRD's are about what a reader may conclude. They are deliberately
+//      NOT the same strings, and mapping in one place stops the two vocabularies
+//      drifting into each other across reporters.
+//
+//   2. `proofArtifactSha256` — a digest over the evidence that actually
+//      justified the tier: the PoC that ran, the effect observed, the backend it
+//      ran on, and the tier claimed. A fix PR can then reference the digest, and
+//      anyone re-running the proof can check they are looking at the same
+//      artifact rather than a later, friendlier one.
+//
+// WHAT THE DIGEST IS AND IS NOT. It is tamper-EVIDENCE over the proof record,
+// not proof the exploit is real — the execution is what does that. It is also
+// not a signature: it commits to content, and anyone can recompute it. Signing
+// belongs with `integrity.js`, which already has a key and a provenance story;
+// duplicating that here would be a second crypto path for no gain.
+//
+// Timestamps are deliberately excluded. Two runs that proved the same thing the
+// same way should produce the same digest, or the field cannot be used to say
+// "this is the artifact the PR was reviewed against".
+
+import crypto from 'node:crypto';
+
+// Engine tier -> PRD proof level. Every tier maps; an unknown tier maps to the
+// weakest level rather than being dropped, because a missing level would read
+// as "not applicable" instead of "we do not know".
+const TIER_TO_LEVEL = Object.freeze({
+  'execution-proven': 'PROVEN',
+  'proof-failed': 'PROBABLE_FP',
+  'taint-proven': 'REACHABLE',
+  'unproven': 'PATTERN',
+});
+
+export const PROOF_LEVELS = Object.freeze(['PROVEN', 'PROBABLE_FP', 'REACHABLE', 'PATTERN']);
+
+/**
+ * The PRD-facing proof level for a finding.
+ *
+ * Returns null when the finding carries no tier at all — a scan that never ran
+ * the proof stage must not have every finding labelled `PATTERN`, which would
+ * assert that each was considered and found unprovable.
+ */
+export function proofLevelOf(finding) {
+  const tier = finding?.proofTier;
+  if (!tier) return null;
+  return TIER_TO_LEVEL[tier] || 'PATTERN';
+}
+
+/**
+ * Digest over the evidence that justified the tier. Null when there is no
+ * evidence to commit to — an absent hash is honest; a hash over nothing is not.
+ */
+export function proofArtifactDigest(finding) {
+  const ev = finding?.proofEvidence;
+  if (!ev || !finding?.proofTier) return null;
+  // Only fields that constitute the CLAIM. `at` (a timestamp) and `exitCode`
+  // are excluded: they vary between identical proofs and would make the digest
+  // useless for "same artifact?" comparisons.
+  const material = JSON.stringify({
+    tier: finding.proofTier,
+    ran: ev.ran === true,
+    backend: ev.backend ?? null,
+    observed: ev.observed ?? null,
+    reason: ev.reason ?? null,
+    marker: finding.poc?.marker ?? null,
+    poc: finding.poc?.code ?? null,
+  });
+  return crypto.createHash('sha256').update(material).digest('hex');
+}
+
+/**
+ * The reportable proof block, or null when the finding has no proof standing.
+ * One shape, so every reporter says the same thing the same way.
+ */
+export function proofBlock(finding) {
+  const level = proofLevelOf(finding);
+  if (!level) return null;
+  const ev = finding?.proofEvidence || {};
+  return {
+    proofLevel: level,
+    proofTier: finding.proofTier,
+    proofRan: ev.ran === true,
+    ...(ev.backend ? { proofBackend: ev.backend } : {}),
+    ...(ev.observed ? { proofObserved: ev.observed } : {}),
+    // Carried on the weaker levels too: "the PoC ran and nothing happened" is a
+    // different statement from "no PoC was attempted", and the reason is what
+    // distinguishes them.
+    ...(ev.reason ? { proofReason: ev.reason } : {}),
+    ...(proofArtifactDigest(finding) ? { proofArtifactSha256: proofArtifactDigest(finding) } : {}),
+  };
+}
+
+export const _internals = { TIER_TO_LEVEL };

package/src/posture/prove-findings.js

@@ -42,13 +42,35 @@
 // enable this on untrusted code without accepting that.
 
 import { synthesizeInProcessPoc } from './poc-inprocess.js';
-import { proveFinding } from './execution-proof.js';
+import { proveFinding, DEFAULT_PROOF_TIMEOUT_MS } from './execution-proof.js';
 import { sandboxAvailable } from '../sandbox/index.js';
 
 const DEFAULT_MAX = 25;
 // Aggregate wall-clock across all candidates in one scan.
 const DEFAULT_TOTAL_BUDGET_MS = 120000;
 
+/**
+ * The file set materialised into the sandbox root for one PoC.
+ *
+ * `requires` names the vulnerable source (the PoC imports it). `extraFiles`
+ * carries support files a template needs that are NOT that source — the SQL
+ * class ships a recording driver stub as `node_modules/<driver>/index.js`.
+ *
+ * `requires` WINS on a collision. Otherwise a template could name the
+ * vulnerable file in `extraFiles` and replace the very code the PoC is
+ * supposed to exploit with content of its own choosing, and the run would
+ * prove a fact about the template.
+ */
+export function mergePocFiles(poc, content) {
+  const files = {};
+  for (const rel of poc?.requires || []) files[rel] = content;
+  for (const [rel, c] of Object.entries(poc?.extraFiles || {})) {
+    if (rel in files) continue;
+    if (typeof c === 'string') files[rel] = c;
+  }
+  return files;
+}
+
 export function proveEnabled(env = process.env) {
   return env.AGENTIC_SECURITY_PROVE === '1';
 }
@@ -60,7 +82,10 @@ export function proveEnabled(env = process.env) {
  * @returns {object} a summary suitable for surfacing on the scan
  */
 export async function annotateExecutionProofs(findings, {
-  fileContents = null, maxCandidates = DEFAULT_MAX, timeoutMs = 10000,
+  // Shares one ceiling with execution-proof.js so the two cannot drift; see the
+  // rationale on DEFAULT_PROOF_TIMEOUT_MS there. Bounded overall by
+  // maxCandidates, so a generous per-PoC budget cannot run away.
+  fileContents = null, maxCandidates = DEFAULT_MAX, timeoutMs = DEFAULT_PROOF_TIMEOUT_MS,
   totalBudgetMs = DEFAULT_TOTAL_BUDGET_MS, env = process.env, now = Date.now,
 } = {}) {
   const summary = {
@@ -112,8 +137,7 @@ export async function annotateExecutionProofs(findings, {
     summary.attempted++;
     // The PoC imports the vulnerable file, so it must exist in the sandbox
     // root alongside it.
-    const files = {};
-    for (const rel of c.poc.requires || []) files[rel] = c.content;
+    const files = mergePocFiles(c.poc, c.content);
     let proved;
     try {
       proved = await proveFinding({ ...c.finding, poc: c.poc }, { files, timeoutMs });

package/src/posture/risk-dollars.js

@@ -23,8 +23,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE = '.agentic-security';
 
+import { statePath } from './state-dir.js';
 // Base rates per family (annual probability of at-least-one exploit given
 // an exposed instance). Rough industry estimates; tune via config.
 const FAMILY_BASE_PROB = {
@@ -79,7 +79,7 @@ const REACH_DISCOUNT = {
 };
 
 function _loadConfig(scanRoot) {
-  const fp = path.join(scanRoot, STATE, 'risk-config.yml');
+  const fp = statePath(scanRoot, 'risk-config.yml');
   if (!fs.existsSync(fp)) return null;
   try {
     const body = fs.readFileSync(fp, 'utf8');

package/src/posture/router.js

@@ -17,6 +17,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { stateDir, statePath } from './state-dir.js';
 function readJson(fp) {
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
@@ -32,7 +33,7 @@ function ageHours(fp) {
 // history to say anything honest. (premortem: never invent a trend from one
 // data point.)
 export function computeScanTrend(scanRoot) {
-  const hist = readJson(path.join(scanRoot, '.agentic-security', 'scan-history.json'));
+  const hist = readJson(statePath(scanRoot, 'scan-history.json'));
   if (!Array.isArray(hist) || hist.length < 2) return {};
   const cur = hist[hist.length - 1];
   const prev = hist[hist.length - 2];
@@ -55,9 +56,9 @@ export function decide(opts) {
 }
 
 function baseDecision({ scanRoot, intent }) {
-  const stateDir = path.join(scanRoot, '.agentic-security');
-  const lastScan = readJson(path.join(stateDir, 'last-scan.json'));
-  const scanAge = ageHours(path.join(stateDir, 'last-scan.json'));
+  const stateDirPath = stateDir(scanRoot);
+  const lastScan = readJson(path.join(stateDirPath, 'last-scan.json'));
+  const scanAge = ageHours(path.join(stateDirPath, 'last-scan.json'));
 
   if (!lastScan) {
     return {

package/src/posture/ruleset-version.js

@@ -25,14 +25,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { SCANNER_VERSION } from './version.js';
 
+import { statePath } from './state-dir.js';
 // Tied to scanner/package.json via posture/version.js — they cannot diverge
 // (premortem 3R1.3).
 export const CURRENT_RULESET_VERSION = SCANNER_VERSION;
 
-const FILE = '.agentic-security/ruleset-version.json';
 
 export function readPinned(scanRoot) {
-  const fp = path.join(scanRoot || process.cwd(), FILE);
+  const fp = statePath(scanRoot || process.cwd(), 'ruleset-version.json');
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
   catch { return null; }

package/src/posture/runtime-correlation.js

@@ -35,12 +35,13 @@ import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { createReadStream } from 'node:fs';
 
+import { statePath } from './state-dir.js';
 const DEFAULT_TRACE_NAMES = ['runtime-trace.jsonl', 'runtime.jsonl', 'ebpf-trace.jsonl'];
 const DEFAULT_OBSERVATION_WINDOW_DAYS = 30;
 
 export async function loadTrace(scanRoot, opts = {}) {
   const explicit = opts.tracePath || process.env.AGENTIC_SECURITY_RUNTIME_TRACE_PATH;
-  const candidates = explicit ? [explicit] : DEFAULT_TRACE_NAMES.map(n => path.join(scanRoot, '.agentic-security', n));
+  const candidates = explicit ? [explicit] : DEFAULT_TRACE_NAMES.map(n => statePath(scanRoot, n));
   let chosen = null;
   for (const c of candidates) {
     if (fs.existsSync(c)) { chosen = c; break; }

package/src/posture/sbom-diff.js

@@ -21,6 +21,7 @@
 // module produces the diff on the next scan.
 
 import * as fs from 'node:fs';
+import { statePath, stateWritesEnabled } from './state-dir.js';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { execSync } from 'node:child_process';
@@ -28,7 +29,7 @@ import { execSync } from 'node:child_process';
 const HISTORY_DIR = 'sbom-history';
 
 function _historyDir(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', HISTORY_DIR);
+  return statePath(scanRoot, HISTORY_DIR);
 }
 
 function _gitHead(scanRoot) {
@@ -47,7 +48,11 @@ function _snapshotKey(component) {
  */
 export function persistSbom(scanRoot, components) {
   const dir = _historyDir(scanRoot);
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  // The mkdir is inside the switch too. Guarding only the write still left an
+  // empty `sbom-history/` in the scanned tree — invisible to `git status`,
+  // because git does not track empty directories, and therefore exactly the
+  // kind of mutation that passes a clean-status check while still being one.
+  if (stateWritesEnabled()) { try { fs.mkdirSync(dir, { recursive: true }); } catch {} }
   const sha = _gitHead(scanRoot) || crypto.createHash('sha256').update(JSON.stringify(components)).digest('hex').slice(0, 12);
   const snap = {
     sha, ts: new Date().toISOString(),
@@ -58,7 +63,11 @@ export function persistSbom(scanRoot, components) {
       sha256: c.sha256 || c.integrity || null,
     })),
   };
-  try { fs.writeFileSync(path.join(dir, `${sha}.json`), JSON.stringify(snap, null, 2)); } catch {}
+  // NON_MUTATING_SCAN_PRD S1 — history is a feature, but not at the cost of
+  // mutating a tree the caller only asked us to read.
+  if (stateWritesEnabled()) {
+    try { fs.writeFileSync(path.join(dir, `${sha}.json`), JSON.stringify(snap, null, 2)); } catch {}
+  }
   return snap;
 }
 

package/src/posture/sca-policy.js

@@ -40,6 +40,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 
+import { safeWriteState, stateDir, statePath } from './state-dir.js';
 const DEFAULT_POLICY = {
   acceptRisk: [],
   sla: {},
@@ -49,7 +50,7 @@ const DEFAULT_POLICY = {
 export function loadScaPolicy(scanRoot) {
   if (!scanRoot) return null;
   for (const name of ['sca-policy.yml', 'sca-policy.yaml', 'sca-policy.json']) {
-    const p = path.join(scanRoot, '.agentic-security', name);
+    const p = statePath(scanRoot, name);
     if (!fs.existsSync(p)) continue;
     try {
       const raw = fs.readFileSync(p, 'utf8');
@@ -183,7 +184,7 @@ export function applyScaPolicy(findings, policy, scanTime = new Date()) {
 // If the policy file doesn't exist, one is created with safe defaults.
 export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
   if (!scanRoot || !finding) return { ok: false, reason: 'missing arguments' };
-  const dir = path.join(scanRoot, '.agentic-security');
+  const dir = stateDir(scanRoot);
   const fp = path.join(dir, 'sca-policy.yml');
   let policy = loadScaPolicy(scanRoot);
   if (policy && policy._error) return { ok: false, reason: policy._error };
@@ -209,7 +210,6 @@ export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
   };
   policy.acceptRisk.push(newEntry);
 
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   const serialized = yaml.dump({
     'accept-risk': policy.acceptRisk.map(e => {
       const o = {};
@@ -224,7 +224,10 @@ export function appendAcceptRiskFromTriage(scanRoot, finding, reason) {
     sla: policy.sla && Object.keys(policy.sla).length ? Object.fromEntries(Object.entries(policy.sla).map(([k, v]) => [k, _formatSlaDuration(v)])) : undefined,
     'major-version-freeze': policy.majorVersionFreeze && Object.keys(policy.majorVersionFreeze).length ? policy.majorVersionFreeze : undefined,
   });
-  fs.writeFileSync(fp, serialized);
+  // Through the seam. This one is user-initiated (a triage decision), so a
+  // refusal is reported rather than swallowed: silently not recording an
+  // accepted risk would be worse than failing loudly. (PRD M1)
+  if (!safeWriteState(fp, serialized)) return { ok: false, reason: 'state writes disabled or path outside a project root', path: fp };
   return { ok: true, entry: newEntry, path: fp };
 }
 

package/src/posture/scan-checkpoint.js

@@ -43,6 +43,15 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
+import { stateWritesEnabled } from './state-dir.js';
+
+// DELIBERATELY NOT routed through statePath(). `resolveProjectRoot()` falls
+// back to walking upward from process.cwd() when the given root does not exist
+// on disk, so `checkpointPath('/some/root')` resolved into the SCANNER'S OWN
+// SOURCE TREE — caught by the test that asserts a checkpoint is never written
+// there. A checkpoint must land in the root it was handed or nowhere; silently
+// relocating it into another directory is the exact failure this line of work
+// exists to prevent. The read-only switch above is still honoured.
 const STATE_DIR = '.agentic-security';
 const FILE_NAME = 'scan-checkpoint.jsonl';
 const FORMAT = 'agentic-security-scan-checkpoint/1';
@@ -191,6 +200,12 @@ function _recover(handle, file, runKey) {
  */
 export function openCheckpoint(scanRoot, { runKey } = {}) {
   if (!scanRoot || !runKey) return _emptyHandle('no-run-key');
+  // A read-only scan cannot checkpoint, and must not try. Resume is purely an
+  // optimisation — without it the scan recomputes, which is slower and
+  // identical — so `--no-state` wins over `AGENTIC_SECURITY_RESUME=1` rather
+  // than the two conflicting. The disabled handle no-ops through the rest of
+  // the API, so no caller needs a new branch. (PRD M1)
+  if (!stateWritesEnabled()) return _emptyHandle('state-writes-disabled');
   const handle = _emptyHandle(null);
   try {
     const dir = path.join(scanRoot, STATE_DIR);