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

package/bin/agentic-security.js

@@ -30,6 +30,7 @@ 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 +66,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/,
@@ -290,20 +298,23 @@ function _bundleSha() {
 }
 
 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`);
+  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'),
+    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 +336,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.
@@ -430,7 +446,7 @@ async function cmdScan(args) {
   }
 
   // --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));
@@ -646,10 +662,10 @@ 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 { isSafeStateDir: _isSafeStateDir, stateWritesEnabled: _writesOnScan } = await import('../src/posture/state-dir.js');
+  const stateDirPath = stateDir(path.resolve(target));
+  if (_writesOnScan() && _isSafeStateDir(stateDirPath)) {
+    await fsp.mkdir(stateDirPath, { recursive: true });
     const 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
@@ -660,7 +676,7 @@ async function cmdScan(args) {
         const { stampFindingTimestamps, buildBaselineMap, renderSlaSummary } = await import('../src/posture/mttr.js');
         let baselineMap = new Map();
         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);
         } catch { /* first run — empty baseline, everything is firstSeen now */ }
         const now = Date.now();
@@ -709,18 +725,18 @@ 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).
   try {
-    const streak = recordScan(stateDir, persistedScan);
+    const streak = recordScan(stateDirPath, persistedScan);
     // Print celebration / streak line to stderr so it doesn't pollute --format json
     if (process.stderr.isTTY && format !== 'json' && format !== 'sarif') {
       const delta = formatGradeDelta(streak);
@@ -799,18 +815,18 @@ async function cmdCi(args) {
   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`);
+  const stateDirPath = stateDir(targetAbs);
+  const { isSafeStateDir: _isSafeCi, stateWritesEnabled: _writesOnCi } = await import('../src/posture/state-dir.js');
+  if (!_writesOnCi() || !_isSafeCi(stateDirPath)) {
+    if (process.env.AGENTIC_SECURITY_DEBUG === '1') process.stderr.write(`[agentic-security] refusing to write CI artifacts at ${stateDirPath} — no project marker\n`);
     return;
   }
-  await fsp.mkdir(stateDir, { recursive: true });
-  await fsp.writeFile(path.join(stateDir, 'findings.json'),
+  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(stateDir, 'findings.sarif'),
+  await fsp.writeFile(path.join(stateDirPath, 'findings.sarif'),
     JSON.stringify(toSARIF(scan, meta), null, 2));
-  await fsp.writeFile(path.join(stateDir, 'findings.junit.xml'),
+  await fsp.writeFile(path.join(stateDirPath, 'findings.junit.xml'),
     toJUnit(scan, meta));
 
   const scanCode = exitCodeFor(scan);
@@ -872,7 +888,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 +946,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 +1272,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 +1335,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 +1437,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 +1464,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 +1484,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 });
@@ -1485,6 +1501,294 @@ async function cmdReset(args) {
 // FR-LEARN-6: read triage-feedback.json, group repeated FP verdicts by
 // (family, dir prefix), and propose a suppression YAML when ≥ threshold
 // (default 5) verdicts cluster. Writes to .agentic-security/rules-proposed/.
+// Languages the Layer-1 IR parses. Anything else cannot be partitioned into a
+// call-graph focus area, so feeding it to a hunter would spend tokens on files
+// the confirmation gate can never corroborate.
+const HUNT_EXTS = /\.(?:js|jsx|mjs|cjs|ts|tsx|py|java|cs|kt|go|php|rb)$/i;
+const HUNT_IGNORE = ['node_modules/**', '.git/**', 'dist/**', 'build/**', 'vendor/**', '**/.agentic-security/**'];
+const HUNT_MAX_FILES = 2000;
+
+async function cmdHunt(args) {
+  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');
+  const { LENSES } = await import('../src/discovery/lenses.js');
+
+  const rels = (await listFiles(scanRoot, { ignore: HUNT_IGNORE })).filter(f => HUNT_EXTS.test(f));
+  if (rels.length > HUNT_MAX_FILES) {
+    console.error(`agentic-security: ${rels.length} source files exceeds the ${HUNT_MAX_FILES}-file hunt cap.`);
+    console.error('Narrow the scope with --root <subdir>. Discovery is token-expensive and');
+    console.error('unbounded fan-out on a large repository is the wrong default.');
+    return 2;
+  }
+
+  const fileContents = {};
+  for (const rel of rels) {
+    try { fileContents[rel] = fs.readFileSync(path.join(scanRoot, rel), 'utf8'); } catch { /* unreadable — skip */ }
+  }
+
+  const { perFile, callGraph } = buildProjectIR(fileContents);
+
+  // 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(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: 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('');
+
+  if (report.fresh.length === 0) {
+    console.log('No new candidates survived confirmation and refutation.');
+  } else {
+    console.log(`${report.fresh.length} new candidate finding(s):`);
+    for (const f of report.fresh) {
+      console.log(`  [${f.severity}] ${f.file}:${f.line}  ${f.vuln}`);
+      console.log(`      lens=${f.discovery.lens} confirmation=${f.discovery.confirmation?.tier || 'unknown'}`);
+    }
+  }
+  if (report.duplicates.length || report.suppressed.length || report.refutedCandidates.length) {
+    console.log('');
+    console.log(`  (${report.duplicates.length} already known, ${report.suppressed.length} previously marked false positive, ` +
+      `${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) {
+    console.log('');
+    console.log('Coverage gaps:');
+    for (const r of c.reasons) console.log(`  · ${r}`);
+  }
+  if (report.runs.length && c.degradedRuns === report.runs.length) {
+    console.log('');
+    console.log('EVERY hunter run degraded — this result says nothing about the code.');
+    console.log('Set AGENTIC_SECURITY_LLM_ENDPOINT to enable discovery.');
+  }
+
+  // Advisory by design: discovery never gates. Exit 0 unless the scope was bad.
+  console.log('');
+  console.log(`Lenses available: ${LENSES.map(l => l.key).join(', ')}  (--lens a,b to narrow)`);
+  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;
+}
+
+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> [--public-key <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 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');
@@ -1521,7 +1825,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');
@@ -1549,7 +1853,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');
@@ -1777,6 +2081,10 @@ async function main() {
       case 'validator-cache': process.exit(await cmdValidatorCache(args));
       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));
@@ -1799,7 +2107,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));

package/dist/113.index.js

@@ -52,7 +52,6 @@ export const modules = {
 
 
 
-const STATE_DIR = '.agentic-security';
 const LOG_FILE = 'fix-metrics.jsonl';
 
 // Below this many samples a percentile is an artifact of the sample, not a
@@ -65,7 +64,7 @@ const RELIABLE_N = 10;
 const FIX_STAGES = Object.freeze(['rescan', 'lint', 'tests', 'honesty', 'poc']);
 
 function _logPath(scanRoot) {
-  return node_path__WEBPACK_IMPORTED_MODULE_1__.join(scanRoot, STATE_DIR, LOG_FILE);
+  return (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__/* .statePath */ .BQ)(scanRoot, LOG_FILE);
 }
 
 /**
@@ -77,9 +76,10 @@ function _logPath(scanRoot) {
 function recordFixAttempt(scanRoot, record) {
   if (!scanRoot || !record || typeof record !== 'object') return false;
   try {
-    const dir = node_path__WEBPACK_IMPORTED_MODULE_1__.join(scanRoot, STATE_DIR);
+    const dir = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__/* .stateDir */ .Pn)(scanRoot);
     if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__.isSafeStateDir)(dir)) return false;
-    node_fs__WEBPACK_IMPORTED_MODULE_0__.mkdirSync(dir, { recursive: true });
+    if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__.stateWritesEnabled)()) return;
+  node_fs__WEBPACK_IMPORTED_MODULE_0__.mkdirSync(dir, { recursive: true });
     // One writeSync of one newline-terminated line: a concurrent reader sees
     // whole records or nothing, and a torn tail is dropped on read.
     node_fs__WEBPACK_IMPORTED_MODULE_0__.appendFileSync(_logPath(scanRoot), JSON.stringify(record) + '\n', 'utf8');
@@ -406,8 +406,8 @@ var external_node_child_process_ = __webpack_require__(1421);
 var external_node_fs_ = __webpack_require__(3024);
 // EXTERNAL MODULE: external "node:path"
 var external_node_path_ = __webpack_require__(6760);
-// EXTERNAL MODULE: ./src/engine.js + 600 modules
-var engine = __webpack_require__(5865);
+// EXTERNAL MODULE: ./src/engine.js + 499 modules
+var engine = __webpack_require__(2912);
 ;// CONCATENATED MODULE: ./src/posture/fix-honesty-gate.js
 // Deterministic honesty gates on fix / finding output (#7).
 //

package/dist/117.index.js

@@ -12,6 +12,7 @@ export const modules = {
 /* unused harmony exports badgeFromScanRoot, renderSvg, _internal */
 /* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3024);
 /* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6760);
+/* harmony import */ var _posture_state_dir_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(1174);
 // Live SVG badge generator (v0.72).
 //
 // Every repo can drop a badge in its README pulling from the latest scan:
@@ -42,6 +43,7 @@ export const modules = {
 
 
 
+
 const COLORS = {
   critical:    '#e05d44',  // red
   high:        '#fe7d37',  // orange
@@ -56,7 +58,7 @@ const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
 
 function _readLastScan(scanRoot) {
   if (!scanRoot) return null;
-  const fp = node_path__WEBPACK_IMPORTED_MODULE_1__.join(scanRoot, '.agentic-security', 'last-scan.json');
+  const fp = (0,_posture_state_dir_js__WEBPACK_IMPORTED_MODULE_2__/* .statePath */ .BQ)(scanRoot, 'last-scan.json');
   if (!node_fs__WEBPACK_IMPORTED_MODULE_0__.existsSync(fp)) return null;
   try { return JSON.parse(node_fs__WEBPACK_IMPORTED_MODULE_0__.readFileSync(fp, 'utf8')); }
   catch { return null; }

package/dist/178.index.js

@@ -13,7 +13,7 @@ export const modules = {
 /* harmony import */ var node_child_process__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(1421);
 /* harmony import */ var node_fs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(3024);
 /* harmony import */ var node_path__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(6760);
-/* harmony import */ var _engine_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(5865);
+/* harmony import */ var _engine_js__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(2912);
 // Time-travel + counterfactual scanning (v0.68).
 //
 // Two new modes that exploit the pure-input shape of runFullScan: