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

package/src/posture/license-policy.js

@@ -16,6 +16,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 
+import { statePath } from './state-dir.js';
 const DEFAULT_POLICY = {
   allow: [],
   deny: [],
@@ -26,7 +27,7 @@ const DEFAULT_POLICY = {
 export function loadLicensePolicy(scanRoot) {
   if (!scanRoot) return null;
   for (const name of ['license-policy.yml', 'license-policy.yaml', 'license-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');

package/src/posture/model-rescan.js

@@ -15,10 +15,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE = '.agentic-security';
+import { statePath, stateWritesEnabled } from './state-dir.js';
 
 function _readJson(scanRoot, name) {
-  try { return JSON.parse(fs.readFileSync(path.join(scanRoot, STATE, name), 'utf8')); } catch { return null; }
+  try { return JSON.parse(fs.readFileSync(statePath(scanRoot, name), 'utf8')); } catch { return null; }
 }
 
 /**
@@ -50,7 +50,8 @@ export function diffValidatorRuns(runA, runB) {
  * Persist a model-rescan report. Returns the file path.
  */
 export function persistRescanReport(scanRoot, from, to, changed) {
-  const dir = path.join(scanRoot, STATE, 'model-rescan');
+  const dir = statePath(scanRoot, 'model-rescan');
+  if (!stateWritesEnabled()) return null;
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   const safe = (s) => String(s || 'unknown').replace(/[^\w.-]/g, '-');
   const fp = path.join(dir, `${safe(from)}-vs-${safe(to)}.json`);

package/src/posture/network-policy-import.js

@@ -27,7 +27,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const CANDIDATE_DIGEST = '.agentic-security/network-policy.json';
+
+import { statePath } from './state-dir.js';
 const K8S_DIRS = ['k8s', 'infra/k8s', 'deploy/k8s', 'kubernetes', 'manifests'];
 
 const INTERNAL_CIDRS = [
@@ -81,7 +82,7 @@ function parseKubeManifests(scanRoot) {
 
 export function loadNetworkPosture(scanRoot) {
   const root = scanRoot || process.cwd();
-  const digestPath = path.join(root, CANDIDATE_DIGEST);
+  const digestPath = statePath(root, 'network-policy.json');
   if (fs.existsSync(digestPath)) {
     try {
       const data = JSON.parse(fs.readFileSync(digestPath, 'utf8'));

package/src/posture/pqc-migration-plan.js

@@ -18,8 +18,7 @@
 // suggestions; JSON-LD-shaped structured output is consumable by Vanta /
 // Drata / SecureFrame or any custom rollup dashboard.
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
+import { statePath, safeWriteState } from './state-dir.js';
 
 function _byHndl(findings) {
   return {
@@ -117,9 +116,12 @@ export function buildMigrationPlan(allFindings) {
 
 export function persistMigrationPlan(scanRoot, plan) {
   if (!plan) return null;
-  try { fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true }); } catch {}
-  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'pqc-migration-plan.json'), JSON.stringify(plan, null, 2)); } catch {}
-  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'pqc-migration-plan.md'), _markdown(plan)); } catch {}
+  // Through the seam: creates the directory, enforces the project-root check,
+  // and honours the read-only scan switch. The plan is still RETURNED when
+  // writing is off — a scan must report the same result whether or not it is
+  // allowed to leave files behind.
+  safeWriteState(statePath(scanRoot, 'pqc-migration-plan.json'), JSON.stringify(plan, null, 2));
+  safeWriteState(statePath(scanRoot, 'pqc-migration-plan.md'), _markdown(plan));
   return plan;
 }
 

package/src/posture/pr-augment.js

@@ -18,6 +18,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { diffScans, summarizeDiff } from './baseline-compare.js';
 
+import { statePath, safeWriteState } from './state-dir.js';
 const REVIEWER_TRIGGERS = [
   { family: /^auth/,                team: 'security', why: 'Auth-related findings' },
   { family: /^crypto/,              team: 'security', why: 'Cryptography findings' },
@@ -29,7 +30,7 @@ const REVIEWER_TRIGGERS = [
 ];
 
 function _stateFile(scanRoot, name) {
-  return path.join(scanRoot, '.agentic-security', name);
+  return statePath(scanRoot, name);
 }
 
 function _readJson(fp) {
@@ -38,7 +39,7 @@ function _readJson(fp) {
 
 function _baselinePath(scanRoot, ref) {
   const safe = String(ref || 'main').replace(/[^\w.-]/g, '-');
-  return path.join(scanRoot, '.agentic-security', 'scan-baselines', `${safe}.json`);
+  return statePath(scanRoot, 'scan-baselines', `${safe}.json`);
 }
 
 /**
@@ -47,8 +48,10 @@ function _baselinePath(scanRoot, ref) {
  */
 export function persistBaseline(scanRoot, ref, scan) {
   const fp = _baselinePath(scanRoot, ref);
-  try { fs.mkdirSync(path.dirname(fp), { recursive: true }); } catch {}
-  try { fs.writeFileSync(fp, JSON.stringify({ ref, ts: new Date().toISOString(), findings: scan.findings || [] }, null, 2)); } catch {}
+  // safeWriteState creates the directory, enforces the project-root check, and
+  // honours the read-only switch. The path is still returned either way, so
+  // callers that only report where the baseline WOULD live are unaffected.
+  safeWriteState(fp, JSON.stringify({ ref, ts: new Date().toISOString(), findings: scan.findings || [] }, null, 2));
   return fp;
 }
 
@@ -109,7 +112,7 @@ function _artifactLinks(scanRoot) {
   ];
   const out = [];
   for (const c of candidates) {
-    const fp = path.join(scanRoot, '.agentic-security', c.file);
+    const fp = statePath(scanRoot, c.file);
     if (fs.existsSync(fp)) out.push({ name: c.name, path: `.agentic-security/${c.file}` });
   }
   return out;

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/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);

package/src/posture/state-dir.js

@@ -111,9 +111,42 @@ export function isSafeStateDir(dir) {
   return false;
 }
 
+// --- Read-only scanning (NON_MUTATING_SCAN_PRD S1) ---------------------------
+//
+// A scan is an OBSERVATION. Pointing the engine at a directory should not
+// change it. Until this switch existed, `scan .` wrote seven-plus files into the
+// scanned tree, which breaks CI that asserts a clean worktree, leaves artefacts
+// in third-party code the user does not own, and — measured on this project's
+// own benchmark — let a second scan read the first scan's conclusions as source.
+//
+// This is deliberately a KILL SWITCH AT THE SEAM rather than a parameter
+// threaded through 72 call sites. Threading it would mean 72 chances to forget,
+// and the module this lives in exists precisely because that kind of
+// per-caller discipline already failed once: its header records a user who
+// uninstalled the plugin after stray state directories broke their build.
+let _stateWritesEnabled = true;
+
+/** Turn all state writing off (or back on) for this process. */
+export function setStateWritesEnabled(enabled) {
+  _stateWritesEnabled = Boolean(enabled);
+}
+
+/**
+ * False when writing is disabled by the CLI flag or the environment.
+ *
+ * The env var is read at CALL time, not captured at import, so a test or a
+ * caller can set it after the module is loaded — the same mistake that made the
+ * gate verdict cache silently never engage.
+ */
+export function stateWritesEnabled() {
+  if (process.env.AGENTIC_SECURITY_NO_STATE === '1') return false;
+  return _stateWritesEnabled;
+}
+
 // Safe mkdir: only creates .agentic-security/ if the parent has a project marker.
 // Returns the dir on success, null if refused. Logs a warning when refused.
 export function ensureStateDir(scanRoot) {
+  if (!stateWritesEnabled()) return null;
   const dir = stateDir(scanRoot);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {
@@ -132,6 +165,7 @@ export function ensureStateDir(scanRoot) {
 // Safe write: only writes if isSafeStateDir(parent) returns true.
 // Returns true on success, false if refused or errored.
 export function safeWriteState(filePath, content) {
+  if (!stateWritesEnabled()) return false;
   const dir = path.dirname(filePath);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {