@clear-capabilities/agentic-security-scanner 0.143.0 → 0.145.0

package/src/posture/scan-checkpoint.js

@@ -18,22 +18,40 @@
 //   2. Only the per-file loop is checkpointed. Every cross-file pass and the
 //      whole annotation pipeline re-runs from scratch on resume, so nothing that
 //      depends on the global picture can be stale by construction.
-//   3. Invalidation is conservative to the point of being blunt. The run key
-//      covers the engine version, the ruleset version, the bundle SHA, a content
-//      hash of every file in the scan (which subsumes mtime), and the scanner's
-//      own environment switches. If any of it moved, the checkpoint is discarded
-//      and the scan starts clean. Redoing work is merely slow; resuming stale
-//      work is a correctness bug.
+//   3. Invalidation is split into a GLOBAL identity and a PER-FILE identity
+//      (assurance-hardening PRD FR-208 — "changed inputs invalidate only
+//      affected checkpoints and record the invalidation reason"). The engine
+//      version, ruleset version, bundle SHA, dependency-manifest contents, and
+//      the scanner's own environment switches form the GLOBAL key: any of them
+//      changing affects how EVERY file would be analysed (decision #2 above —
+//      cross-file/dependency-derived results aren't checkpointed per-file at
+//      all), so a global-key mismatch still discards the whole checkpoint,
+//      exactly as before. A single scanned file's own content is NOT part of
+//      the global key: only THAT file's record is invalidated when its content
+//      changes, because a single file's own per-file analysis result depends
+//      only on that file's content plus the (unchanged) global identity — the
+//      cross-file passes that COULD make it depend on other files always
+//      re-run from scratch per decision #2. This was a real, deliberate
+//      widening from the original "any change discards everything" design,
+//      not a relaxation of the correctness property: it only reuses a
+//      per-file result when nothing that result could possibly depend on has
+//      moved. Redoing work is merely slow; resuming stale work is a
+//      correctness bug, and that bar has not moved.
 //
 // CRASH SAFETY: append-and-fsync. The file is a JSONL log — one header line
-// pinning the run key, then one self-describing record per completed file,
-// each carrying a SHA-256 of its own payload. Every record is written with a
+// pinning the global key (plus a plaintext meta summary used only to explain a
+// mismatch, never to decide one), then one self-describing record per
+// completed file, each carrying a SHA-256 of its own payload AND a SHA-256 of
+// the source content it was computed from. Every record is written with a
 // single `writeSync` and immediately `fsyncSync`'d before the next file is
 // analysed, so a process killed at any instant leaves either a complete record
 // or a torn tail. On recovery we read forward while records verify and truncate
 // the file at the last byte offset that did, so a torn tail is discarded rather
 // than resumed into. Nothing is ever rewritten in place, so there is no window
-// in which the file is neither the old state nor the new one.
+// in which the file is neither the old state nor the new one. A record whose
+// OWN content hash no longer matches the current file is a separate, later
+// check from tamper/tear detection — it is structurally intact, so it is not
+// truncated away, just excluded from what gets replayed (see `_recover`).
 //
 // Everything here follows the posture convention of never throwing: a failure to
 // open, read or append degrades to "no checkpoint", which just means a full scan.
@@ -54,7 +72,12 @@ import { stateWritesEnabled } from './state-dir.js';
 // exists to prevent. The read-only switch above is still honoured.
 const STATE_DIR = '.agentic-security';
 const FILE_NAME = 'scan-checkpoint.jsonl';
-const FORMAT = 'agentic-security-scan-checkpoint/1';
+// Bumped from /1: the header now stores a GLOBAL-only key (FR-208) instead of
+// one that folds in every scanned file's content, plus a plaintext meta
+// summary. A /1 checkpoint on disk must never be half-interpreted under /2
+// semantics, so the format bump alone is enough to force a clean discard of
+// anything written before this change — the safest possible migration.
+const FORMAT = 'agentic-security-scan-checkpoint/2';
 
 // Env switches that change what the engine emits are part of the run identity.
 // These three are deliberately excluded: they change how the run is driven, not
@@ -92,6 +115,14 @@ export function bundleShaForRunKey() {
  * Everything that would invalidate previously-completed per-file work, reduced
  * to one hex digest. Content hashes rather than mtimes: strictly stronger, and
  * immune to filesystems with coarse or non-monotonic timestamps.
+ *
+ * Retained as its own function (still folding in `fileContents`) because it is
+ * a useful, independently-tested "did ANYTHING about this scan change"
+ * fingerprint, and because `computeGlobalKey` below is defined in terms of it
+ * (fileContents forced empty) — changing this function's hash would silently
+ * change that one too. Production checkpointing itself uses `computeGlobalKey`,
+ * not this function directly; see FR-208's note in the module header for why
+ * file content is no longer part of what invalidates the WHOLE checkpoint.
  */
 export function computeRunKey({
   engineVersion, rulesetVersion, bundleSha,
@@ -119,6 +150,50 @@ export function computeRunKey({
   return h.digest('hex');
 }
 
+/**
+ * FR-208: the GLOBAL portion of run identity — everything that would affect
+ * how EVERY scanned file is analysed. Deliberately excludes `fileContents`
+ * (a single file's own content is checked per-record in `_recover` instead)
+ * but keeps `depFileContents`: dependency-manifest-derived findings are not
+ * part of any per-file checkpoint record (they're recomputed fresh every run,
+ * same as cross-file taint — decision #2 in the module header), so there is
+ * no per-file granularity to offer there; any manifest change invalidates
+ * everything, same as before this change.
+ */
+export function computeGlobalKey({ engineVersion, rulesetVersion, bundleSha, depFileContents = {}, env = process.env } = {}) {
+  return computeRunKey({ engineVersion, rulesetVersion, bundleSha, fileContents: {}, depFileContents, env });
+}
+
+/**
+ * A plaintext (non-hashed) summary of the same inputs `computeGlobalKey` folds
+ * in, stored alongside the key in the checkpoint header. Used ONLY to explain
+ * a global-key mismatch after the fact (`_explainGlobalMismatch`) — never to
+ * decide whether one occurred; the key comparison remains the sole source of
+ * truth for that, so a caller cannot bypass invalidation by supplying
+ * mismatched meta.
+ */
+export function globalKeyMeta({ engineVersion, rulesetVersion, bundleSha, depFileContents = {}, env = process.env } = {}) {
+  return {
+    engineVersion: String(engineVersion ?? ''),
+    rulesetVersion: String(rulesetVersion ?? ''),
+    bundleSha: String(bundleSha ?? 'unavailable'),
+    depFingerprint: computeRunKey({ engineVersion: '', rulesetVersion: '', bundleSha: '', fileContents: {}, depFileContents, env: {} }),
+    envFingerprint: computeRunKey({ engineVersion: '', rulesetVersion: '', bundleSha: '', fileContents: {}, depFileContents: {}, env }),
+  };
+}
+
+function _explainGlobalMismatch(oldMeta, newMeta) {
+  oldMeta = oldMeta || {};
+  newMeta = newMeta || {};
+  const parts = [];
+  if (oldMeta.engineVersion !== newMeta.engineVersion) parts.push(`engine version changed (${oldMeta.engineVersion || 'unknown'} -> ${newMeta.engineVersion || 'unknown'})`);
+  if (oldMeta.rulesetVersion !== newMeta.rulesetVersion) parts.push(`ruleset version changed (${oldMeta.rulesetVersion || 'unknown'} -> ${newMeta.rulesetVersion || 'unknown'})`);
+  if (oldMeta.bundleSha !== newMeta.bundleSha) parts.push('the running bundle changed');
+  if (oldMeta.depFingerprint !== newMeta.depFingerprint) parts.push('a dependency manifest file changed');
+  if (oldMeta.envFingerprint !== newMeta.envFingerprint) parts.push('an AGENTIC_SECURITY_* environment switch changed');
+  return parts.length ? `global scan identity changed: ${parts.join(', ')}` : 'global scan identity changed';
+}
+
 // A value is safe to checkpoint only if JSON can carry it back unchanged. Dates,
 // regexes, Maps, Sets, functions and BigInts all survive `JSON.stringify` in a
 // lossy or throwing way; recording one would mean the resumed run sees different
@@ -150,28 +225,39 @@ function _jsonSafe(v, depth = 0, seen = new Set()) {
 
 function _emptyHandle(reason) {
   return {
-    enabled: false, file: null, fd: null, runKey: null,
+    enabled: false, file: null, fd: null, globalKey: null,
     recovered: new Map(), order: [], written: new Set(),
-    discarded: false, reason,
+    discarded: false, reason, invalidatedFiles: [], fileContents: {},
   };
 }
 
-function _headerLine(runKey) {
-  return JSON.stringify({ v: FORMAT, runKey }) + '\n';
+function _headerLine(globalKey, meta) {
+  return JSON.stringify({ v: FORMAT, gk: globalKey, meta: meta || {} }) + '\n';
 }
 
 // Read forward from a byte offset, keeping records while they verify. Returns
-// the offset of the first byte that did NOT verify, so the caller can truncate.
-function _recover(handle, file, runKey) {
+// {offset, discardReason}: offset is the byte position the caller should keep
+// (or truncate to); discardReason is set only when offset===0 (the whole
+// checkpoint is being discarded) and explains why, per FR-208.
+//
+// A record whose payload hash (`c`) doesn't verify is torn/tampered and ends
+// recovery right there, same as before FR-208. A record that verifies
+// structurally but whose OWN content hash (`h`) no longer matches the
+// CURRENT content of that file is a different, later check — it is not
+// corrupt, so it does not truncate the file; it is simply excluded from
+// `handle.recovered` and named in `handle.invalidatedFiles`, so only that
+// file gets re-analysed this run.
+function _recover(handle, file, globalKey, meta, fileContents) {
   let buf;
   try { buf = fs.readFileSync(file); }
-  catch { return -1; } // no file yet
+  catch { return { offset: -1, discardReason: null }; } // no file yet
   const text = buf.toString('utf8');
   const nl = text.indexOf('\n');
-  if (nl < 0) return 0;
+  if (nl < 0) return { offset: 0, discardReason: 'empty or corrupt checkpoint file' };
   let header = null;
-  try { header = JSON.parse(text.slice(0, nl)); } catch { return 0; }
-  if (!header || header.v !== FORMAT || header.runKey !== runKey) return 0;
+  try { header = JSON.parse(text.slice(0, nl)); } catch { return { offset: 0, discardReason: 'corrupt checkpoint header' }; }
+  if (!header || header.v !== FORMAT) return { offset: 0, discardReason: 'checkpoint format changed' };
+  if (header.gk !== globalKey) return { offset: 0, discardReason: _explainGlobalMismatch(header.meta, meta) };
 
   let offset = Buffer.byteLength(text.slice(0, nl + 1), 'utf8');
   let cursor = nl + 1;
@@ -187,19 +273,50 @@ function _recover(handle, file, runKey) {
     if (rec.c !== _sha(rec.d)) break;         // tampered or torn-then-patched
     let payload;
     try { payload = JSON.parse(rec.d); } catch { break; }
+    // Structurally intact and parseable — advance past it regardless of what
+    // the per-file content check below decides; a stale-but-intact record is
+    // not a torn or tampered one and must not be truncated away.
+    offset = Buffer.byteLength(text.slice(0, cursor), 'utf8');
+    // FR-208: per-file content check. A record written with no tracked
+    // source hash (`h` absent — e.g. a caller that never supplied
+    // fileContents) has nothing to compare against, so it is trusted exactly
+    // as it was before this per-file check existed.
+    if (rec.h != null) {
+      const current = fileContents ? fileContents[rec.f] : undefined;
+      if (typeof current !== 'string') {
+        handle.invalidatedFiles.push({ file: rec.f, reason: 'no longer part of this scan' });
+        continue;
+      }
+      if (rec.h !== _sha(current)) {
+        handle.invalidatedFiles.push({ file: rec.f, reason: 'content changed since it was checkpointed' });
+        continue;
+      }
+    }
     if (!handle.recovered.has(rec.f)) handle.order.push(rec.f);
     handle.recovered.set(rec.f, payload);
-    offset = Buffer.byteLength(text.slice(0, cursor), 'utf8');
   }
-  return offset;
+  return { offset, discardReason: null };
 }
 
 /**
- * Open (or start) the checkpoint for `scanRoot` under `runKey`. Never throws.
- * A handle whose `enabled` is false silently no-ops through the rest of the API.
+ * Open (or start) the checkpoint for `scanRoot` under `globalKey`. Never
+ * throws. A handle whose `enabled` is false silently no-ops through the rest
+ * of the API.
+ *
+ * `fileContents` (FR-208): the CURRENT content of every file this scan would
+ * analyse, keyed by the same relative path `recordFileDone` is called with.
+ * Passed through to per-file content comparison on recovery, and to
+ * `recordFileDone` for hashing each new record's own content. Omitting it
+ * (or passing `{}`) degrades every record to trust-on-structural-validity
+ * only — the pre-FR-208 behaviour — which is exactly what a caller testing
+ * the checkpoint PROTOCOL itself (not per-file invalidation) wants, and
+ * exactly what the low-level tests in this module's test file rely on.
+ *
+ * `meta`: a plaintext summary of the inputs behind `globalKey` (see
+ * `globalKeyMeta`), stored in the header purely to explain a mismatch later.
  */
-export function openCheckpoint(scanRoot, { runKey } = {}) {
-  if (!scanRoot || !runKey) return _emptyHandle('no-run-key');
+export function openCheckpoint(scanRoot, { globalKey, meta = {}, fileContents = {} } = {}) {
+  if (!scanRoot || !globalKey) return _emptyHandle('no-global-key');
   // A read-only scan cannot checkpoint, and must not try. Resume is purely an
   // optimisation — without it the scan recomputes, which is slower and
   // identical — so `--no-state` wins over `AGENTIC_SECURITY_RESUME=1` rather
@@ -207,20 +324,25 @@ export function openCheckpoint(scanRoot, { runKey } = {}) {
   // the API, so no caller needs a new branch. (PRD M1)
   if (!stateWritesEnabled()) return _emptyHandle('state-writes-disabled');
   const handle = _emptyHandle(null);
+  handle.fileContents = fileContents || {};
   try {
     const dir = path.join(scanRoot, STATE_DIR);
     fs.mkdirSync(dir, { recursive: true });
     const file = checkpointPath(scanRoot);
     handle.file = file;
-    handle.runKey = runKey;
+    handle.globalKey = globalKey;
 
-    const keepBytes = _recover(handle, file, runKey);
+    const { offset: keepBytes, discardReason } = _recover(handle, file, globalKey, meta, handle.fileContents);
     if (keepBytes <= 0) {
-      // Absent, foreign, or unreadable — start clean. Conservative by design.
+      // Absent, foreign, or globally invalidated — start clean. A byte offset
+      // of -1 (no file yet) is a fresh checkpoint, not a discard, so it gets
+      // no reason; 0 (format/global-key mismatch, or corrupt header) does.
       handle.recovered.clear();
       handle.order.length = 0;
+      handle.invalidatedFiles = [];
       handle.discarded = keepBytes === 0;
-      fs.writeFileSync(file, _headerLine(runKey));
+      handle.reason = keepBytes === 0 ? discardReason : null;
+      fs.writeFileSync(file, _headerLine(globalKey, meta));
     } else {
       // Drop any torn tail so appends land after the last verified record.
       try {
@@ -243,6 +365,13 @@ export function openCheckpoint(scanRoot, { runKey } = {}) {
  * analysis produced. `findings` is the per-file payload object (see the engine
  * call site); it must be plain JSON data. Returns true only if the record is on
  * disk and fsync'd.
+ *
+ * Also records a SHA-256 of `relPath`'s current content (from the
+ * `fileContents` the handle was opened with), so a later run's `_recover` can
+ * tell whether this specific file has changed since — the FR-208 per-file
+ * half of invalidation. A handle opened without `fileContents` (or one that
+ * doesn't include this path) records no hash, which `_recover` treats as
+ * "nothing to compare," matching this module's pre-FR-208 behaviour exactly.
  */
 export function recordFileDone(handle, relPath, findings) {
   if (!handle || !handle.enabled || handle.fd === null || typeof relPath !== 'string') return false;
@@ -250,7 +379,9 @@ export function recordFileDone(handle, relPath, findings) {
     if (!_jsonSafe(findings)) return false;
     const d = JSON.stringify(findings === undefined ? null : findings);
     if (typeof d !== 'string') return false;
-    const line = JSON.stringify({ f: relPath, c: _sha(d), d }) + '\n';
+    const src = handle.fileContents ? handle.fileContents[relPath] : undefined;
+    const h = typeof src === 'string' ? _sha(src) : null;
+    const line = JSON.stringify({ f: relPath, h, c: _sha(d), d }) + '\n';
     fs.writeSync(handle.fd, line);
     fs.fsyncSync(handle.fd);
     handle.written.add(relPath);
@@ -260,6 +391,20 @@ export function recordFileDone(handle, relPath, findings) {
   }
 }
 
+/**
+ * FR-208: individually-invalidated files from a checkpoint whose GLOBAL
+ * identity still matched — each entry names the file and why (content
+ * changed, or the file is no longer part of this scan). Deliberately does
+ * NOT enumerate every file when the whole checkpoint was discarded instead
+ * (`handle.discarded`/`handle.reason` already say why, once, for all of
+ * them — reading the rest of a large journal just to repeat the same reason
+ * per file would cost real I/O for no new information). Always `[]` on a
+ * disabled handle, a brand-new checkpoint, or a global discard.
+ */
+export function invalidatedFiles(handle) {
+  return (handle && Array.isArray(handle.invalidatedFiles)) ? handle.invalidatedFiles : [];
+}
+
 /** Files already analysed — recovered from a prior run plus written by this one. */
 export function completedFiles(handle) {
   const out = new Set();

package/src/posture/secret-history.js

@@ -12,6 +12,7 @@
 // needs network and is deferred — see the rollup.
 
 import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 // Pull the post-image (added) lines out of a unified diff: lines starting with
 // a single '+' (not the '+++' file header). Returns reconstructed text.
@@ -62,8 +63,15 @@ export function sweepGitHistory(scanRoot, detectFn, { maxCommits = 50, timeoutMs
   if (!scanRoot || typeof detectFn !== 'function') return [];
   let out;
   try {
-    out = execFileSync('git', ['-C', scanRoot, 'log', '-p', '-n', String(maxCommits), '--no-color', '--no-merges', '--no-textconv'],
-      { encoding: 'utf8', maxBuffer: 96 * 1024 * 1024, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'] });
+    // Second independent Finding Provenance PRD audit (FR-PROV-024): this
+    // scanRoot is a scanned repository, not this project's own trusted
+    // checkout. `--no-textconv` alone (the pre-existing hardening here) closes
+    // the .gitattributes textconv surface but NOT `core.fsmonitor` /
+    // `core.hooksPath` — this `log -p` call renders every historical commit's
+    // diff content, the same shape verified exploitable in
+    // provenance/git-evidence.js, so it gets the full hardening too.
+    out = execFileSync('git', hardenGitArgs(['-C', scanRoot, 'log', '-p', '-n', String(maxCommits), '--no-color', '--no-merges', '--no-textconv']),
+      { encoding: 'utf8', maxBuffer: 96 * 1024 * 1024, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() });
   } catch { return []; }
   const parts = out.split(/^commit ([0-9a-f]{7,40})/m); // [pre, sha, body, sha, body, ...]
   const findings = [];

package/src/posture/state-dir.js

@@ -16,7 +16,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-const STATE_DIR_NAME = '.agentic-security';
+// Exported so a caller that needs the state dir NAME for display purposes
+// (e.g. a human-readable "this file lives at X/Y" string, not an actual
+// path construction) can go through the seam too, rather than hardcoding
+// the literal — see test/no-stray-state.test.js's own detector, which
+// flags a quoted '.agentic-security' literal anywhere else in the tree.
+export const STATE_DIR_NAME = '.agentic-security';
 
 const PROJECT_MARKERS = [
   '.git',
@@ -125,6 +130,14 @@ export function isSafeStateDir(dir) {
 // per-caller discipline already failed once: its header records a user who
 // uninstalled the plugin after stray state directories broke their build.
 let _stateWritesEnabled = true;
+// Category-scoped override (M2 §2.4 performance fix): when the blanket
+// switch above is OFF, a category listed here still writes. Exists for
+// lsp/server.js, which needs the provenance disk cache live on every
+// keystroke-save while every OTHER state write (dpia.md, lifecycle.json,
+// ...) stays suppressed — see the withStateWritesDisabled call site in
+// lsp/server.js for why the blanket switch alone made every LSP scan pay
+// the FULL uncached provenance-resolution cost on every single save.
+let _enabledCategories = new Set();
 
 /** Turn all state writing off (or back on) for this process. */
 export function setStateWritesEnabled(enabled) {
@@ -143,10 +156,56 @@ export function stateWritesEnabled() {
   return _stateWritesEnabled;
 }
 
+// Category-aware check used by ensureStateDir/safeWriteState below. A
+// caller that never passes `category` behaves EXACTLY as before: it only
+// ever consults the blanket switch.
+function _categoryEnabled(category) {
+  if (process.env.AGENTIC_SECURITY_NO_STATE === '1') return false;
+  if (_stateWritesEnabled) return true;
+  return !!category && _enabledCategories.has(category);
+}
+
+/**
+ * Run `fn` with state writes forced off, restoring the PRIOR flag value
+ * afterward — for a caller (assurance-hardening PRD FR-704) that must
+ * guarantee ITS scan does not mutate the tree, without having to remember
+ * to call setStateWritesEnabled(true) again itself. A caller that disables
+ * writes and forgets to re-enable them silently breaks every LATER write in
+ * the same process — exactly `apply_fix`'s failure mode this wrapper exists
+ * to prevent, via `finally` rather than caller discipline.
+ *
+ * `exceptCategories` lets a caller keep ONE narrow category of write alive
+ * while everything else stays suppressed — see lsp/server.js. Restored via
+ * the same `finally` as the blanket flag, for the same reason.
+ *
+ * KNOWN LIMITATION: `_stateWritesEnabled` and `_enabledCategories` are both
+ * process-global, not per-call. Two overlapping calls to this function (or
+ * one overlapping a direct setStateWritesEnabled() call) can race and leave
+ * the flags in the wrong state for one of them once both finish. mcp/CLAUDE.md
+ * already documents an accepted concurrency limitation of the same shape for
+ * fix-history.js ("concurrent apply_fix calls can race... today benign... a
+ * future stateful tool needs serialization") — this is the same class of
+ * risk, not a new one, and this wrapper is still a strict improvement over
+ * the alternative it replaces (a caller that writes state UNCONDITIONALLY on
+ * every call, with no opt-out at all).
+ */
+export async function withStateWritesDisabled(fn, { exceptCategories = [] } = {}) {
+  const prior = _stateWritesEnabled;
+  const priorCategories = new Set(_enabledCategories);
+  _stateWritesEnabled = false;
+  for (const c of exceptCategories) _enabledCategories.add(c);
+  try {
+    return await fn();
+  } finally {
+    _stateWritesEnabled = prior;
+    _enabledCategories = priorCategories;
+  }
+}
+
 // Safe mkdir: only creates .agentic-security/ if the parent has a project marker.
 // Returns the dir on success, null if refused. Logs a warning when refused.
-export function ensureStateDir(scanRoot) {
-  if (!stateWritesEnabled()) return null;
+export function ensureStateDir(scanRoot, { category } = {}) {
+  if (!_categoryEnabled(category)) return null;
   const dir = stateDir(scanRoot);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {
@@ -164,8 +223,8 @@ export function ensureStateDir(scanRoot) {
 
 // Safe write: only writes if isSafeStateDir(parent) returns true.
 // Returns true on success, false if refused or errored.
-export function safeWriteState(filePath, content) {
-  if (!stateWritesEnabled()) return false;
+export function safeWriteState(filePath, content, { category } = {}) {
+  if (!_categoryEnabled(category)) return false;
   const dir = path.dirname(filePath);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {

package/src/posture/state-lifecycle-report.js

@@ -0,0 +1,77 @@
+// FR-706 (assurance-hardening PRD): manifest-based export and deletion
+// reports — "Operators can prove what was exported, deleted, retained, or
+// failed."
+//
+// Two report kinds, one shared per-item shape ({name, status, ...}), each
+// written by its one real caller in bin/agentic-security.js:
+//   - `cmdReset` builds a deletion report from the SAME target/preserved
+//     data it already computes for its console output (see FR-702/FR-703),
+//     reshaped into a durable, structured artifact instead of only ever
+//     printed and lost. Written on BOTH a dry run (items carry status
+//     'planned') and a real run (status 'deleted'/'failed'), so an operator
+//     can prove either "what would happen" or "what did happen" depending
+//     on which they asked for — `dryRun` on the report says which.
+//   - `cmdExport` (new) builds an export report after copying every
+//     currently-present registered artifact to an operator-chosen
+//     destination, naming what was copied (with a hash) and what failed.
+//
+// Each report is a SINGLE OVERWRITTEN file per kind — the same "last
+// action" precedent as last-scan.json, not an ever-growing log. An
+// operator who needs a persistent audit trail across many runs should
+// retain these externally (commit them, forward to their own SIEM); this
+// module's job is only to make the LAST action's outcome durable and
+// provable, not to be the audit log itself.
+
+import { statePath, safeWriteState } from './state-dir.js';
+
+export const DELETION_REPORT_FILE = 'deletion-report.json';
+export const EXPORT_REPORT_FILE = 'export-report.json';
+
+export function buildDeletionReport({ mode, dryRun, root, items, preserved }) {
+  const list = Array.isArray(items) ? items : [];
+  const preservedList = Array.isArray(preserved) ? preserved : [];
+  return {
+    schema: 'agentic-security/deletion-report@1',
+    generatedAt: new Date().toISOString(),
+    mode: mode || 'reset',
+    dryRun: !!dryRun,
+    root: root || null,
+    items: list,
+    preserved: preservedList,
+    summary: {
+      planned: list.filter(i => i.status === 'planned').length,
+      deleted: list.filter(i => i.status === 'deleted').length,
+      failed: list.filter(i => i.status === 'failed').length,
+      preserved: preservedList.length,
+    },
+  };
+}
+
+export function writeDeletionReport(scanRoot, report) {
+  try {
+    const fp = statePath(scanRoot, DELETION_REPORT_FILE);
+    return safeWriteState(fp, JSON.stringify(report, null, 2) + '\n') ? fp : null;
+  } catch { return null; }
+}
+
+export function buildExportReport({ root, outDir, items }) {
+  const list = Array.isArray(items) ? items : [];
+  return {
+    schema: 'agentic-security/export-report@1',
+    generatedAt: new Date().toISOString(),
+    root: root || null,
+    outDir: outDir || null,
+    items: list,
+    summary: {
+      exported: list.filter(i => i.status === 'exported').length,
+      failed: list.filter(i => i.status === 'failed').length,
+    },
+  };
+}
+
+export function writeExportReport(scanRoot, report) {
+  try {
+    const fp = statePath(scanRoot, EXPORT_REPORT_FILE);
+    return safeWriteState(fp, JSON.stringify(report, null, 2) + '\n') ? fp : null;
+  } catch { return null; }
+}

package/src/posture/suppressions.js

@@ -4,11 +4,41 @@
 //                  reviewer + expiry + rule-version pin)
 // One function `applySuppressions(findings, scanRoot, profile)` filters in
 // place. Loaders accept malformed input gracefully (skip bad entries, log).
+//
+// FR-1004 (assurance-hardening PRD): "exception owner, reason, scope,
+// compensating control, and expiry." The pro schema already had reason
+// (`reason`) and expiry (`expires_at`); `owner`, `scope`, and
+// `compensating_control` are added here as required fields on the SAME
+// entry, validated by the SAME `validateProSuppression` gate that already
+// enforces the two-person rule. This is a deliberate tightening: an
+// existing suppressions.yml entry written before this field set was
+// required will now fail validation and REOPEN its finding, same as any
+// other invalid pro suppression already does — an operator must add the
+// three new fields to keep the exception honored. `owner` is who is
+// accountable for eventually resolving or renewing the exception (may or
+// may not be the same person as `reviewer`); `scope` is a short,
+// human-readable statement of what the exception covers (this module's
+// matching remains per-finding — `scope` documents intent, it does not
+// widen what gets suppressed); `compensating_control` is the specific
+// alternative mitigation that justifies leaving the underlying finding
+// unfixed (a required field, not inferred from `reason` — "we'll fix it
+// later" is a reason, not a compensating control, and conflating the two
+// was the actual gap this PRD item exists to close).
+//
+// "Expired exceptions automatically reopen findings or fail the gate":
+// `applySuppressions` already returns an expired suppression's finding to
+// the KEPT (open) set rather than the suppressed set (see the `exp < now`
+// branch below) — an expired exception was always self-reopening by
+// construction, this was just never covered by a test until FR-1004.
+// Reopening feeds the existing severity-based CI gate (`--fail-on`)
+// exactly like any other open finding; no second, parallel expiry-gate
+// mechanism is needed or built here.
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 import { statePath, safeWriteState } from './state-dir.js';
+import { loadApproverRegistry, verifyApprover, requiredRolesFor } from '../fix/approver-registry.js';
 
 const MS_PER_DAY = 86400000;
 const SOFT_TTL_DAYS = 30;
@@ -59,14 +89,31 @@ export function loadProSuppressions(scanRoot) {
 }
 
 // Validate one entry. Returns { ok, errors }.
-export function validateProSuppression(entry) {
+//
+// FR-1002: "bind approvals, EXCEPTIONS, AND SUPPRESSIONS to verified
+// identities and roles... anonymous or unauthorized high-risk exceptions
+// fail policy." A pro suppression's `justification_signed_by` is exactly
+// such an exception-approval identity, but until this fix it was pure
+// self-reported free text -- FR-307/FR-1002's registry existed and was
+// wired into apply_fix, but never consulted here. `opts.registry` is
+// optional and NO-OP when absent (loadApproverRegistry(scanRoot) returns
+// null until an operator opts in, matching every other gate in this
+// registry), so an existing project with no registry file sees zero
+// behavior change. `opts.requiredRoles` lets the caller scope role
+// requirements to the SUPPRESSED FINDING's own family/category, the same
+// way FR-307 scopes them to a change's material-change category.
+export function validateProSuppression(entry, opts = {}) {
   const errors = [];
-  for (const k of ['finding_id', 'file', 'reason', 'justification_signed_by', 'reviewer', 'expires_at']) {
+  for (const k of ['finding_id', 'file', 'reason', 'justification_signed_by', 'reviewer', 'expires_at', 'owner', 'scope', 'compensating_control']) {
     if (!entry[k] || (typeof entry[k] === 'string' && !entry[k].trim())) errors.push(`missing: ${k}`);
   }
   if (entry.justification_signed_by && entry.reviewer && entry.justification_signed_by === entry.reviewer) {
     errors.push('justification_signed_by must differ from reviewer (two-person rule)');
   }
+  if (entry.justification_signed_by && opts.registry !== undefined) {
+    const v = verifyApprover(opts.registry, entry.justification_signed_by, opts.requiredRoles || []);
+    if (!v.verified) errors.push(`justification_signed_by not authorized: ${v.reason}`);
+  }
   if (entry.expires_at) {
     const t = _dateOnly(entry.expires_at);
     if (!Number.isFinite(t)) errors.push('expires_at must be ISO date');
@@ -84,6 +131,11 @@ export function applySuppressions(findings, scanRoot, profile) {
   const items = isPro ? loadProSuppressions(scanRoot) : loadSoftAccepted(scanRoot);
   if (!items.length) return findings;
 
+  // FR-1002: loaded once per call, not per entry — a missing registry file
+  // (the common, not-opted-in case) makes verifyApprover() a no-op below,
+  // exactly like every other gate built on this registry.
+  const approverRegistry = isPro ? loadApproverRegistry(scanRoot) : null;
+
   const now = _now();
   const kept = [];
   const suppressed = [];
@@ -106,7 +158,11 @@ export function applySuppressions(findings, scanRoot, profile) {
       }
       // Pro: validate the entry still passes
       if (isPro) {
-        const v = validateProSuppression({ ...matched, severity: f.severity });
+        // Same registry/category shape FR-307 already uses for high-impact
+        // fixes: an operator opts a finding family into role-gating via
+        // requiredRolesByCategory, keyed by that family's name.
+        const requiredRoles = requiredRolesFor(approverRegistry, [f.family].filter(Boolean));
+        const v = validateProSuppression({ ...matched, severity: f.severity }, { registry: approverRegistry, requiredRoles });
         if (!v.ok) { kept.push({ ...f, _suppressionInvalid: v.errors }); continue; }
       }
       suppressed.push({ ...f, _suppressed: matched });

package/src/posture/vuln-archaeology.js

@@ -34,6 +34,7 @@
 // timeout, degrading to an empty result in a non-repository.
 
 import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 const CVE_RE = /\b(?:CVE-\d{4}-\d{4,7}|GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})\b/i;
 
@@ -87,14 +88,19 @@ export function classifyCommit(subject) {
   return { tier: 'mentioned', evidence: `mentions "${noun[0]}" with no fix verb` };
 }
 
+// `scanRoot` is the scanned project's repository, not this project's own
+// trusted checkout — hardened per FR-PROV-024 / the second Finding
+// Provenance PRD audit (same exposure class as
+// provenance/git-evidence.js's `_run`). No `--no-textconv` needed: this
+// invocation has no `-p`/`-L`, so no diff/blob content is rendered.
 function _gitLog(scanRoot, { maxCommits, timeoutMs }) {
   // NUL-delimited records so subjects containing newlines cannot split a
   // record — a commit message is arbitrary user text and must not be able to
   // forge a record boundary.
-  const out = execFileSync('git', [
+  const out = execFileSync('git', hardenGitArgs([
     '-C', scanRoot, 'log', '-n', String(maxCommits), '--no-merges', '--no-color',
     '--name-only', '--format=%x00%H%x1f%aI%x1f%s',
-  ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  ]), { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() });
   const commits = [];
   for (const block of out.split('\0')) {
     if (!block.trim()) continue;