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

package/bin/agentic-security.js

@@ -14,7 +14,6 @@ import { toCycloneDX, toSPDX } from '../src/posture/sbom.js';
 import { toPBOM } from '../src/sast/pipeline.js';
 import { buildAIBOM, aibomToMarkdown } from '../src/posture/aibom.js';
 import { recordScan, formatStreakLine, formatGradeDelta } from '../src/posture/streak.js';
-import { ingestAndMerge } from '../src/sca/sarif-ingest.js';
 import { loadProfile, saveProfile, detectProfile, renderAttributionLine, ATTRIBUTION, ATTRIBUTION_URL } from '../src/posture/profile.js';
 import { applySuppressions, addSoftAcceptance, expiredSoftAcceptances } from '../src/posture/suppressions.js';
 import { applyOverrides, validateOverrides, suppressionReport, renderSuppressionSummary } from '../src/posture/rule-overrides.js';
@@ -28,8 +27,8 @@ import { syncTickets } from '../src/integrations/tickets.js';
 import { decide as decideNextAction, explain as explainDecision } from '../src/posture/router.js';
 import * as triage from '../src/posture/triage.js';
 import { buildSlackDigest, buildDiscordDigest, postWebhook, buildJiraIssue, buildPrComment, buildSiemEvent, loadIntegrationConfig } from '../src/integrations/index.js';
-import { globFiles } from '../src/util/glob.js';
 
+import { stateDir, statePath } from '../src/posture/state-dir.js';
 // last-scan.json integrity helpers — implementation in posture/integrity.js
 // so the MCP server tools can share verification.
 function _verifyLastScan(body, sigFile) {
@@ -65,6 +64,13 @@ Commands:
   verify [--finding <id>]      Re-run the verifier loop on last-scan findings (use --live --target <url> to execute PoCs)
   reset [--yes] [--keep ...]   Right-to-delete: wipe accumulated learned state under .agentic-security/ (preserves operator-authored config)
   rule-synth [--dry-run]       Auto-synthesise suppression rules from repeated FP verdicts (proposes — does not activate)
+  compliance [--privacy]       Assess the last scan against NIST Privacy Framework 1.1
+                               --list                 show bundled + BYO frameworks
+                               --walkthrough <id>     auditor narrative for any framework
+                               --gap                  only the failing controls
+                               --format cli|json|md   (default cli)
+                               --fail-on gap          exit 1 when a control is failing
+                               Reads .agentic-security/last-scan.json — run a scan first.
   version                      Print version
   banner [--full]              Print the Patch-the-frog mascot + brand lockup
   harness [path] [--include-home]   Multi-harness config audit: scans .claude/,
@@ -103,7 +109,6 @@ Options:
   --show-threat-model          Append the auto-derived STRIDE threat model summary
   --show-drift                 Append calibration-drift alarms (overconfidence detection)
   --sca-reachable-only         Only SCA findings where the vulnerable function is reachable
-  --ingest-sarif <glob>        Merge external SARIF into this scan
   --scorecard                  Enrich components with OSSF Scorecard scores
   --no-network                 Skip OSV/registry queries (offline mode)
   --pr [ref]                   Diff-aware: scan only files changed since ref (auto-detects PR base)
@@ -289,21 +294,24 @@ function _bundleSha() {
   return 'unavailable';
 }
 
-async function writeMachineOutput(targetAbs, scan, meta, profile) {
-  const stateDir = path.join(targetAbs, '.agentic-security');
-  const { isSafeStateDir: _isSafe } = await import('../src/posture/state-dir.js');
-  if (!_isSafe(stateDir)) {
-    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write machine output at ${stateDir} — no project marker\n`);
+async function writeMachineOutput(targetAbs, scan, meta, profile, args) {
+  const stateDirPath = stateDir(targetAbs);
+  const { isSafeStateDir: _isSafe, stateWritesEnabled: _writesOn } = await import('../src/posture/state-dir.js');
+  // Read-only scan (NON_MUTATING_SCAN_PRD S1). These writes bypass
+  // safeWriteState because they are async, so the switch is checked here — the
+  // same refusal path the project-root check already uses.
+  if (!_writesOn() || !_isSafe(stateDirPath)) {
+    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write machine output at ${stateDirPath} — no project marker\n`);
     return;
   }
-  await fsp.mkdir(stateDir, { recursive: true });
+  await fsp.mkdir(stateDirPath, { recursive: true });
   // Always JSON (used by /security-fix and /security-report).
-  await fsp.writeFile(path.join(stateDir, 'findings.json'),
+  await fsp.writeFile(path.join(stateDirPath, 'findings.json'),
     JSON.stringify(toJSON(scan, meta), null, 2));
-  if (profile.profile === 'pro' || profile.machineOutput) {
-    await fsp.writeFile(path.join(stateDir, 'findings.sarif'),
+  if (profile.profile === 'pro' || profile.machineOutput || (args && args.flags['machine-output'])) {
+    await fsp.writeFile(path.join(stateDirPath, 'findings.sarif'),
       JSON.stringify(toSARIF(scan, meta), null, 2));
-    await fsp.writeFile(path.join(stateDir, 'findings.csv'), toCSV(scan));
+    await fsp.writeFile(path.join(stateDirPath, 'findings.csv'), toCSV(scan));
   }
 }
 
@@ -325,6 +333,11 @@ function parseArgs(argv) {
 }
 
 async function cmdScan(args) {
+  // NON_MUTATING_SCAN_PRD S1 — a scan is an observation; --no-state makes it one.
+  if (args.flags['no-state']) {
+    const { setStateWritesEnabled } = await import('../src/posture/state-dir.js');
+    setStateWritesEnabled(false);
+  }
   const target = args._[1] || '.';
   const targetAbs = path.resolve(target);
   // Load persona profile (R1). Persona-aware defaults flow from here.
@@ -424,13 +437,20 @@ async function cmdScan(args) {
 
   const only = args.flags.only;
   if (only) {
+    // Four channels exist (scanner/CLAUDE.md): findings (SAST), secrets,
+    // supplyChain (SCA), logicVulns (business-logic). --only sast keeps
+    // logicVulns (business-logic is source analysis, part of the SAST
+    // pillar); --only sca/secrets must also clear it — it's neither SCA
+    // nor secrets, and normalizeFindings()/exitCodeFor() both fold it in,
+    // so leaving it meant a business-logic finding leaked into a
+    // single-pillar scan's output AND its exit code.
     if (only === 'sast') { scan.secrets = []; scan.supplyChain = []; }
-    if (only === 'sca')  { scan.findings = []; scan.secrets = []; }
-    if (only === 'secrets') { scan.findings = []; scan.supplyChain = []; }
+    if (only === 'sca')  { scan.findings = []; scan.secrets = []; scan.logicVulns = []; }
+    if (only === 'secrets') { scan.findings = []; scan.supplyChain = []; scan.logicVulns = []; }
   }
 
   // --set-baseline: save current findings as baseline for future --since-baseline filtering
-  const baselinePath = path.join(target || '.', '.agentic-security', 'baseline.json');
+  const baselinePath = statePath(target || '.', 'baseline.json');
   if (args.flags['set-baseline']) {
     const { normalizeFindings } = await import('../src/report/index.js');
     const baselineIds = new Set(normalizeFindings(scan).map(f => f.stableId || f.id));
@@ -478,18 +498,6 @@ async function cmdScan(args) {
   // 0.9.0 Feat-18: --scorecard flag enables OSSF Scorecard enrichment
   if (args.flags['scorecard']) process.env.AGENTIC_SECURITY_SCORECARD = '1';
 
-  // 0.7.0 Feat-7: --ingest-sarif <path-or-glob> merges SARIF from external tools (Semgrep,
-  // gitleaks, Bandit, Trivy, Checkov, etc.) into this scan's findings, deduping by
-  // fingerprint and tracking provenance via sources[].
-  if (args.flags['ingest-sarif']) {
-    const glob = args.flags['ingest-sarif'];
-    const paths = await globFiles(glob);
-    if (paths.length) {
-      const r = ingestAndMerge(scan, paths);
-      if (process.stderr.isTTY) process.stderr.write(`[ingest] merged ${r.merged} / added ${r.added} findings from ${paths.length} SARIF file(s)\n`);
-    }
-  }
-
   // 0.6.0 Feat-1: --sca-reachable-only filters to only SCA findings where the vulnerable
   // function was confirmed reachable from a route handler.
   if (args.flags['sca-reachable-only']) {
@@ -550,6 +558,31 @@ async function cmdScan(args) {
     try { await enrichWithEPSS(scan); } catch {}
   }
 
+  // Re-run risk-dollars now that both signals it needs are actually
+  // available: EPSS (just enriched above — engine.js's own call ran before
+  // this, so every finding's epssScore was still unset) and relevanceTier
+  // (posture/relevance.js runs last inside runScan/engine.js, so it's
+  // populated on `scan.findings` by the time we get here, but wasn't yet
+  // when engine.js's own annotateRiskDollars call ran mid-pipeline).
+  try {
+    const { annotateRiskDollars } = await import('../src/posture/risk-dollars.js');
+    annotateRiskDollars(targetAbs, scan.findings || []);
+  } catch {}
+
+  // Re-run composite risk for the same reason as annotateRiskDollars above:
+  // engine.js's mid-pipeline annotateCompositeRisk calls ran before
+  // enrichWithEPSS (just above) had a chance to set f.exploitedNow, so
+  // every finding's 'exploited-now-floor:75' boost was computed against a
+  // field that was always undefined at the time — an actively-exploited
+  // CVE (EPSS percentile >= 0.95) never got its compositeRisk score raised.
+  // annotateCompositeRisk is pure/idempotent (only sets compositeRisk*
+  // fields, reads everything else), so re-running it here is safe.
+  try {
+    const { annotateCompositeRisk } = await import('../src/posture/composite-risk.js');
+    annotateCompositeRisk(scan.findings || []);
+    annotateCompositeRisk(scan.supplyChain || []);
+  } catch {}
+
   // Blast-radius narrative — purely local, always safe to run.
   if (!args.flags['no-blast-radius']) {
     try { enrichWithBlastRadius(scan, targetAbs); } catch {}
@@ -606,7 +639,7 @@ async function cmdScan(args) {
   } catch { /* attestation is metadata; never fail a scan over it */ }
 
   // R2: Always emit machine-readable artifacts to .agentic-security/.
-  await writeMachineOutput(targetAbs, scan, meta, profile);
+  await writeMachineOutput(targetAbs, scan, meta, profile, args);
 
   const includeSuppressed = !!args.flags['include-suppressed'];
   let body;
@@ -646,34 +679,72 @@ async function cmdScan(args) {
   else process.stdout.write(body + '\n');
 
   // Persist last scan for /security-fix and /security-report
-  const { isSafeStateDir: _isSafeStateDir } = await import('../src/posture/state-dir.js');
-  const stateDir = path.join(path.resolve(target), '.agentic-security');
-  if (_isSafeStateDir(stateDir)) {
-    await fsp.mkdir(stateDir, { recursive: true });
-    const persistedScan = toJSON(scan, meta);
+  const { isSafeStateDir: _isSafeStateDir, stateWritesEnabled: _writesOnScan } = await import('../src/posture/state-dir.js');
+  const stateDirPath = stateDir(path.resolve(target));
+  // S7 (Stage-0 audit): declared here, not with `const` inside the `if`
+  // below — it used to be block-scoped there while recordScan() further
+  // down referenced it unconditionally, throwing a ReferenceError on every
+  // single scan (silently swallowed by that call's empty catch{}). streak.json
+  // — grades, streak days, achievements — never actually persisted through
+  // the real CLI as a result, reproduced live before this fix.
+  let persistedScan = null;
+  if (_writesOnScan() && _isSafeStateDir(stateDirPath)) {
+    await fsp.mkdir(stateDirPath, { recursive: true });
+    persistedScan = toJSON(scan, meta);
     // #10 — MTTR: stamp firstSeenAt/lastSeenAt/ageDays from the PREVIOUS scan so
     // every finding carries an age, SLA breaches can be surfaced, and the fix
     // loop can report time-to-clean. Best-effort; skipped under --deterministic
     // so deterministic state stays byte-identical run-to-run.
     if (!args.flags.deterministic) {
       try {
-        const { stampFindingTimestamps, buildBaselineMap, renderSlaSummary } = await import('../src/posture/mttr.js');
+        const { stampFindingTimestamps, buildBaselineMap, renderSlaSummary, fingerprintFinding, computeMTTR } = await import('../src/posture/mttr.js');
         let baselineMap = new Map();
+        let prevAll = [];
         try {
-          const prev = JSON.parse(await fsp.readFile(path.join(stateDir, 'last-scan.json'), 'utf8'));
+          const prev = JSON.parse(await fsp.readFile(path.join(stateDirPath, 'last-scan.json'), 'utf8'));
           baselineMap = buildBaselineMap(prev);
+          // The previous scan's own findings already carry firstSeenAt/lastSeenAt
+          // from ITS baseline lookup — exactly the shape computeMTTR needs for
+          // whichever of them are no longer present now (i.e. were fixed).
+          prevAll = [
+            ...(prev?.findings || []), ...(prev?.secrets || []),
+            ...(prev?.supplyChain || []).filter(s => s.type === 'vulnerable_dep'),
+          ];
         } catch { /* first run — empty baseline, everything is firstSeen now */ }
         const now = Date.now();
         stampFindingTimestamps(persistedScan.findings || [], baselineMap, now);
         stampFindingTimestamps(persistedScan.secrets || [], baselineMap, now);
         stampFindingTimestamps((persistedScan.supplyChain || []).filter(s => s.type === 'vulnerable_dep'), baselineMap, now);
+        // #10 — MTTR: which of the previous scan's findings are no longer
+        // present now (fixed), and how long each took. computeMTTR itself was
+        // fully built and tested but had never had a real caller — the module's
+        // own comment calls it "true MTTR," distinct from the open-backlog
+        // median-age proxy renderSlaSummary already surfaces below.
+        const currentFps = new Set([
+          ...(persistedScan.findings || []), ...(persistedScan.secrets || []),
+          ...(persistedScan.supplyChain || []).filter(s => s.type === 'vulnerable_dep'),
+        ].map(fingerprintFinding));
+        const removed = prevAll.filter(f => !currentFps.has(fingerprintFinding(f)));
+        persistedScan.mttr = computeMTTR(removed);
         // Surface the SLA-breach line on human-readable formats (not JSON/CI pipes).
         const isJson = format === 'json' || format === 'sarif' || format === 'cyclonedx' || format === 'sbom' || format === 'spdx' || format === 'vex' || format === 'openvex' || format === 'pbom' || format === 'aibom';
         if (!isJson) {
           const sla = renderSlaSummary(persistedScan.findings || []);
           if (sla) process.stderr.write(`⏰ agentic-security: ${sla}\n`);
+          if (persistedScan.mttr.count > 0) {
+            process.stderr.write(`✅ agentic-security: ${persistedScan.mttr.count} finding(s) fixed since last scan, median ${Math.round(persistedScan.mttr.medianDays)}d to remediate\n`);
+          }
+        }
+      } catch (e) {
+        // MTTR is best-effort — never block a scan write. But a silent catch
+        // here previously hid a real, deterministic CI-only failure (the
+        // mttr field went missing on every hosted-CI run, never locally, and
+        // nothing explained why) for long enough that it shipped several
+        // releases undiagnosed. Surface it — never fail the scan on it.
+        if (process.env.AGENTIC_SECURITY_MTTR_DEBUG === '1' || process.env.CI || process.env.GITHUB_ACTIONS) {
+          process.stderr.write(`agentic-security: MTTR computation failed (best-effort, scan unaffected): ${(e && e.stack) || e}\n`);
         }
-      } catch { /* MTTR is best-effort — never block a scan write */ }
+      }
 
       // R5 — report the observed time-to-validated-fix distribution from the
       // fix attempts recorded by `verifyFix`. This is measurement, not
@@ -709,20 +780,27 @@ async function cmdScan(args) {
       } catch { /* best-effort, offline-degrading — never block a scan */ }
     }
     const lastScanBody = JSON.stringify(persistedScan, null, 2);
-    await fsp.writeFile(path.join(stateDir, 'last-scan.json'), lastScanBody);
+    await fsp.writeFile(path.join(stateDirPath, 'last-scan.json'), lastScanBody);
     try {
-      await fsp.writeFile(path.join(stateDir, 'last-scan.json.sig'), _signLastScan(lastScanBody));
+      await fsp.writeFile(path.join(stateDirPath, 'last-scan.json.sig'), _signLastScan(lastScanBody));
     } catch { /* non-fatal — sig file is best-effort */ }
   } else {
-    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write state at ${stateDir} — no project marker in ${path.resolve(target)}\n`);
+    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write state at ${stateDirPath} — no project marker in ${path.resolve(target)}\n`);
   }
 
   // 0.14.0 — update streak / achievements after every full scan. Suppress
   // streak side effects when the user only wants raw JSON output (CI piping).
+  // Gated on `persistedScan !== null` (i.e. the same _writesOnScan() &&
+  // _isSafeStateDir() condition above) — recordScan()'s own isSafeStateDir
+  // check alone does not know about --no-state / AGENTIC_SECURITY_NO_STATE,
+  // so without this a "read-only, mutates nothing" scan would still write
+  // streak.json. This was accidentally masked before the persistedScan
+  // scoping fix (recordScan was never reached at all, for the wrong reason);
+  // fixing that reachability bug required adding this guard explicitly.
   try {
-    const streak = recordScan(stateDir, persistedScan);
+    const streak = persistedScan !== null ? recordScan(stateDirPath, persistedScan) : null;
     // Print celebration / streak line to stderr so it doesn't pollute --format json
-    if (process.stderr.isTTY && format !== 'json' && format !== 'sarif') {
+    if (streak && process.stderr.isTTY && format !== 'json' && format !== 'sarif') {
       const delta = formatGradeDelta(streak);
       const line = formatStreakLine(streak);
       if (delta) process.stderr.write('\n' + delta + '\n');
@@ -798,20 +876,48 @@ async function cmdCi(args) {
   const packNames = packArg ? (Array.isArray(packArg) ? packArg : String(packArg).split(',')) : [];
   if (packNames.length) Object.assign(scan, applyPacks(scan, packNames));
 
-  // Persist the three CI artifacts.
-  const stateDir = path.join(targetAbs, '.agentic-security');
-  const { isSafeStateDir: _isSafeCi } = await import('../src/posture/state-dir.js');
-  if (!_isSafeCi(stateDir)) {
-    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write CI artifacts at ${stateDir} — no project marker\n`);
-    return;
+  // R4 — same run attestation cmdScan attaches, computed here too so
+  // findings.json (the actual CI evidence artifact) carries the same
+  // tamper-evidence digest 'agentic-security scan' does, rather than
+  // always shipping attestation: null. Runs after every filter above, so
+  // it attests what actually ships. Metadata only — never fails the scan.
+  try {
+    const { computeRunAttestation } = await import('../src/posture/attestation.js');
+    const { keyProvenance } = await import('../src/posture/integrity.js');
+    const { effectiveVersion } = await import('../src/posture/ruleset-version.js');
+    scan.attestation = computeRunAttestation({
+      findings: normalizeFindings(scan),
+      engineVersion: PKG_VERSION,
+      rulesetVersion: effectiveVersion(targetAbs).version,
+      bundleSha: _bundleSha(),
+      root: targetAbs,
+      sign: true,
+    });
+    if (scan.attestation) scan.attestation.keyProvenance = keyProvenance();
+  } catch { /* attestation is metadata; never fail a scan over it */ }
+
+  // Persist the three CI artifacts — but a refusal to write must NEVER skip
+  // the --fail-on evaluation below. S1 (Stage-0 audit, 2026): this used to be
+  // a bare `return;` inside the write-guard, so `cmdCi` returned `undefined`
+  // and `process.exit(await cmdCi(args))` became `process.exit(undefined)`,
+  // which Node treats as exit 0 — a CI pipeline reading only $? would see a
+  // passing build whose findings were never evaluated against --fail-on at
+  // all. The write and the gate are orthogonal: "we couldn't persist
+  // artifacts" is not evidence about "the scan is clean."
+  const stateDirPath = stateDir(targetAbs);
+  const { isSafeStateDir: _isSafeCi, stateWritesEnabled: _writesOnCi } = await import('../src/posture/state-dir.js');
+  const _canWriteCi = _writesOnCi() && _isSafeCi(stateDirPath);
+  if (!_canWriteCi) {
+    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write CI artifacts at ${stateDirPath} — no project marker\n`);
+  } else {
+    await fsp.mkdir(stateDirPath, { recursive: true });
+    await fsp.writeFile(path.join(stateDirPath, 'findings.json'),
+      JSON.stringify(toJSON(scan, meta), null, 2));
+    await fsp.writeFile(path.join(stateDirPath, 'findings.sarif'),
+      JSON.stringify(toSARIF(scan, meta), null, 2));
+    await fsp.writeFile(path.join(stateDirPath, 'findings.junit.xml'),
+      toJUnit(scan, meta));
   }
-  await fsp.mkdir(stateDir, { recursive: true });
-  await fsp.writeFile(path.join(stateDir, 'findings.json'),
-    JSON.stringify(toJSON(scan, meta), null, 2));
-  await fsp.writeFile(path.join(stateDir, 'findings.sarif'),
-    JSON.stringify(toSARIF(scan, meta), null, 2));
-  await fsp.writeFile(path.join(stateDir, 'findings.junit.xml'),
-    toJUnit(scan, meta));
 
   const scanCode = exitCodeFor(scan);
   const findings = normalizeFindings(scan);
@@ -819,7 +925,9 @@ async function cmdCi(args) {
   for (const f of findings) sev[f.severity] = (sev[f.severity] || 0) + 1;
   process.stderr.write(
     `[ci] ${findings.length} findings — ${sev.critical} critical · ${sev.high} high · ${sev.medium} medium · ${sev.low} low\n` +
-    `[ci] artifacts: .agentic-security/findings.{json,sarif,junit.xml}\n` +
+    (_canWriteCi
+      ? `[ci] artifacts: .agentic-security/findings.{json,sarif,junit.xml}\n`
+      : `[ci] artifacts: NOT written (state writes refused — set AGENTIC_SECURITY_DEBUG=1 for the reason)\n`) +
     `[ci] fail-on=${failOn}  scan-exit=${scanCode}\n`
   );
   // FR-SDLC-9: when --policy <file.rego> is supplied, evaluate against the
@@ -872,7 +980,7 @@ async function cmdAccept(args) {
   const id = args.flags.finding;
   if (!id) { console.error('--finding <id> required'); return 4; }
   const reason = args.flags.reason || 'vibecoded for now';
-  const lastScanPath = path.join(target, '.agentic-security', 'findings.json');
+  const lastScanPath = statePath(target, 'findings.json');
   if (!fs.existsSync(lastScanPath)) { console.error('No prior scan found. Run `agentic-security scan` first.'); return 4; }
   const last = JSON.parse(await fsp.readFile(lastScanPath, 'utf8'));
   const f = (last.findings || []).find(x => x.id === id);
@@ -930,7 +1038,7 @@ async function cmdTriage(args) {
   }
   const sub = args._[1];
   // Sync first so list reflects the latest scan.
-  const lastScanPath = path.join(target, '.agentic-security', 'findings.json');
+  const lastScanPath = statePath(target, 'findings.json');
   if (fs.existsSync(lastScanPath)) {
     const last = JSON.parse(await fsp.readFile(lastScanPath, 'utf8'));
     triage.syncWithScan(target, last.findings || []);
@@ -1256,7 +1364,7 @@ async function cmdRule(args) {
 async function cmdValidatorCache(args) {
   const sub = args._[1] || 'help';
   const root = path.resolve(args._[2] || '.');
-  const cacheDir = path.join(root, '.agentic-security', 'llm-cache');
+  const cacheDir = statePath(root, 'llm-cache');
   if (!fs.existsSync(cacheDir)) {
     console.log(`No validator cache at ${cacheDir}`);
     return 0;
@@ -1319,7 +1427,7 @@ async function cmdValidatorCache(args) {
 // FR-VER-7 fail-closed: any error → cannot-verify, never silent drop.
 async function cmdVerify(args) {
   const scanRoot = path.resolve(args.flags.root || '.');
-  const lastScanPath = path.join(scanRoot, '.agentic-security', 'last-scan.json');
+  const lastScanPath = statePath(scanRoot, 'last-scan.json');
   if (!fs.existsSync(lastScanPath)) {
     console.error(`No prior scan found at ${lastScanPath}. Run \`agentic-security scan\` first.`);
     return 4;
@@ -1421,9 +1529,9 @@ async function cmdVerify(args) {
 // --yes to skip the confirmation prompt (for scripted use).
 async function cmdReset(args) {
   const scanRoot = path.resolve(args.flags.root || '.');
-  const stateDir = path.join(scanRoot, '.agentic-security');
-  if (!fs.existsSync(stateDir)) {
-    console.log(`No state to reset at ${stateDir}`);
+  const stateDirPath = stateDir(scanRoot);
+  if (!fs.existsSync(stateDirPath)) {
+    console.log(`No state to reset at ${stateDirPath}`);
     return 0;
   }
   const WIPE = new Set([
@@ -1448,17 +1556,17 @@ async function cmdReset(args) {
   ]);
   const keep = new Set((args.flags.keep || '').split(',').filter(Boolean));
   const targets = [];
-  for (const entry of await fsp.readdir(stateDir, { withFileTypes: true })) {
+  for (const entry of await fsp.readdir(stateDirPath, { withFileTypes: true })) {
     if (keep.has(entry.name)) continue;
     if (WIPE.has(entry.name) || WIPE_DIRS.has(entry.name)) {
       targets.push({ name: entry.name, dir: entry.isDirectory() });
     }
   }
   if (!targets.length) {
-    console.log(`Nothing to reset under ${stateDir}.`);
+    console.log(`Nothing to reset under ${stateDirPath}.`);
     return 0;
   }
-  console.log(`agentic-security reset — will remove from ${stateDir}:`);
+  console.log(`agentic-security reset — will remove from ${stateDirPath}:`);
   for (const t of targets) console.log(`  ${t.name}${t.dir ? '/' : ''}`);
   console.log('');
   console.log('Preserving operator-authored config: rules.yml, rules/, license-policy.yml, trusted-keys.json, ruleset-version.json');
@@ -1468,7 +1576,7 @@ async function cmdReset(args) {
     return 0;
   }
   for (const t of targets) {
-    const p = path.join(stateDir, t.name);
+    const p = path.join(stateDirPath, t.name);
     try {
       if (t.dir) await fsp.rm(p, { recursive: true, force: true });
       else await fsp.rm(p, { force: true });
@@ -1493,7 +1601,7 @@ const HUNT_IGNORE = ['node_modules/**', '.git/**', 'dist/**', 'build/**', 'vendo
 const HUNT_MAX_FILES = 2000;
 
 async function cmdHunt(args) {
-  const scanRoot = path.resolve(args.flags.root || args._[0] || '.');
+  const scanRoot = path.resolve(args.flags.root || args._[1] || '.');
   const { listFiles } = await import('../src/util/glob.js');
   const { buildProjectIR } = await import('../src/ir/index.js');
   const { runDiscovery } = await import('../src/discovery/index.js');
@@ -1517,19 +1625,43 @@ async function cmdHunt(args) {
   // Prior scan and triage verdicts feed the judge so a hunt does not re-report
   // what the rule engine already found or what a human already dismissed.
   let priorScan = null, triageFeedback = null;
-  try { priorScan = JSON.parse(fs.readFileSync(path.join(scanRoot, '.agentic-security', 'last-scan.json'), 'utf8')); } catch {}
-  try { triageFeedback = JSON.parse(fs.readFileSync(path.join(scanRoot, '.agentic-security', 'triage-feedback.json'), 'utf8')); } catch {}
+  try { priorScan = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8')); } catch {}
+  try { triageFeedback = JSON.parse(fs.readFileSync(statePath(scanRoot, 'triage-feedback.json'), 'utf8')); } catch {}
 
   const lenses = args.flags.lens ? String(args.flags.lens).split(',').map(s => s.trim()).filter(Boolean) : undefined;
+  const intFlag = (name) => (args.flags[name] ? parseInt(args.flags[name], 10) : undefined);
+  const numFlag = (name) => (args.flags[name] ? Number(args.flags[name]) : undefined);
   const report = await runDiscovery(
     { perFileIR: perFile, callGraph, fileContents, priorScan, triageFeedback },
-    { lenses, maxAreas: args.flags['max-areas'] ? parseInt(args.flags['max-areas'], 10) : undefined },
+    {
+      lenses,
+      maxAreas: intFlag('max-areas'),
+      // PRD Phase 0 / C3. Defaults live in discovery/index.js so the library is
+      // bounded even when driven by something other than this CLI.
+      maxLlmCalls: intFlag('max-llm-calls'),
+      maxWallMs: intFlag('max-wall-ms'),
+      maxCandidates: intFlag('max-candidates'),
+      maxCostUsd: numFlag('max-cost-usd'),
+      // PRD C4 — persist and consult cross-run memory.
+      scanRoot: args.flags['no-memory'] ? undefined : scanRoot,
+      // PRD C2 — a comma-separated endpoint list turns on consensus.
+      endpoints: args.flags.endpoints,
+      costPerCallUsd: numFlag('cost-per-call-usd'),
+    },
   );
 
   const c = report.coverage;
   console.log('');
   console.log(`Discovery — ${rels.length} file(s), ${c.areasPlanned} focus area(s), ${c.lensesPerArea} lens(es) each`);
   console.log(`  areas hunted: ${c.areasHunted}/${c.areasPlanned} (fully: ${c.areasFullyHunted})   degraded runs: ${c.degradedRuns}/${report.runs.length}`);
+  console.log(`  budget: ${c.llmCalls}/${c.maxLlmCalls} LLM calls${c.budgetExhausted ? '  ← EXHAUSTED, run is incomplete' : ''}` +
+    `${c.candidatesCapped ? `   ${c.candidatesCapped} candidate(s) capped` : ''}` +
+    `${c.callsPerFinding !== null && c.callsPerFinding !== undefined ? `   ${c.callsPerFinding} calls/finding` : ''}`);
+  if (c.priorRuns !== null && c.priorRuns !== undefined) {
+    console.log(`  memory: ${c.priorRuns} prior run(s)` +
+      `${c.rememberedRefutals ? `, ${c.rememberedRefutals} candidate(s) skipped as already refuted` : ''}`);
+    if (c.nextWave?.summary) console.log(`  next wave: ${c.nextWave.summary}`);
+  }
   console.log(`  confirmation: ${JSON.stringify(c.confirmedByTier)}   panels: ${c.panelsRun} (undecided ${c.undecidedPanels})`);
   console.log('');
 
@@ -1548,6 +1680,23 @@ async function cmdHunt(args) {
       `${report.refutedCandidates.length} refuted by the panel)`);
   }
 
+  // PRD C5 — variant analysis. A confirmed finding is rarely alone: the same
+  // root cause is usually copy-pasted, and the siblings often do not trip a
+  // rule. sweepRootCauses already does this with exact accounting for scan
+  // findings; discovery findings simply never reached it until now.
+  if (report.fresh.length && !args.flags['no-variants']) {
+    try {
+      const { sweepRootCauses, formatSweepLedger } = await import('../src/posture/root-cause-sweep.js');
+      const sweep = sweepRootCauses(report.fresh, fileContents, { confirmedOnly: false });
+      const ledger = formatSweepLedger(sweep);
+      if (ledger) {
+        console.log('');
+        console.log('Variant sweep (siblings of the findings above):');
+        console.log(`  ${ledger}`);
+      }
+    } catch { /* the sweep is additive; never let it sink the report */ }
+  }
+
   // Degradation is part of the output. A half-failed hunt must never read as a
   // clean one, so every reason is printed rather than summarised away.
   if (c.reasons.length) {
@@ -1567,6 +1716,228 @@ async function cmdHunt(args) {
   return 0;
 }
 
+// PRD D2 — emit signed, per-finding evidence bundles, and verify them.
+//
+// `attest` needs our private key. `verify-attestation` needs ONLY a public key,
+// which is the entire point: a buyer or auditor checks the artefact without ever
+// having had access to anything of ours.
+/**
+ * `compliance` — framework assessment from the CLI.
+ *
+ * Reads the LAST SCAN rather than running a new one. A compliance answer is a
+ * statement about a scan that happened, and silently re-scanning here would
+ * make the number depend on when you asked rather than on what was measured —
+ * the same class of confusion as a benchmark that mutates its own corpus. If
+ * there is no scan to read, this says so and exits non-zero instead of
+ * assessing an empty project, which would report controls as satisfied on the
+ * strength of having looked at nothing.
+ */
+async function cmdCompliance(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const fmt = String(args.flags.format || 'cli');
+  const {
+    assessPrivacyFramework, PRIVACY_FRAMEWORK_ID, BUCKETS,
+  } = await import('../src/posture/privacy-framework.js');
+  const { listFrameworks, loadFramework, evaluateFramework, renderWalkthrough } =
+    await import('../src/posture/auditor-walkthrough.js');
+
+  if (args.flags.list) {
+    const fws = listFrameworks(scanRoot);
+    if (fmt === 'json') { console.log(JSON.stringify(fws, null, 2)); return 0; }
+    for (const f of fws) console.log(`  ${f.id.padEnd(20)} ${f.name}  [${f.source}]`);
+    return 0;
+  }
+
+  let scan;
+  try { scan = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8')); }
+  catch {
+    console.error('No .agentic-security/last-scan.json — run `agentic-security scan .` first.');
+    console.error('Refusing to assess an unscanned project: every control would report as');
+    console.error('unassessed, which is correct but useless, and one flag away from looking clean.');
+    return 2;
+  }
+  // The engine records this two ways depending on the emit path; take either.
+  scan.filesScanned = scan._scanMeta?.filesScanned ?? scan.scanned?.files ?? 0;
+
+  const wt = args.flags.walkthrough;
+  if (wt && wt !== true) {
+    const fw = loadFramework(scanRoot, String(wt));
+    if (!fw) {
+      console.error(`Unknown framework "${wt}". Try --list.`);
+      return 2;
+    }
+    console.log(renderWalkthrough(fw, evaluateFramework(scanRoot, fw, scan), {}));
+    return 0;
+  }
+
+  // Default mode is --privacy: it is the only framework with a remediation
+  // layer, so it is the only one where a CLI exit code means anything.
+  const r = assessPrivacyFramework(scanRoot, scan);
+  if (!r) { console.error(`Framework ${PRIVACY_FRAMEWORK_ID} could not be loaded.`); return 2; }
+
+  const gapsOnly = !!args.flags.gap;
+  if (fmt === 'json') {
+    console.log(JSON.stringify(gapsOnly ? { ...r, controls: r.controls.filter(c => c.bucket === 'gap') } : r, null, 2));
+  } else if (fmt === 'md') {
+    console.log(fs.readFileSync(statePath(scanRoot, 'privacy-framework.md'), 'utf8'));
+  } else {
+    console.log(`\n${r.frameworkName}\n`);
+    console.log(`  ${r.interpretation}\n`);
+    for (const b of BUCKETS) {
+      const rows = r.controls.filter(c => c.bucket === b);
+      if (!rows.length || (gapsOnly && b !== 'gap')) continue;
+      console.log(`  ${b} (${rows.length})`);
+      for (const c of rows) {
+        console.log(`    ${c.id.padEnd(11)} ${c.summary.slice(0, 84)}`);
+        const f = r.findings.find(x => x.id === `privacy-framework:${c.id}`);
+        if (f) console.log(`                → ${f.remediation}`);
+      }
+      console.log('');
+    }
+    console.log('  A control that is "manual" or "engine-gap" is NOT evidence of compliance.');
+    console.log('  This organizes scanner evidence; a licensed assessor owns the attestation.\n');
+  }
+
+  // --fail-on gap is opt-in. A compliance opinion becomes a build failure only
+  // when someone asks for it; defaulting to non-zero would break every pipeline
+  // that adds this command to see the report.
+  if (args.flags['fail-on'] === 'gap' && r.summary.gap > 0) return 1;
+  return 0;
+}
+
+async function cmdAttest(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const {
+    ensureKeyPair, buildEvidenceBundle, signEvidenceBundle,
+  } = await import('../src/posture/evidence-bundle.js');
+
+  let scan;
+  try { scan = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8')); }
+  catch { console.error('No .agentic-security/last-scan.json — run a scan first.'); return 2; }
+
+  const findings = scan.findings || [];
+  const wanted = args.flags.id;
+  const subset = wanted ? findings.filter(f => f.id === wanted || f.stableId === wanted) : findings;
+  if (!subset.length) {
+    console.error(wanted ? `No finding matching "${wanted}".` : 'No findings to attest.');
+    return 2;
+  }
+
+  const kp = ensureKeyPair();
+  if (kp.created) console.error(`Generated a new signing key at ${kp.privateKey} (public: ${kp.publicKey}).`);
+
+  const outDir = statePath(scanRoot, 'attestations');
+  fs.mkdirSync(outDir, { recursive: true });
+  const meta = {
+    engineVersion: scan.engineVersion || null,
+    rulesetVersion: scan.rulesetVersion || null,
+    bundleSha: scan.bundleSha || null,
+    commit: scan.commit || null,
+  };
+
+  let n = 0;
+  for (const f of subset) {
+    const bundle = signEvidenceBundle(buildEvidenceBundle(f, meta), kp.privateKeyPem);
+    const name = `${(f.stableId || f.id || `finding-${n}`)}.json`.replace(/[^\w.-]/g, '_');
+    fs.writeFileSync(path.join(outDir, name), JSON.stringify(bundle, null, 2) + '\n');
+    n++;
+  }
+  console.log(`Signed ${n} evidence bundle(s) → ${path.relative(scanRoot, outDir)}/`);
+  console.log(`Public key (share this with whoever verifies): ${kp.publicKey}`);
+  console.log('');
+  console.log('A bundle proves its contents are unmodified since signing. It does NOT');
+  console.log('prove the finding is real — read evidence.proofTier for that.');
+  return 0;
+}
+
+// R4/D2 correctness follow-up: attestation.js ships TWO independent
+// verifiers — verifyEvidenceBundle (per-finding, Ed25519, self-contained —
+// only needs a public key) and verifyRunAttestation (whole-run, per-install
+// HMAC, NOT self-contained — needs the caller to also supply the finding
+// set to re-derive against). This CLI command only ever called the first;
+// the second had zero production callers anywhere in the repo (confirmed by
+// grep — only test/attestation.test.js called it). Auto-detect which
+// artifact was handed in and dispatch to the matching verifier instead of
+// silently misinterpreting a run-attestation as a (structurally different)
+// evidence bundle.
+function _asRunAttestation(obj) {
+  if (obj && typeof obj.digest === 'string' && obj.canonicalisation) return obj;
+  if (obj && obj.attestation && typeof obj.attestation.digest === 'string') return obj.attestation;
+  return null;
+}
+
+// Verifies a run attestation the ONLY way it can be verified: by re-deriving
+// the digest from a fresh scan and comparing. Unlike an evidence bundle
+// (self-contained, just needs a public key), a run attestation is a claim
+// about a FINDING SET, not a standalone signed blob — "does scanning this
+// codebase right now reproduce the exact digest an earlier run attested"
+// is the actual, meaningful question this command answers.
+async function cmdVerifyRunAttestation(attestation, args) {
+  const projectPath = path.resolve(args.flags.against || '.');
+  if (!fs.existsSync(projectPath)) {
+    console.error(`--against path does not exist: ${projectPath}`);
+    return 2;
+  }
+  console.log(`Re-scanning ${projectPath} to check it reproduces the attested digest...`);
+  const { runScan } = await import('../src/runScan.js');
+  const { normalizeFindings } = await import('../src/report/index.js');
+  const { effectiveVersion } = await import('../src/posture/ruleset-version.js');
+  const { verifyRunAttestation } = await import('../src/posture/attestation.js');
+  const { scan } = await runScan(projectPath);
+  const r = verifyRunAttestation(attestation, {
+    findings: normalizeFindings(scan),
+    engineVersion: PKG_VERSION,
+    rulesetVersion: effectiveVersion(projectPath).version,
+    bundleSha: _bundleSha(),
+    root: projectPath,
+  });
+  if (!r.ok) {
+    console.error(`✗ INVALID — ${r.reason}`);
+    return 1;
+  }
+  console.log('✓ VALID — a fresh scan of this project reproduces the attested digest exactly.');
+  console.log('');
+  console.log(`  digest:          ${attestation.digest}`);
+  console.log(`  findingCount:    ${attestation.findingCount}`);
+  console.log(`  proves:          ${attestation.proves}`);
+  console.log(`  does NOT prove:  ${attestation.doesNotProve}`);
+  return 0;
+}
+
+async function cmdVerifyAttestation(args) {
+  const { verifyEvidenceBundle, keyPaths } = await import('../src/posture/evidence-bundle.js');
+  // `args._[0]` is the command name itself — the same convention cmdScan uses.
+  const file = args.flags.bundle || args._[1];
+  if (!file) { console.error('Usage: agentic-security verify-attestation <bundle.json|last-scan.json> [--public-key <path>] [--against <project-path>]'); return 2; }
+
+  let bundle;
+  try { bundle = JSON.parse(fs.readFileSync(path.resolve(file), 'utf8')); }
+  catch (e) { console.error(`Could not read bundle: ${e.message}`); return 2; }
+
+  const runAttestation = _asRunAttestation(bundle);
+  if (runAttestation) return cmdVerifyRunAttestation(runAttestation, args);
+
+  const keyFile = args.flags['public-key'] || keyPaths().publicKey;
+  let publicKeyPem = null;
+  try { publicKeyPem = fs.readFileSync(path.resolve(keyFile), 'utf8'); }
+  catch { console.error(`Could not read public key at ${keyFile}. Pass --public-key <path>.`); return 2; }
+
+  const r = verifyEvidenceBundle(bundle, publicKeyPem);
+  if (!r.ok) {
+    console.error(`✗ INVALID — ${r.reason}`);
+    return 1;
+  }
+  const f = bundle.finding || {};
+  console.log('✓ VALID — the bundle is exactly what the signer attested.');
+  console.log('');
+  console.log(`  ${f.severity ? `[${f.severity}] ` : ''}${f.vuln || '(no title)'}  ${f.file || '?'}:${f.line ?? '?'}`);
+  console.log(`  cwe ${f.cwe || 'n/a'}   parser ${f.parser || 'n/a'}   proof tier ${bundle.evidence?.proofTier || 'n/a'}`);
+  console.log('');
+  console.log(`  proves:        ${bundle.proves}`);
+  console.log(`  does NOT prove: ${bundle.doesNotProve}`);
+  return 0;
+}
+
 async function cmdRuleSynth(args) {
   const scanRoot = path.resolve(args.flags.root || '.');
   const { synthesizeRules } = await import('../src/posture/rule-synthesis.js');
@@ -1603,7 +1974,7 @@ async function cmdPacks(args) {
 async function cmdDigest(args) {
   const target = path.resolve(args._[1] || '.');
   const profile = loadProfile(target);
-  const lastScanPath = path.join(target, '.agentic-security', 'findings.json');
+  const lastScanPath = statePath(target, 'findings.json');
   if (!fs.existsSync(lastScanPath)) { console.error('No prior scan found.'); return 4; }
   const last = JSON.parse(await fsp.readFile(lastScanPath, 'utf8'));
   const findings = (last.findings || []).filter(f => f.severity === 'critical' || f.severity === 'high');
@@ -1631,7 +2002,7 @@ async function cmdFix(args) {
   const isApply = !!args.flags.apply;
   const scanRoot = path.resolve(args.flags.root || '.');
   if (!id) { console.error('--finding <id> required'); return 4; }
-  const lastScanPath = path.join(scanRoot, '.agentic-security', 'last-scan.json');
+  const lastScanPath = statePath(scanRoot, 'last-scan.json');
   if (!fs.existsSync(lastScanPath)) { console.error('No prior scan found. Run `agentic-security scan` first.'); return 4; }
   const lastScanBody = await fsp.readFile(lastScanPath, 'utf8');
   const sigVerified = _verifyLastScan(lastScanBody, lastScanPath + '.sig');
@@ -1860,6 +2231,9 @@ async function main() {
       case 'verify':   process.exit(await cmdVerify(args));
       case 'reset':    process.exit(await cmdReset(args));
       case 'hunt':     process.exit(await cmdHunt(args));
+      case 'compliance': process.exit(await cmdCompliance(args));
+      case 'attest':   process.exit(await cmdAttest(args));
+      case 'verify-attestation': process.exit(await cmdVerifyAttestation(args));
       case 'rule-synth': process.exit(await cmdRuleSynth(args));
       case 'digest':   process.exit(await cmdDigest(args));
       case 'setup':    process.exit(await cmdSetup(args));
@@ -1882,7 +2256,7 @@ async function main() {
         const result = analyzeTranscript({ transcriptPath: args.flags.transcript, projectDir });
         if (result.ok) {
           try {
-            const dir = path.join(projectDir, '.agentic-security');
+            const dir = stateDir(projectDir);
             fs.mkdirSync(dir, { recursive: true });
             fs.writeFileSync(path.join(dir, 'cache-telemetry.json'),
               JSON.stringify({ updatedAt: new Date().toISOString(), metrics: result.metrics, leaks: result.leaks }, null, 2));