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

package/src/posture/license-attributions.js

@@ -11,8 +11,7 @@
 // The emitter is deterministic — sorts by ecosystem, name, version —
 // so commits don't churn between scans.
 
-import * as fs from 'node:fs';
-import * as path from 'node:path';
+import { statePath, safeWriteState } from './state-dir.js';
 
 function _sortKey(c) {
   return `${c.ecosystem || 'zz'}:${c.name || ''}:${c.version || ''}`;
@@ -83,11 +82,10 @@ export function generateAttributions(components, options) {
 
 export function persistAttributions(scanRoot, result) {
   if (!result || !result.markdown) return null;
-  try { fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true }); } catch {}
-  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'ATTRIBUTIONS.md'), result.markdown); } catch {}
-  if (result.notice) {
-    try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'NOTICE'), result.notice); } catch {}
-  }
+  // Through the seam — see the note in pqc-migration-plan.js. The result is
+  // still returned when writing is off; only the artifact is withheld.
+  safeWriteState(statePath(scanRoot, 'ATTRIBUTIONS.md'), result.markdown);
+  if (result.notice) safeWriteState(statePath(scanRoot, 'NOTICE'), result.notice);
   return result;
 }
 

package/src/posture/license-graph.js

@@ -37,6 +37,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 // ── License taxonomy ───────────────────────────────────────────────────────
 
 const LICENSE_FAMILIES = {
@@ -223,7 +224,7 @@ export function analyzeLicenseGraph(components, options) {
 
 export function loadLicenseGraphPolicy(scanRoot) {
   if (!scanRoot) return { distributionMode: DEFAULT_DIST_MODE };
-  const fp = path.join(scanRoot, '.agentic-security', 'license-policy.yml');
+  const fp = statePath(scanRoot, 'license-policy.yml');
   if (!fs.existsSync(fp)) return { distributionMode: DEFAULT_DIST_MODE };
   try {
     const raw = fs.readFileSync(fp, 'utf8');

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

package/src/posture/mttr.js

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

package/src/posture/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/poc-inprocess.js

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

package/src/posture/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/regression-test-gen.js

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