@clear-capabilities/agentic-security-scanner 0.144.0 → 0.147.0

package/src/posture/provenance-evidence-bundle.js

@@ -0,0 +1,144 @@
+// Signed provenance evidence bundles (Finding Provenance PRD, M4 §4.1).
+//
+// Sibling to posture/evidence-bundle.js, not a generalization of it — that
+// module's bundle shape (proofTier, taintPath, exploitability...) answers
+// "is this finding real"; this one answers "who/when introduced it, how
+// sure are we." Forcing one shape to cover both would leave half of every
+// bundle null. Same four-function pattern (build/sign/verify + a schema
+// string + a top-level-key allowlist), same Ed25519 key material — reused,
+// not reimplemented.
+//
+// The allowlisted fields mirror provenance/coordinator.js's own
+// computeDigest() material EXACTLY (stableId, findingOrigin.commit,
+// branchIntroduction.commit, evidenceAttribution role:path:line:commit
+// strings, method, confidence.reasons, limitations) plus repo/HEAD identity
+// (not in computeDigest's material, since that digest never leaves the repo
+// it was computed in, but a bundle does). Everything here is copied from
+// what findingProvenance already computed. Nothing is inferred.
+//
+// canonicalJson vs canonicalBytes — resolved before writing this file
+// -------------------------------------------------------------------
+// evidence-bundle.js exports TWO canonicalisation helpers, not one, and they
+// are not interchangeable. `canonicalJson(value)` is a pure, shape-agnostic
+// deterministic serialiser (sorted keys at every level, order-preserving
+// arrays) — safe to reuse for any bundle shape. `canonicalBytes(bundle)`
+// is NOT generic: it hardcodes evidence-bundle.js's own six top-level keys
+// (`schema, finding, evidence, engine, proves, doesNotProve`) when building
+// the object it signs. Reusing `canonicalBytes` here would silently sign a
+// filtered object missing this module's `repo` and `provenance` fields
+// (and would read `bundle.evidence`, which a provenance bundle never has) —
+// exactly the EA-03 failure mode the allowlist check below exists to catch,
+// just introduced from the signing side instead of the verifying side. So
+// this module imports the generic `canonicalJson` (as the brief's Step 1
+// sketch already did) and signs `canonicalJson(bundle)` directly, since
+// `buildProvenanceEvidenceBundle` never puts anything on the unsigned
+// object beyond this module's own allowlisted fields.
+
+import * as crypto from 'node:crypto';
+import { ensureKeyPair, keyPaths, canonicalJson } from './evidence-bundle.js';
+
+export const PROVENANCE_BUNDLE_SCHEMA = 'agentic-security/provenance-evidence@1';
+
+const PROVES = 'This bundle\'s contents are exactly what was signed at attestation time.';
+const DOES_NOT_PROVE = 'This bundle does NOT prove the origin commit is correctly identified — read confidence.level and limitations for that. It proves the RECORD is unmodified, not that the record is right.';
+
+/**
+ * Build an unsigned provenance bundle from one finding's findingProvenance.
+ * Returns null for a finding with no findingProvenance at all (nothing to
+ * attest) — this is a caller error (attest a scan before its provenance
+ * pass ran), not a case to paper over with an empty bundle.
+ */
+export function buildProvenanceEvidenceBundle(finding, { engineVersion, repoIdentity, head } = {}) {
+  if (!finding || typeof finding !== 'object') return null;
+  const fp = finding.findingProvenance;
+  if (!fp || typeof fp !== 'object') return null;
+  return {
+    schema: PROVENANCE_BUNDLE_SCHEMA,
+    finding: {
+      id: finding.id ?? null,
+      stableId: finding.stableId ?? null,
+    },
+    repo: {
+      identity: repoIdentity ?? null,
+      head: head ?? fp.analysisBasis?.head ?? null,
+    },
+    provenance: {
+      status: fp.status ?? null,
+      findingOrigin: fp.findingOrigin
+        ? {
+            commit: fp.findingOrigin.commit ?? null,
+            authorName: fp.findingOrigin.authorName ?? null,
+            authorDate: fp.findingOrigin.authorDate ?? null,
+            summary: fp.findingOrigin.summary ?? null,
+          }
+        : null,
+      branchIntroduction: fp.branchIntroduction
+        ? { commit: fp.branchIntroduction.commit ?? null, branch: fp.branchIntroduction.branch ?? null }
+        : null,
+      evidenceAttribution: (fp.evidenceAttribution || []).map((n) => ({
+        role: n.role ?? null, path: n.path ?? null, line: n.line ?? null, commit: n.commit ?? null,
+      })),
+      method: fp.method ?? null,
+      confidence: fp.confidence
+        ? { level: fp.confidence.level ?? null, score: fp.confidence.score ?? null, reasons: fp.confidence.reasons || [] }
+        : null,
+      limitations: fp.limitations || [],
+      // M4 §4.2 final-review fix: this module was written (Task 1) before
+      // the cross-repo lineage feature existed (Task 5), so a
+      // cross-repo-resolved origin's boundary-crossing marker was dropped
+      // from the signed bundle — a foreign repository's commit SHA and a
+      // real author name, with no MACHINE-READABLE signal that the origin
+      // crossed a repository boundary (only the prose in `limitations`
+      // said so, and a programmatic verifier does not read prose). Nested
+      // under `provenance` alongside the fields above, so it is part of
+      // what gets signed — never a new top-level key.
+      historyCoverage: { crossRepoLineage: fp.historyCoverage?.crossRepoLineage ?? false },
+    },
+    engine: { engineVersion: engineVersion ?? null },
+    proves: PROVES,
+    doesNotProve: DOES_NOT_PROVE,
+  };
+}
+
+export function signProvenanceEvidenceBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, Buffer.from(canonicalJson(bundle), 'utf8'), privateKeyPem);
+  return {
+    ...bundle,
+    signature: { algorithm: 'ed25519', canonicalisation: PROVENANCE_BUNDLE_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+const PROVENANCE_BUNDLE_TOP_LEVEL_KEYS = new Set([
+  'schema', 'finding', 'repo', 'provenance', 'engine', 'proves', 'doesNotProve', 'signature',
+]);
+
+/**
+ * Verify with a PUBLIC key only. Rejects any top-level key outside the
+ * allowlist BEFORE checking the signature — same EA-03 fix evidence-bundle.js
+ * carries: a signature only covers the bytes it was computed over, so an
+ * unknown key stapled on after signing would otherwise verify as authentic.
+ */
+export function verifyProvenanceEvidenceBundle(bundle, publicKeyPem) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  if (bundle.schema !== PROVENANCE_BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  const unknownKeys = Object.keys(bundle).filter((k) => !PROVENANCE_BUNDLE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  const { signature, ...unsigned } = bundle;
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(canonicalJson(unsigned), 'utf8'), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return ok
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+}
+
+export { ensureKeyPair, keyPaths };

package/src/posture/remediation-ledger.js

@@ -0,0 +1,337 @@
+// remediation-ledger.js — M5 deliverable #6 (Blast-Radius: Remediation
+// Command Center, FR-507 + AC-31), Task 2 of the sub-project: the IMPURE
+// half. `../lineage/remediation.js` (Task 1) ships the pure RemediationItem
+// contract — zero imports, no fs, never throws. This module owns every side
+// effect that contract needs to become a real, durable, tamper-evident
+// record: file locking, JSONL append, tolerant read, and the hash chain.
+//
+// This is the SECOND `posture/` → `lineage/` import in the codebase
+// (`auditor-walkthrough.js`'s `graph:` branch was the first, per
+// `posture/CLAUDE.md`'s "First `posture/` → `lineage/` import" section) —
+// noted here so the boundary stays a deliberate, documented exception
+// rather than an accident.
+//
+// ── The append-only contract (PRD line 984) ──────────────────────────────
+//
+// A remediation item's history is never rewritten, only appended to. Every
+// decision — owner assignment, a state change, a manual attestation, an
+// accepted-risk exception — is a permanent event, never an edit of a prior
+// one. `foldRemediationItem`/`foldRemediationLedger` (Task 1) derive an
+// item's CURRENT shape by replaying its events forward; nothing here ever
+// mutates a written line.
+//
+// ── Why the physical shape is a JSONL append, not a whole-file rewrite ────
+//
+// `fix-metrics.js:69`'s `recordFixAttempt` is the precedent this module
+// follows: "One writeSync of one newline-terminated line: a concurrent
+// reader sees whole records or nothing, and a torn tail is dropped on
+// read." `provenance/lifecycle.js:195`'s `updateLifecycle`, by contrast,
+// reads the WHOLE store into memory, folds one scan's worth of changes in,
+// and rewrites the WHOLE file — safe there because a lifecycle update is a
+// single scan touching potentially every finding at once. A remediation
+// ledger is the opposite shape: a human, one item at a time, arbitrarily
+// interleaved with edits to every OTHER item. A partial rewrite of a shared
+// document risks losing every OTHER item's history to a crash or a bug
+// mid-rewrite; an append can only ever add a new, independently-readable
+// line.
+//
+// ── Why a lock is still required, despite the append itself being atomic ──
+//
+// `fs.appendFileSync` of one line is atomic at the OS level, but writing an
+// event is not just "append a line" — it is a READ-MODIFY-WRITE: the
+// proposed event must be validated (`validateTransition`) against the
+// item's CURRENT folded state, which requires reading and folding every
+// prior event first. Two concurrent callers each reading the same "before"
+// state and then both appending could both validate against a state that
+// is stale by the time either write lands — e.g. two racing attempts to
+// open the same item, both seeing "no item yet" and both succeeding, when
+// exactly one must win. The lock serializes the whole
+// read-fold-validate-append sequence into one critical section per event.
+//
+// `withLock` below is a faithful local PORT of
+// `provenance/lifecycle.js:36`'s own `withLock` — NOT an import, because
+// that function is not exported (verified directly against the file: it is
+// a bare, module-private `async function withLock`). `isProcessAlive` is
+// ported alongside it for the same reason.
+//
+// ── The hash chain ─────────────────────────────────────────────────────
+//
+// Byte-identical in behavior to `mcp/audit.js`'s own chain (`_sha`,
+// `GENESIS`, `_readLastEntryHash`, `verifyAuditLog`, verified directly
+// against that file before writing this one): each event carries `prev`,
+// the SHA-256 hex digest of the PREVIOUS line's exact serialized JSON text
+// (including that line's own `prev` field). The first event's `prev` is
+// the literal string `'GENESIS'`. `readLedgerEvents`/`latestEventHash`
+// walk forward from GENESIS; a line that fails to `JSON.parse` (a torn
+// tail) or whose `prev` does not match the expected running hash (tamper)
+// STOPS the walk. Both functions therefore return the longest verifying
+// PREFIX of the file — never the full stream when any of it is
+// unverifiable, and never a thrown error. See `_walkLedger` below, which
+// both exported readers share so they cannot silently disagree on what
+// "the last valid line" means.
+//
+// `appendLedgerEvent` is async and is the SINGLE place `validateTransition`
+// is called in this codebase. No CLI command (Task 3) computes validity
+// for itself — every proposed event is validated at this one write
+// boundary, inside the lock, against the real current folded state. As of
+// final-review fix round 1, this is also the single place THREE more
+// things are enforced, all inside the same lock so none of them can race
+// the write they guard: an `opened` event is additionally checked against
+// `validateOpenPayload` (I4/M11 — previously only the CLI validated an
+// `opened` payload's own shape, so a non-CLI caller could append a
+// malformed one); the ledger's on-disk tail is checked for tearing before
+// anything is appended onto it (I4 — appending onto a torn line would
+// merge them into one unparseable line, silently losing the new event,
+// and everything after it, forever); and an optional
+// `opts.expectedBaseHash` optimistic-concurrency check runs against the
+// real `lastHash` computed inside the lock (I5 — previously the CLI's own
+// `--base-event` guard ran OUTSIDE the lock, a real TOCTOU: another
+// process could append in the window between that check and this
+// function's own lock acquisition).
+
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { statePath, isSafeStateDir, stateWritesEnabled } from './state-dir.js';
+import { validateTransition, validateOpenPayload, foldRemediationLedger } from '../lineage/remediation.js';
+
+const GENESIS = 'GENESIS';
+
+function _sha(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+export function ledgerPaths(scanRoot) {
+  return {
+    ledgerPath: statePath(scanRoot, 'remediation', 'items.jsonl'),
+    lockPath: statePath(scanRoot, 'remediation', 'items.lock'),
+  };
+}
+
+// Shared walk: reads the ledger file (missing → empty), splits on '\n',
+// drops empty lines, and walks forward maintaining `expectedPrev` (starting
+// at GENESIS) exactly as `mcp/audit.js`'s `verifyAuditLog` does. A parse
+// failure or a `prev` mismatch stops the walk without throwing. Returns
+// `{events, lastHash}` so `readLedgerEvents`/`latestEventHash` cannot drift
+// apart on what "the last valid line" means.
+function _walkLedger(scanRoot) {
+  const { ledgerPath } = ledgerPaths(scanRoot);
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return { events: [], lastHash: GENESIS };
+  }
+  const lines = raw.split('\n').filter(Boolean);
+  const events = [];
+  let expectedPrev = GENESIS;
+  let lastHash = GENESIS;
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      break; // torn tail — stop, do not throw
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event) || event.prev !== expectedPrev) {
+      break; // tamper detected — stop, do not throw
+    }
+    events.push(event);
+    lastHash = _sha(line);
+    expectedPrev = lastHash;
+  }
+  return { events, lastHash };
+}
+
+// Returns the longest verifying PREFIX of the ledger — never the full
+// stream when a tail is torn or a middle line is tampered. Never throws.
+export function readLedgerEvents(scanRoot) {
+  return _walkLedger(scanRoot).events;
+}
+
+// GENESIS when the ledger is empty/missing, or when nothing in it verifies.
+export function latestEventHash(scanRoot) {
+  return _walkLedger(scanRoot).lastHash;
+}
+
+// Reports whether the ledger's real content on disk has more raw lines than
+// the longest verifying prefix — i.e. a torn tail OR a tampered middle line
+// broke the hash chain partway through. Never throws. This is a read-only
+// diagnostic; it does not change what readLedgerEvents/latestEventHash
+// return (both still return the longest verifying prefix, unconditionally
+// safe by construction) — it exists so a caller (the CLI's `list` command)
+// can surface a loud warning instead of silently presenting a shorter or
+// stale history as if it were the whole truth. (I7, final-review fix
+// round 1.)
+export function ledgerIntegrity(scanRoot) {
+  const { ledgerPath } = ledgerPaths(scanRoot);
+  let raw;
+  try {
+    raw = fs.readFileSync(ledgerPath, 'utf8');
+  } catch {
+    return { ok: true, totalLines: 0, verifiedLines: 0 };
+  }
+  const totalLines = raw.split('\n').filter(Boolean).length;
+  const { events } = _walkLedger(scanRoot);
+  return { ok: events.length === totalLines, totalLines, verifiedLines: events.length };
+}
+
+function isProcessAlive(pid) {
+  // POSIX: process.kill(pid, 0) probes existence without sending a signal.
+  // EPERM also means the process exists; only ESRCH means dead.
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e && e.code === 'EPERM'; }
+}
+
+// Faithful local port of `provenance/lifecycle.js:36-88`'s `withLock` — not
+// an import, since that function is module-private there. Exclusive `wx`
+// open of the lockfile, write the PID, run `fn` in a `try`, `unlink` in
+// `finally`. On EEXIST, a stale lock (holding PID not alive, or lockfile
+// older than 30s) is reaped, re-reading the lockfile before unlinking so a
+// fresh holder taken by another process in the meantime is never raced.
+// 25ms retry; 5s timeout throwing a named error.
+async function withLock(lockPath, fn) {
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  const start = Date.now();
+  const TIMEOUT_MS = 5000;
+  while (true) {
+    try {
+      const handle = await fsp.open(lockPath, 'wx');
+      await handle.writeFile(String(process.pid));
+      try { await handle.close(); } catch {}
+      try {
+        return await fn();
+      } finally {
+        await fsp.unlink(lockPath).catch(() => {});
+      }
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        try {
+          const [st, pidStr] = await Promise.all([
+            fsp.stat(lockPath),
+            fsp.readFile(lockPath, 'utf8').catch(() => ''),
+          ]);
+          const pid = parseInt(pidStr.trim(), 10);
+          const pidAlive = Number.isFinite(pid) && isProcessAlive(pid);
+          const old = Date.now() - st.mtimeMs > 30000;
+          if (!pidAlive || old) {
+            try {
+              // Only unlink if the lockfile still holds the PID we just
+              // read, so we don't race the unlink against a fresh lock
+              // taken by another process in the meantime.
+              const recheck = (await fsp.readFile(lockPath, 'utf8').catch(() => '')).trim();
+              if (recheck === pidStr.trim()) {
+                await fsp.unlink(lockPath);
+              }
+            } catch {}
+            continue;
+          }
+        } catch {}
+        if (Date.now() - start > TIMEOUT_MS) throw new Error('remediation-ledger: lock timed out');
+        await new Promise((r) => setTimeout(r, 25));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+// Resolves the itemId a proposed event refers to, mirroring
+// `foldRemediationLedger`'s own grouping fallback exactly (Task 1's
+// `../lineage/remediation.js`: `ev.itemId ?? (ev.type === 'opened' ?
+// ev.id : undefined)`) — an `opened` event carries `id` (per
+// `foldRemediationItem`'s own use of `openEvent.id`), every other event
+// type carries `itemId`. Reusing the identical fallback here, rather than
+// reading `eventPayload.itemId` alone, is what makes item resolution agree
+// with how the ledger will actually be folded on read — an opened event
+// for an id that already exists must resolve to that existing item, not
+// silently miss it because the payload only carries `id`.
+function _resolveItemId(eventPayload) {
+  if (!eventPayload || typeof eventPayload !== 'object') return undefined;
+  return eventPayload.itemId ?? (eventPayload.type === 'opened' ? eventPayload.id : undefined);
+}
+
+// This function is the single place `validateTransition` is called. No CLI
+// command computes validity for itself. `opts.expectedBaseHash` (I5) is an
+// optional optimistic-concurrency check, compared against the real
+// `lastHash` computed INSIDE the lock — the authoritative half of the
+// `--base-event` guard; `undefined` (the flag was never passed) performs no
+// check.
+export async function appendLedgerEvent(scanRoot, eventPayload, opts = {}) {
+  const { ledgerPath, lockPath } = ledgerPaths(scanRoot);
+  const dir = path.dirname(ledgerPath);
+
+  // Refused BEFORE the lock is taken, so an unsafe/disabled target never
+  // even gets a lockfile written into it.
+  if (!isSafeStateDir(dir)) {
+    return {
+      valid: false,
+      errors: [{ field: '(scanRoot)', message: 'refusing to write — not a recognized project state directory' }],
+    };
+  }
+  if (!stateWritesEnabled()) {
+    return {
+      valid: false,
+      errors: [{ field: '(state)', message: 'state writes are disabled (AGENTIC_SECURITY_NO_STATE or setStateWritesEnabled(false))' }],
+    };
+  }
+
+  return withLock(lockPath, async () => {
+    // I4 (final-review fix round 1): refuse to append onto a torn tail —
+    // concatenating a new event onto an unterminated final line would
+    // merge them into one unparseable line, silently losing this event
+    // (and everything after it) forever while still reporting success. A
+    // crash/ENOSPC mid-write leaves exactly this shape. Checked first,
+    // inside the lock, before anything else touches the file.
+    try {
+      const raw = fs.readFileSync(ledgerPath, 'utf8');
+      if (raw.length > 0 && !raw.endsWith('\n')) {
+        return {
+          valid: false,
+          errors: [{ field: '(ledger)', message: 'the ledger file has a torn/unterminated final line — refusing to append onto it. Recover the file (restore from backup, or manually truncate to its last complete, newline-terminated line) before retrying.' }],
+        };
+      }
+    } catch { /* missing file — nothing to check */ }
+
+    const { events, lastHash } = _walkLedger(scanRoot);
+
+    // I5 (final-review fix round 1): the authoritative optimistic-
+    // concurrency check, run against the real `lastHash` computed inside
+    // this same critical section — the CLI's own pre-lock check is still
+    // useful as a cheap, early fail, but this is the one that cannot be
+    // raced by a concurrent writer.
+    if (opts.expectedBaseHash !== undefined && opts.expectedBaseHash !== lastHash) {
+      return {
+        valid: false,
+        errors: [{ field: '(base-event)', message: 'the ledger changed since --base-event was computed (a concurrent write) — refusing to append.' }],
+      };
+    }
+
+    const items = foldRemediationLedger(events);
+    const itemId = _resolveItemId(eventPayload);
+    const item = itemId != null ? (items[itemId] ?? null) : null;
+
+    // M11: an `opened` event's own shape is validated here too, not just
+    // by the CLI — mirrors "the single place validity is enforced" for
+    // the one event type `validateTransition` deliberately does not
+    // shape-check (it only checks that no item with this id exists yet).
+    if (eventPayload && eventPayload.type === 'opened') {
+      const openCheck = validateOpenPayload(eventPayload);
+      if (!openCheck.valid) {
+        return { valid: false, errors: openCheck.errors };
+      }
+    }
+
+    const { valid, errors } = validateTransition(item, eventPayload);
+    if (!valid) {
+      return { valid: false, errors };
+    }
+
+    const event = { ...eventPayload, prev: lastHash };
+    const line = JSON.stringify(event);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(ledgerPath, line + '\n', 'utf8');
+    return { valid: true, errors: [], event, hash: _sha(line) };
+  });
+}

package/src/posture/sbom-diff.js

@@ -24,7 +24,8 @@ import * as fs from 'node:fs';
 import { statePath, stateWritesEnabled } from './state-dir.js';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 const HISTORY_DIR = 'sbom-history';
 
@@ -32,9 +33,21 @@ function _historyDir(scanRoot) {
   return statePath(scanRoot, HISTORY_DIR);
 }
 
+// `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 sweep (found missing here by a follow-up review that
+// grepped for `child_process` usage beyond just `execFileSync('git'` call
+// sites). `rev-parse HEAD` was VERIFIED not to itself trigger
+// `core.fsmonitor`/a hook (it touches neither the working tree nor the
+// index), so this is not a second live RCE — but leaving
+// `GIT_CONFIG_NOSYSTEM`/`GIT_TERMINAL_PROMPT`/`core.hooksPath` unset here
+// still violated this module's own "every git call routes through
+// hardenGitArgs/hardenGitEnv" contract, and `execSync` (a shell string) is
+// gratuitous risk this call never needed — `rev-parse HEAD` has no
+// caller-controlled input to interpolate at all.
 function _gitHead(scanRoot) {
   try {
-    return execSync('git rev-parse HEAD', { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return execFileSync('git', hardenGitArgs(['rev-parse', 'HEAD']), { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() }).trim();
   } catch { return null; }
 }
 

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

@@ -130,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) {
@@ -148,6 +156,15 @@ 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
@@ -157,31 +174,38 @@ export function stateWritesEnabled() {
  * the same process — exactly `apply_fix`'s failure mode this wrapper exists
  * to prevent, via `finally` rather than caller discipline.
  *
- * KNOWN LIMITATION: `_stateWritesEnabled` is process-global, not per-call.
- * Two overlapping calls to this function (or one overlapping a direct
- * setStateWritesEnabled() call) can race and leave the flag 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
+ * `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) {
+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') {
@@ -199,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') {