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

package/src/posture/provenance/lifecycle.js

@@ -0,0 +1,208 @@
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { statePath, stateWritesEnabled, isSafeStateDir } from '../state-dir.js';
+
+// Both paths go through the state-dir seam rather than joining the state
+// directory name by hand — see test/no-stray-state.test.js.
+//
+// What that does and does NOT buy: statePath() resolves WHERE state belongs
+// (resolveProjectRoot walks up for a project marker), but it performs no
+// safety check of its own. The marker check is `isSafeStateDir`, and it lives
+// inside safeWriteState()/ensureStateDir() — which updateLifecycle
+// deliberately bypasses (see its comment). So this module calls isSafeStateDir
+// explicitly before writing; without that it would happily create
+// `.agentic-security/` in a directory that is not a recognised project root,
+// which is the litter state-dir.js exists to prevent.
+function storePath(scanRoot) { return statePath(scanRoot, 'provenance', 'lifecycle.json'); }
+function lockPath(scanRoot) { return statePath(scanRoot, 'provenance', 'lifecycle.lock'); }
+
+export function readLifecycle(scanRoot) {
+  // Read directly and let the catch handle "missing" — an explicit
+  // existsSync() check first is a check-then-use race for no benefit, since
+  // the catch already covers every failure mode a stale check would too.
+  try {
+    return JSON.parse(fs.readFileSync(storePath(scanRoot), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+// Mirrors posture/fix-history.js's _withLogLock: an exclusive (wx) lockfile,
+// released in finally{}. On contention (EEXIST), a stale lock — one whose
+// holding PID is no longer alive, or one older than 30s — is reaped before
+// falling through to the timeout-based retry loop, so a crashed/killed
+// process (not just a throwing one) cannot wedge provenance updates forever.
+async function withLock(scanRoot, fn) {
+  const lp = lockPath(scanRoot);
+  fs.mkdirSync(path.dirname(lp), { recursive: true });
+  const start = Date.now();
+  const TIMEOUT_MS = 5000;
+  while (true) {
+    try {
+      const handle = await fsp.open(lp, 'wx');
+      await handle.writeFile(String(process.pid));
+      try { await handle.close(); } catch {}
+      try {
+        return await fn();
+      } finally {
+        await fsp.unlink(lp).catch(() => {});
+      }
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        try {
+          const [st, pidStr] = await Promise.all([
+            fsp.stat(lp),
+            fsp.readFile(lp, '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(lp, 'utf8').catch(() => '')).trim();
+              if (recheck === pidStr.trim()) {
+                await fsp.unlink(lp);
+              }
+            } catch {}
+            continue;
+          }
+        } catch {}
+        if (Date.now() - start > TIMEOUT_MS) throw new Error('provenance/lifecycle: lock timed out');
+        await new Promise((r) => setTimeout(r, 25));
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+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'; }
+}
+
+function isOpenEvent(events) {
+  const last = events[events.length - 1];
+  return !!last && ['introduced', 'reintroduced', 'reverted', 'cherry-picked'].includes(last.type);
+}
+
+/**
+ * Fold this scan's findings into `store`, in memory. Pure with respect to the
+ * filesystem — extracted so the read-only path below can produce the SAME view
+ * the persisting path would, without writing anything.
+ *
+ * `completeScan` is the one structural guard in this module, and it exists
+ * because the two passes below make asymmetric claims:
+ *
+ *  - The `introduced`/`reintroduced` pass reasons about findings that ARE
+ *    present. Present is present regardless of how much of the tree was read,
+ *    so it is sound on any scan and always runs.
+ *  - The remediation pass reasons about findings that are ABSENT, turning
+ *    absence into the positive claim "this was fixed." That is only sound if
+ *    the scan actually looked everywhere it could have found them. On a subset
+ *    scan (`--changed-since`, `--pr`, an MCP/LSP caller-supplied file list) the
+ *    entire rest of the project is absent by construction, so running it marks
+ *    every open finding outside the changed set remediated.
+ *
+ * Skipping the pass leaves those entries OPEN, which is the honest state: the
+ * scan has no evidence either way. A later complete scan closes whatever was
+ * genuinely fixed. Defaults true so an explicit `completeScan:false` is what
+ * suppresses it, never a caller forgetting to pass the flag.
+ */
+function applyScan(store, currentFindings, { scanId, observedAt, completeScan = true }) {
+  const currentIds = new Set(currentFindings.map((f) => f.stableId).filter(Boolean));
+
+  for (const f of currentFindings) {
+    if (!f.stableId) continue;
+    const events = store[f.stableId] || (store[f.stableId] = []);
+    if (isOpenEvent(events)) continue;
+    const fp = f.findingProvenance;
+    const commit = fp?.findingOrigin?.commit || null;
+    const authorDate = fp?.status === 'complete' ? (fp.findingOrigin?.authorDate || observedAt) : observedAt;
+    // M3 §3.1: a reintroduction whose resolved findingOrigin is a genuine
+    // revert-of-a-fix or a cherry-picked propagation of an earlier
+    // introduction is a DIFFERENT lifecycle story than an unrelated
+    // reintroduction — both fields are only ever populated by deep-mode
+    // resolution (Task 3), so this vocabulary is silent (both null) for
+    // every standard-mode scan, which is the honest state: standard mode
+    // has no opinion on the distinction.
+    let type = events.length === 0 ? 'introduced' : 'reintroduced';
+    // `relatedCommit` carries the revert-target / cherry-pick-source SHA that
+    // was already read to CLASSIFY `type` above — without this, that SHA was
+    // discarded once the classification was made, so a 'reverted'/
+    // 'cherry-picked' event recorded THAT something was reverted/cherry-picked
+    // but not WHAT commit it was reverted/cherry-picked from, which is the
+    // fact a consumer actually needs to follow the link back.
+    let relatedCommit = null;
+    if (fp?.findingOrigin?.revertOf) { type = 'reverted'; relatedCommit = fp.findingOrigin.revertOf; }
+    else if (fp?.findingOrigin?.cherryPickOf) { type = 'cherry-picked'; relatedCommit = fp.findingOrigin.cherryPickOf; }
+    events.push({ type, commit, authorDate, scanId, observedAt, relatedCommit });
+  }
+
+  if (completeScan !== false) {
+    for (const [stableId, events] of Object.entries(store)) {
+      if (isOpenEvent(events) && !currentIds.has(stableId)) {
+        events.push({ type: 'remediated', commit: null, authorDate: null, scanId, observedAt });
+      }
+    }
+  }
+
+  return store;
+}
+
+export async function updateLifecycle(scanRoot, currentFindings, { scanId, observedAt, completeScan = true }) {
+  // Read-only scan (`--no-state` / AGENTIC_SECURITY_NO_STATE): return the view
+  // this scan WOULD have produced, computed in memory, and persist nothing.
+  //
+  // Returning the on-disk store unchanged would have been one line shorter and
+  // wrong in a quiet way — a caller asking "when was this finding introduced"
+  // would get "never" for every finding first seen in this scan, which is a
+  // false answer rather than a missing one. The lock is skipped too: a lockfile
+  // is itself a write into the scanned tree, and there is nothing to serialise
+  // when nothing is written.
+  if (!stateWritesEnabled()) {
+    return applyScan(readLifecycle(scanRoot), currentFindings, { scanId, observedAt, completeScan });
+  }
+
+  // The project-marker check safeWriteState() would have applied, applied here
+  // because the write below deliberately does not go through it.
+  //
+  // Checked BEFORE withLock, not inside it: withLock's first act is
+  // `fs.mkdirSync(path.dirname(lockPath))`, so guarding only the store write
+  // would still have created `.agentic-security/provenance/` in an
+  // unrecognised directory before refusing — the directory IS the litter, so
+  // refusing after creating it refuses nothing. Returns the same in-memory view
+  // the read-only path returns, for the same reason: a missing answer, not a
+  // false one.
+  if (!isSafeStateDir(path.dirname(storePath(scanRoot)))) {
+    return applyScan(readLifecycle(scanRoot), currentFindings, { scanId, observedAt, completeScan });
+  }
+
+  return withLock(scanRoot, async () => {
+    const store = applyScan(readLifecycle(scanRoot), currentFindings, { scanId, observedAt, completeScan });
+    // Deliberately a direct write, not safeWriteState(): this write is inside a
+    // locked critical section and its failure MUST propagate so the lock is
+    // released and the caller learns the store was not persisted.
+    // safeWriteState swallows errors and returns false, which would turn a
+    // failed write into a silent no-op that still looks like success.
+    fs.mkdirSync(path.dirname(storePath(scanRoot)), { recursive: true });
+    fs.writeFileSync(storePath(scanRoot), JSON.stringify(store, null, 2));
+    return store;
+  });
+}
+
+export function latestOpenIntroduction(store, stableId) {
+  const events = store[stableId];
+  if (!events || events.length === 0) return null;
+  const last = events[events.length - 1];
+  // Same open-type vocabulary as isOpenEvent: 'reverted'/'cherry-picked' are
+  // still open findings (M3 §3.1) — the classification is about HOW the
+  // finding became open, not whether it currently is.
+  return ['introduced', 'reintroduced', 'reverted', 'cherry-picked'].includes(last.type) ? last : null;
+}

package/src/posture/provenance/missing-control-resolver.js

@@ -0,0 +1,137 @@
+// Missing-control regression resolution (Finding Provenance PRD, M3 §3.3).
+//
+// Architecturally inverted from every other resolver in this directory:
+// "when did a previously-observed safeguard DISAPPEAR," not "when did a bad
+// pattern APPEAR." Walks backward from HEAD (newest-first — the opposite
+// direction candidateCommitsForLine's oldest-first convention uses, because
+// this resolver is searching for the MOST RECENT transition from present to
+// absent, not the earliest transition from absent to present).
+//
+// The one invariant this module exists to enforce, verbatim from the spec:
+// if the control is absent at EVERY reachable commit including the
+// repository's own root, status is 'unknown' — NEVER attributed to the root
+// commit. Every other resolver in this milestone treats "absent at the
+// root, present now" as real evidence of introduction (the root IS the
+// beginning of everything this repo can prove). This resolver's question is
+// the mirror image — "when did it disappear" — and a control absent
+// EVERYWHERE has no disappearance to date, which is a fundamentally
+// different, weaker claim than "introduced at the beginning." Collapsing
+// them would be exactly the false certainty the whole feature forbids.
+
+import { getFirstParent, commitMeta, _relPath, _isSafeRevision } from './git-evidence.js';
+import * as cp from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../../util/git-hardening.js';
+
+const GIT_TIMEOUT_MS = 2000;
+// Same hostile-repo hardening as git-evidence.js's `_run` (FR-PROV-024 /
+// second audit). This module's own `_run` call is `log --format=%H
+// --follow -- <path>` — no `-p`/`-L`, no diff/blob content rendered, so no
+// `--no-textconv` surface to close here (see git-evidence.js for the calls
+// where it is load-bearing).
+function _run(scanRoot, args) {
+  try {
+    const stdout = cp.execFileSync('git', hardenGitArgs(args), {
+      cwd: scanRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024,
+      env: hardenGitEnv(),
+    });
+    return { ok: true, stdout };
+  } catch (e) {
+    return { ok: false, stdout: '', error: e };
+  }
+}
+
+// The commits touching `file` on the path from `since`/root to HEAD,
+// NEWEST-FIRST (the reverse of git-evidence.js's candidateCommitsForFile,
+// which is oldest-first — this resolver needs to walk backward from the
+// present).
+//
+// This module reimplements its own git-invocation helper (`_run` above)
+// rather than adding a new wrapper to git-evidence.js, but that must not
+// mean skipping the argument-injection guards every OTHER resolver in this
+// directory gets for free by routing through git-evidence.js. `since` feeds
+// straight into a `<since>..HEAD` revision range and `file` becomes a bare
+// argv token after `--` — both reuse git-evidence.js's own exported guards
+// (`_isSafeRevision`, `_relPath`) rather than re-deriving the validation
+// logic here, so a caller-supplied `since` shaped like a git flag (e.g.
+// `--upload-pack=evil`) or a `file` that escapes scanRoot can never reach
+// git's argv as an unvalidated token — same contract candidateCommitsForFile
+// enforces for the forward-walking resolvers.
+function candidateCommitsNewestFirst(scanRoot, file, since) {
+  const rel = _relPath(scanRoot, file);
+  if (!rel) return [];
+  if (since && !_isSafeRevision(since)) return [];
+  const args = ['log', '--format=%H', '--follow'];
+  if (since) args.push(`${since}..HEAD`);
+  args.push('--', rel);
+  const r = _run(scanRoot, args);
+  if (!r.ok) return [];
+  return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+export async function resolveMissingControl(scanRoot, { file, predicate, since, deadlineAt } = {}) {
+  if (!file || typeof predicate !== 'function') {
+    return { status: 'unknown', commitsConsidered: 0 };
+  }
+  const candidates = candidateCommitsNewestFirst(scanRoot, file, since);
+  if (candidates.length === 0) return { status: 'unknown', commitsConsidered: 0 };
+
+  let commitsConsidered = 0;
+  let priorPresentCommit = null; // the most-recently-checked commit where the control WAS present (walking backward, so this is the newest such commit seen so far)
+
+  for (const sha of candidates) {
+    if (deadlineAt && Date.now() > deadlineAt) return { status: 'budget_exhausted', commitsConsidered };
+    commitsConsidered++;
+    let presentHere;
+    try { presentHere = await predicate(scanRoot, sha, file); } catch { presentHere = false; }
+
+    if (presentHere) {
+      // Found a commit where it WAS present. If we've already seen a LATER
+      // (newer) commit where it was NOT present, that later commit's own
+      // transition (or the commit just after this one, going forward) is
+      // the removal — but walking newest-first, the removal transition is
+      // between THIS commit (present) and the previous iteration's commit
+      // (absent, checked earlier in this loop = newer in time). So: if
+      // priorPresentCommit is unset AND we've already walked past at least
+      // one absent commit, that means HEAD-side history is absent and THIS
+      // commit is present — the transition is between this commit and the
+      // one checked immediately before it in the loop.
+      if (commitsConsidered > 1 && priorPresentCommit === null) {
+        // The immediately-prior (newer) candidate was absent, and this one
+        // is present — that prior candidate (or the gap right after this
+        // commit) is where it disappeared. Report THIS commit (the last
+        // proven-present one) as the evidence anchor, and the prior
+        // candidate as the removal point.
+        const removedMeta = commitMeta(scanRoot, candidates[commitsConsidered - 2]);
+        const presentMeta = commitMeta(scanRoot, sha);
+        if (removedMeta && presentMeta) {
+          return {
+            status: 'complete',
+            removedAt: { commit: removedMeta.commit, authorName: removedMeta.authorName, authorDate: removedMeta.authorDate, summary: removedMeta.summary },
+            presentAt: { commit: presentMeta.commit, authorDate: presentMeta.authorDate },
+            commitsConsidered,
+          };
+        }
+      }
+      priorPresentCommit = sha;
+      // Present at the oldest commit we've checked so far and no removal
+      // found yet — keep walking older history in case there's an EARLIER
+      // removal-then-readd cycle; but for M3's scope (the Scenario I
+      // acceptance case is "never present, resolves unknown" and "present
+      // then removed, resolves complete"), stop here: control is present
+      // at this point in history and we have not yet found where it was
+      // removed relative to HEAD. Continue the loop.
+    }
+    // presentHere === false: keep walking older history (newest-first),
+    // looking for the presence that precedes this absence.
+  }
+
+  // Walked every candidate and never found a present→absent transition —
+  // either the control was NEVER present in any reachable commit (the
+  // Scenario I case — must resolve 'unknown', never attributed to the
+  // oldest candidate as if that were meaningful), or it has been present
+  // at every commit checked (no removal to report, which for THIS
+  // resolver's question — "when did it disappear" — is also 'unknown':
+  // there is no disappearance to date).
+  return { status: 'unknown', commitsConsidered };
+}