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

package/src/posture/provenance/dag-walk.js

@@ -0,0 +1,249 @@
+// Non-linear DAG analysis for --provenance deep (Finding Provenance PRD,
+// M3 §3.1). Three independent capabilities, each documented at its export:
+//
+//  1. checkAbsentInAllParents — generalizes origin-resolver.js's existing
+//     first-parent-only absence check to EVERY parent of a candidate commit.
+//     A vulnerability introduced via a merged feature branch (not mainline)
+//     needs this: checking only the first parent would see the predicate
+//     already present there (inherited from mainline before the merge) and
+//     wrongly conclude the merge commit isn't the origin, when the real
+//     introduction happened on the feature branch's own history — which the
+//     first-parent-only walk never visits at all.
+//
+//  2. detectRevert / detectCherryPick — lifecycle event classification, not
+//     origin resolution. A reintroduction that is actually a revert-of-a-fix
+//     or propagation of an earlier introduction via cherry-pick is a
+//     DIFFERENT lifecycle story than an unrelated re-introduction, and
+//     lifecycle.js's event vocabulary (Task 4) needs to say so.
+import { getAllParents, commitDiff } 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` calls are both `show -s
+// --format=...` (detectRevert's message check, detectCherryPick) — no diff
+// content rendered, so `--no-textconv` is defense-in-depth/uniformity here
+// rather than closing a verified path (the diff-content case,
+// `commitDiff`, is imported from git-evidence.js and already hardened
+// there).
+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 };
+  }
+}
+const SHA_RE = /^[0-9a-f]{4,40}$/i;
+function _isSha(sha) { return typeof sha === 'string' && SHA_RE.test(sha); }
+
+/**
+ * Check whether a predicate is absent in EVERY parent of `sha`, not just the
+ * first. `replay` is the caller's (sha) => Promise<{present:boolean}> closure
+ * (origin-resolver.js already has one via its own memoized `replay`).
+ */
+export async function checkAbsentInAllParents(scanRoot, sha, replay) {
+  const parents = getAllParents(scanRoot, sha);
+  if (parents.length === 0) return { absentInAll: true, parents: [], rootCommit: true };
+  const results = await Promise.all(parents.map((p) => replay(p)));
+  const absentInAll = results.every((r) => !r.present);
+  return { absentInAll, parents, rootCommit: false };
+}
+
+/**
+ * Check whether a predicate is absent in AT LEAST ONE parent of `sha` (not
+ * necessarily all of them). This is the mathematically correct
+ * generalization of origin-resolver.js's first-parent-only check: "absent in
+ * the first parent" is the special case where that one parent happens to be
+ * absent, so "absent in ANY parent" is a strict SUPERSET of what the
+ * first-parent check alone can find — it additionally catches a merge
+ * candidate whose FIRST parent has the predicate (inherited from that
+ * line's own earlier history) but a DIFFERENT parent's line did not, which
+ * means that other line's merge into this one is genuinely where the
+ * predicate became reachable via THIS path. `checkAbsentInAllParents`
+ * (above) answers a different question — "did every contributing line lack
+ * it" — and is a strict SUBSET of the first-parent check instead, which is
+ * why it can never resolve anything the first-parent check couldn't already
+ * resolve on its own; it exists as a safety/non-regression check, not a
+ * resolving-power check. Do not conflate the two.
+ */
+export async function checkAbsentInSomeParent(scanRoot, sha, replay) {
+  const parents = getAllParents(scanRoot, sha);
+  if (parents.length === 0) return { absentInSome: true, absentParents: [], parents: [], rootCommit: true };
+  const results = await Promise.all(parents.map((p) => replay(p)));
+  const absentParents = parents.filter((_, i) => !results[i].present);
+  return { absentInSome: absentParents.length > 0, absentParents, parents, rootCommit: false };
+}
+
+// git's own convention when using `git revert` (no -n/--no-edit override):
+// "Revert \"<original subject>\"". Message alone is spoofable, so this is
+// only the FIRST half of detection — see detectRevert.
+const REVERT_MESSAGE_RE = /^Revert "/;
+
+/**
+ * A commit is a real revert only when its message matches git's own Revert
+ * convention AND its diff is a genuine structural inverse of an EARLIER
+ * candidate commit's diff (message-only detection is spoofable). Checked
+ * against each of `candidateShas` (typically the same candidate list the
+ * caller's walk already has, oldest-first) — the first one whose diff is the
+ * exact reverse wins.
+ */
+export function detectRevert(scanRoot, sha, candidateShas) {
+  if (!_isSha(sha)) return { isRevert: false, revertsCommit: null };
+  const meta = _run(scanRoot, ['show', '-s', '--no-textconv', '--format=%s', sha]);
+  if (!meta.ok || !REVERT_MESSAGE_RE.test(meta.stdout.trim())) {
+    return { isRevert: false, revertsCommit: null };
+  }
+  const thisDiff = commitDiff(scanRoot, sha);
+  if (!thisDiff) return { isRevert: false, revertsCommit: null };
+  const invertedThisDiff = _invertUnifiedDiff(thisDiff);
+  for (const candidate of candidateShas || []) {
+    if (candidate === sha) continue;
+    const candidateDiff = commitDiff(scanRoot, candidate);
+    if (candidateDiff && candidateDiff.trim() === invertedThisDiff.trim()) {
+      return { isRevert: true, revertsCommit: candidate };
+    }
+  }
+  return { isRevert: false, revertsCommit: null };
+}
+
+// Produce what the INVERSE of a `-U0` unified diff would look like, so it
+// can be string-compared against a candidate's real diff.
+//
+// DEVIATION FROM THE M3 BRIEF: the brief specified a per-LINE +/- swap
+// ("this is intentionally a simple line-level swap ... -U0 makes this
+// sufficient"). That is not sufficient — verified empirically against real
+// `git revert` output before shipping this version. A unified diff hunk
+// lists its removed lines as a BLOCK followed by its added lines as a
+// BLOCK (git's own convention, not something -U0 changes); a real reverse
+// diff swaps those two BLOCKS (additions become the new removal block,
+// removals become the new addition block, in their respective original
+// orders) — it does not swap each line's marker in place. For a hunk with
+// one removal and one addition (the common single-line-change case) a
+// per-line swap silently reverses the two lines' relative order versus
+// what git itself produces, so the string comparison in detectRevert never
+// matched a real revert: `-safe\n+eval(x)\n` inverted to `+safe\n-eval(x)\n`,
+// but git's actual reverse diff is `-eval(x)\n+safe\n`. The `index a..b`
+// header line's two blob hashes and a hunk header's `-x,y +p,q` ranges also
+// swap under a real reversal and were previously left untouched, which
+// mismatches too whenever the two commits touch different blobs (always,
+// in practice). This version fixes both: it groups each contiguous run of
+// -/+ content lines into a block and swaps the two blocks (not each line),
+// and it swaps the index-line hash pair and the hunk-header range pair.
+// Confirmed against both a single-line change and a two-hunk multi-line
+// change, string-compared to `git diff <new> <old>`'s real output.
+//
+// POST-REVIEW FIX (M3 §3.1 review, finding #1): a whole-file add or delete
+// was still mishandled. `git show -U0` on a commit that ADDS a file emits
+// `new file mode <mode>` and a `---`/`+++` pair of `--- /dev/null` /
+// `+++ b/<path>`; a commit that DELETES a file emits `deleted file mode
+// <mode>` and the mirror pair, `--- a/<path>` / `+++ /dev/null`. Neither
+// was touched before, so inverting an add-diff still read as an add (still
+// `new file mode`, still `--- /dev/null`), which never matches a real
+// delete diff and made `detectRevert` miss a revert-of-an-add or
+// revert-of-a-delete entirely (fails safe — under-detection, not
+// misattribution, but still a real gap `detectRevert` should not have).
+// Fixed by: swapping `new file mode` <-> `deleted file mode` line-for-line,
+// and — since the two file-mode header lines are independent per-line but
+// the `---`/`+++` pair must be read TOGETHER to know which side is
+// /dev/null — handling `---`/`+++` as a pair: an add's `--- /dev/null` +
+// `+++ b/<path>` becomes a delete's `--- a/<path>` + `+++ /dev/null`, and
+// vice versa; an ordinary modify's `--- a/<path>` + `+++ b/<path>` (neither
+// side /dev/null) is left as-is, matching the existing a/ b/ convention
+// that already made the plain-modify case direction-invariant. Confirmed
+// against real git output for both a file addition reverted (delete) and a
+// file deletion reverted (re-add), plus a regression check that the
+// existing plain-modify case is unaffected.
+function _invertUnifiedDiff(diffText) {
+  const lines = diffText.split('\n');
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.startsWith('new file mode ')) {
+      out.push('deleted file mode ' + line.slice('new file mode '.length));
+      i++;
+      continue;
+    }
+    if (line.startsWith('deleted file mode ')) {
+      out.push('new file mode ' + line.slice('deleted file mode '.length));
+      i++;
+      continue;
+    }
+    if (line.startsWith('index ')) {
+      const m = line.match(/^index ([0-9a-f]+)\.\.([0-9a-f]+)(.*)$/);
+      out.push(m ? `index ${m[2]}..${m[1]}${m[3]}` : line);
+      i++;
+      continue;
+    }
+    if (line.startsWith('@@')) {
+      const m = line.match(/^@@ -(\S+) \+(\S+) @@(.*)$/);
+      out.push(m ? `@@ -${m[2]} +${m[1]} @@${m[3]}` : line);
+      i++;
+      continue;
+    }
+    if (line.startsWith('--- ')) {
+      const next = lines[i + 1];
+      if (typeof next === 'string' && next.startsWith('+++ ')) {
+        const oldSide = line.slice(4);
+        const newSide = next.slice(4);
+        if (oldSide === '/dev/null' && newSide.startsWith('b/')) {
+          // Add -> inverted to a delete.
+          out.push('--- a/' + newSide.slice(2));
+          out.push('+++ /dev/null');
+        } else if (newSide === '/dev/null' && oldSide.startsWith('a/')) {
+          // Delete -> inverted to an add.
+          out.push('--- /dev/null');
+          out.push('+++ b/' + oldSide.slice(2));
+        } else {
+          // Ordinary modify: a/ and b/ labels are direction-invariant.
+          out.push(line);
+          out.push(next);
+        }
+        i += 2;
+        continue;
+      }
+      out.push(line);
+      i++;
+      continue;
+    }
+    if (line.startsWith('+++') || line.startsWith('diff ')) {
+      out.push(line);
+      i++;
+      continue;
+    }
+    if (line.startsWith('-') || line.startsWith('+')) {
+      const removals = [];
+      const additions = [];
+      while (i < lines.length && (lines[i].startsWith('-') || lines[i].startsWith('+'))) {
+        if (lines[i].startsWith('-')) removals.push(lines[i].slice(1));
+        else additions.push(lines[i].slice(1));
+        i++;
+      }
+      for (const a of additions) out.push('-' + a);
+      for (const r of removals) out.push('+' + r);
+      continue;
+    }
+    out.push(line);
+    i++;
+  }
+  return out.join('\n');
+}
+
+// `git cherry-pick -x` leaves this exact trailer format in the new commit's
+// message body: "(cherry picked from commit <full-or-abbrev-sha>)".
+const CHERRY_PICK_TRAILER_RE = /\(cherry picked from commit ([0-9a-f]{4,40})\)/;
+
+export function detectCherryPick(scanRoot, sha) {
+  if (!_isSha(sha)) return { isCherryPick: false, originalCommit: null };
+  const r = _run(scanRoot, ['show', '-s', '--no-textconv', '--format=%B', sha]);
+  if (!r.ok) return { isCherryPick: false, originalCommit: null };
+  const m = r.stdout.match(CHERRY_PICK_TRAILER_RE);
+  if (!m) return { isCherryPick: false, originalCommit: null };
+  return { isCherryPick: true, originalCommit: m[1] };
+}

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

@@ -0,0 +1,59 @@
+import { blameLine } from './git-evidence.js';
+import { EVIDENCE_ROLE } from './schema.js';
+
+// Second independent Finding Provenance PRD audit: `opts.removedGuard` and
+// `opts.secret` let coordinator.js tell this function WHICH question a
+// no-source/no-sink finding is actually answering, instead of every such
+// finding collapsing onto the generic `sink` role. Both are cheap,
+// coordinator-level hints — no new detector work:
+//   - `removedGuard` — set for a `missingControlCandidate` finding
+//     (today, rate-limit.js's routes) once `resolveMissingControl` has
+//     confirmed a present->absent transition. The finding's own file:line
+//     IS the site where the (now-removed) control was expected, so that
+//     single evidence node is `removed_guard`, not `sink`.
+//   - `secret` — set for every finding routed through the coordinator with
+//     `findingType: 'secret'`. A hardcoded-credential finding's evidence
+//     node names where the SECRET sits, not a taint sink.
+// `guard` and `config` are NOT wired: no current detector's evidence
+// naturally maps to either without new detector-side work (a "control is
+// PRESENT" observation, or a misconfigured-setting location) — see
+// schema.js's EVIDENCE_ROLE comment for the honest disclosure.
+export function attributeEvidence(scanRoot, finding, opts = {}) {
+  const nodes = [];
+  const push = (role, file, line) => {
+    if (!file || !line) return;
+    const blame = blameLine(scanRoot, file, line);
+    nodes.push({ role, path: file, line, commit: blame && !blame.uncommitted ? blame.commit : null });
+  };
+  const fallbackRole = opts.removedGuard
+    ? EVIDENCE_ROLE.REMOVED_GUARD
+    : opts.secret
+    ? EVIDENCE_ROLE.SECRET
+    : EVIDENCE_ROLE.SINK;
+
+  if (finding.source || finding.sink) {
+    if (finding.source) push(EVIDENCE_ROLE.SOURCE, finding.source.file || finding.file, finding.source.line);
+    if (finding.sink) push(EVIDENCE_ROLE.SINK, finding.sink.file || finding.file, finding.sink.line);
+  } else {
+    push(fallbackRole, finding.file, finding.line);
+  }
+
+  // `step.removedGuard` — a per-STEP (not whole-finding) removed-guard
+  // marker for a taint-flow backward slice, e.g. "a sanitizer that used to
+  // sit on this path is gone." Honest disclosure (second independent audit):
+  // no producer sets this today — `dataflow/backward.js`'s
+  // `annotateBackwardSlices` is the only `pathSteps` writer and only ever
+  // sets `{type, label, line}`, never `removedGuard`. Left in place as the
+  // intended hook for a future taint-based guard-removal detector; the
+  // finding-level `opts.removedGuard` hint above is the one currently-live
+  // path to a `removed_guard` node (the rate-limit / missing-control case,
+  // which has no `pathSteps` at all).
+  if (Array.isArray(finding.pathSteps)) {
+    for (const step of finding.pathSteps) {
+      const role = step.removedGuard ? EVIDENCE_ROLE.REMOVED_GUARD : EVIDENCE_ROLE.TRANSFORMATION;
+      push(role, step.file || finding.file, step.line);
+    }
+  }
+
+  return nodes;
+}

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

@@ -0,0 +1,310 @@
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { hardenGitArgs, hardenGitEnv } from '../../util/git-hardening.js';
+
+// 2s keeps a single call bounded for the common case; `-L`/`--follow` walks on a
+// very large history can be slower, at which point they just return an empty/
+// null result rather than blocking the caller — degrading gracefully was judged
+// preferable to a longer timeout that lets one pathological repo stall a scan.
+const GIT_TIMEOUT_MS = 2000;
+
+// Second independent Finding Provenance PRD audit (FR-PROV-024 / Section 8
+// control 3): this scanRoot is a SCANNED repository, not this project's own
+// trusted checkout — its .git/config is attacker-influenceable. Every git
+// invocation in this module MUST route through this one function so the
+// hardening applies uniformly; see util/git-hardening.js for what each flag
+// closes and why it was verified necessary.
+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 };
+  }
+}
+
+// Exported so other resolvers in this directory that build their own git
+// invocations (rather than adding a new wrapper function here) still route
+// path/revision arguments through the same validation, instead of
+// reimplementing it and risking drift — see missing-control-resolver.js.
+export function _relPath(scanRoot, file) {
+  const abs = path.resolve(scanRoot, file);
+  const rel = path.relative(scanRoot, abs);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  // Lexical containment alone isn't enough: `file` could be a symlink whose
+  // TARGET resolves outside scanRoot even though its own path lexically
+  // sits inside it. realpathSync follows every symlink in the chain; if the
+  // real (post-symlink) path escapes scanRoot, treat it the same as any
+  // other traversal attempt.
+  //
+  // realpathSync can throw for reasons other than "doesn't exist": ELOOP
+  // (a symlink cycle), EACCES (permission denied partway through
+  // resolution), ENOTDIR (a path component that should be a directory
+  // isn't). None of those have the "historical commit, file plausibly
+  // doesn't exist right now" excuse -- they mean something genuinely
+  // couldn't be verified, so they fail CLOSED (return null), matching
+  // every other fail-closed check in this module. ENOENT is the one
+  // exception and fails OPEN: most callers are asking about a file's state
+  // at some HISTORICAL commit, which git-evidence.js reads from git
+  // objects, not the working tree, so the working tree may not have this
+  // file at all, or may have it under a different name after a rename --
+  // that is routine and must not be treated as a proven escape.
+  try {
+    const real = fs.realpathSync(abs);
+    const realRoot = fs.realpathSync(scanRoot);
+    const realRel = path.relative(realRoot, real);
+    if (realRel === '' || realRel.startsWith('..') || path.isAbsolute(realRel)) return null;
+  } catch (e) {
+    if (e.code !== 'ENOENT') return null;
+  }
+  return rel.split(path.sep).join('/');
+}
+
+// Git SHAs (full or abbreviated) are always lowercase/uppercase hex, 4-40 chars.
+// Rejecting anything else closes off flag injection (e.g. a "sha" of
+// "--output=/tmp/pwned" reaching `git show`/`git log` as a bare argv token).
+const SHA_RE = /^[0-9a-f]{4,40}$/i;
+function _isSha(sha) {
+  return typeof sha === 'string' && SHA_RE.test(sha);
+}
+
+// `since` is only ever used as the left side of a `<since>..HEAD` revision
+// range, so it must look like a ref/tag/sha — never start with `-` (which
+// git would parse as an option) and contain only characters refs can hold.
+const SINCE_RE = /^[A-Za-z0-9._/-]+$/;
+export function _isSafeRevision(since) {
+  return typeof since === 'string' && since.length > 0 && !since.startsWith('-') && SINCE_RE.test(since);
+}
+
+export function isGitRepo(scanRoot) {
+  return _run(scanRoot, ['rev-parse', '--git-dir']).ok;
+}
+
+// FR-PROV-022: repository-identity signal for provider enrichment
+// (providers/github.js / providers/gitlab.js parse owner/repo out of this
+// URL). No `origin` remote (a local-only repo, or a fixture that never added
+// one) degrades to null rather than throwing — same convention as every
+// other `_run`-backed helper here.
+export function getRemoteUrl(scanRoot) {
+  const r = _run(scanRoot, ['remote', 'get-url', 'origin']);
+  return r.ok ? r.stdout.trim() : null;
+}
+
+export function getRepoState(scanRoot) {
+  if (!isGitRepo(scanRoot)) return null;
+  const head = _run(scanRoot, ['rev-parse', 'HEAD']);
+  const branch = _run(scanRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const dirty = _run(scanRoot, ['status', '--porcelain']);
+  const shallow = _run(scanRoot, ['rev-parse', '--is-shallow-repository']);
+  return {
+    head: head.ok ? head.stdout.trim() : null,
+    branch: branch.ok ? branch.stdout.trim() : null,
+    dirty: dirty.ok ? dirty.stdout.trim().length > 0 : false,
+    shallow: shallow.ok ? shallow.stdout.trim() === 'true' : false,
+  };
+}
+
+export function commitMeta(scanRoot, sha) {
+  if (!_isSha(sha)) return null;
+  // `--no-textconv`: verified this specific invocation (`-s`, no diff/blob
+  // content rendered) is NOT reachable via a hostile `.gitattributes`
+  // textconv driver in current git — kept for defense-in-depth /
+  // uniformity with every other `show` call in this module, not because a
+  // live exploit path was found here.
+  //
+  // `%P` (Task 6, provenance-second-audit-remediation): the parent-hash list,
+  // added to this SAME `show` call rather than requiring a second
+  // `getFirstParent` subprocess spawn right after this one — profiling the
+  // bench (bench/provenance/runner.mjs) found git subprocess spawn count,
+  // not the detector pipeline, is the dominant cost of provenance overhead
+  // (~6-8ms per `execFileSync('git', ...)` on the dev machine; the standard
+  // origin-resolver.js walk calls `getFirstParent` and `commitMeta` back to
+  // back for the identical sha on every candidate). Purely additive to the
+  // returned shape and to the existing `%x1f`-delimited format — no
+  // hardening flag changed, no existing field removed.
+  //
+  // `%P` SITS AT INDEX 1, IMMEDIATELY AFTER `%H`, AND MUST STAY THERE.
+  // It was first added at index 5 (after `%an`/`%ae`), which was a real,
+  // demonstrated vulnerability caught in review before release: git strips
+  // only `\n`/`<`/`>` from an ident, so a literal 0x1f inside an AUTHOR NAME
+  // survives `git commit` and shifts every later field left. An attacker who
+  // controls their own author name (an outside PR contributor is enough — no
+  // hostile clone, no crafted objects) could therefore choose the string this
+  // code reads as the first parent. That is not cosmetic: origin-resolver.js
+  // feeds `parents[0]` to `replay(parent)`, and a parent whose blobs cannot
+  // be fetched is INDISTINGUISHABLE from a parent that genuinely lacks the
+  // finding — so a spoofed or garbage value yields absentInParent=true,
+  // status:'complete', parentBoundaryVerified:true, and CONFIDENCE HIGH
+  // (0.95, `parent_absence_verified`) for a finding whose boundary was never
+  // actually verified. That is the exact "never false certainty" invariant in
+  // posture/CLAUDE.md, and these values reach signed evidence bundles.
+  //
+  // Only `%H` may precede it: 40 chars of git-generated hex, not
+  // attacker-influenceable. The residual shift risk on `authorName`/`summary`
+  // is pre-existing and cosmetic — those fields are display-only and feed no
+  // trust decision. Validating parents as hex (below) is defense in depth,
+  // NOT a substitute for the ordering: an attacker can supply valid hex.
+  const r = _run(scanRoot, ['show', '-s', '--no-textconv', '--format=%H%x1f%P%x1f%an%x1f%ae%x1f%aI%x1f%cI%x1f%s', sha]);
+  if (!r.ok) return null;
+  const [full, parentsRaw, authorName, authorEmail, authorDate, committerDate, summary] = r.stdout.trim().split('\x1f');
+  if (!full) return null;
+  // Every parent must look like a real object name. A non-hex entry here can
+  // only mean the record was malformed or tampered with, and silently
+  // accepting it is what turns a parse bug into a false HIGH-confidence
+  // verdict — drop the whole list rather than resolve against a value we
+  // cannot vouch for. `[]` is safe: it reads as "root commit", which
+  // origin-resolver.js treats as unverifiable, not as verified-absent.
+  const parents = parentsRaw ? parentsRaw.split(' ').filter(Boolean) : [];
+  const parentsValid = parents.every((p) => /^[0-9a-f]{4,40}$/i.test(p));
+  return {
+    commit: full, authorName, authorEmail, authorDate, committerDate, summary,
+    parents: parentsValid ? parents : [],
+  };
+}
+
+export function getFirstParent(scanRoot, sha) {
+  if (!_isSha(sha)) return null;
+  const r = _run(scanRoot, ['rev-parse', `${sha}^1`]);
+  return r.ok ? r.stdout.trim() : null;
+}
+
+// M3 §3.1: the full parent list, not just the first. `git rev-parse
+// <sha>^@` expands to every parent SHA, one per line — the same mechanism
+// `<sha>^1` (getFirstParent) uses for a single parent, generalized. A
+// commit with no parents (the repo root) returns empty stdout, which
+// `.filter(Boolean)` turns into `[]` rather than `['']`.
+export function getAllParents(scanRoot, sha) {
+  if (!_isSha(sha)) return [];
+  const r = _run(scanRoot, ['rev-parse', `${sha}^@`]);
+  if (!r.ok) return [];
+  return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+// M3 §3.1: the diff a commit introduces, as a normalized patch string — used
+// by dag-walk.js to confirm a claimed revert is a REAL structural inverse of
+// an earlier commit's diff, not just a commit whose MESSAGE says "Revert" (a
+// spoofable, unreliable signal on its own per the spec). `--no-color` and a
+// fixed context of 0 lines keep the two diffs comparable independent of
+// terminal/config state; `-U0` removes context lines so unrelated nearby
+// edits between the two commits don't defeat the comparison.
+export function commitDiff(scanRoot, sha) {
+  if (!_isSha(sha)) return null;
+  // `--no-textconv`: VERIFIED exploitable without it — a hostile
+  // `.gitattributes` `diff=<name>` attribute + a matching
+  // `diff.<name>.textconv` config value runs an attacker script on this
+  // exact invocation shape (`show -U0`, real diff content rendered). This
+  // is the call the second audit named explicitly.
+  const r = _run(scanRoot, ['show', '--no-color', '--no-textconv', '-U0', '--format=', sha]);
+  return r.ok ? r.stdout : null;
+}
+
+// M4 §4.2: does `ancestor` reach `descendant` by following parent links —
+// true for `ancestor === descendant` too, matching `git merge-base
+// --is-ancestor`'s own semantics. Used by cross-repo lineage continuation
+// (origin-resolver.js's `tryCrossRepoLineage`) to keep a candidate drawn from
+// the LINKED repo's own (possibly still-developing) history from resolving
+// to something that postdates the declared `atCommit` boundary — the
+// DECLARED lineage link only vouches for history up to and including
+// atCommit, never past it.
+export function isAncestor(scanRoot, ancestor, descendant) {
+  if (!_isSha(ancestor) || !_isSha(descendant)) return false;
+  return _run(scanRoot, ['merge-base', '--is-ancestor', ancestor, descendant]).ok;
+}
+
+export function getBlobAtCommit(scanRoot, sha, file) {
+  if (!_isSha(sha)) return null;
+  const rel = _relPath(scanRoot, file);
+  if (!rel) return null;
+  // `./` makes git resolve `rel` relative to cwd (scanRoot) rather than the
+  // repo root — load-bearing when scanRoot is a SUBDIRECTORY of the actual
+  // git repository (e.g. one package of a monorepo). Without it, `git show
+  // <sha>:<bare-relative-path>` resolves the bare path against the repo
+  // root and silently fails for every caller whose scanRoot != repo root.
+  //
+  // `--no-textconv`: verified this blob-cat form of `show` (`<sha>:<path>`,
+  // not a diff) is NOT reachable via a hostile textconv driver in current
+  // git — kept for defense-in-depth / uniformity, same as commitMeta above.
+  const r = _run(scanRoot, ['show', '--no-textconv', `${sha}:./${rel}`]);
+  return r.ok ? r.stdout : null;
+}
+
+export function candidateCommitsForLine(scanRoot, file, line, { since } = {}) {
+  const rel = _relPath(scanRoot, file);
+  if (!rel) return [];
+  if (since && !_isSafeRevision(since)) return [];
+  const args = ['log', '--format=commit %H', '--reverse'];
+  if (since) args.push(`${since}..HEAD`);
+  // `-L` renders per-commit line-history diff content, which VERIFIED goes
+  // through a hostile textconv driver the same way `commitDiff`'s `show
+  // -U0` does — `--no-textconv` is required here for the same real reason.
+  args.push('-L', `${line},${line}:${rel}`, '--no-textconv');
+  const r = _run(scanRoot, args);
+  if (!r.ok) return [];
+  const shas = [];
+  for (const ln of r.stdout.split('\n')) {
+    const m = ln.match(/^commit ([0-9a-f]{40})/);
+    if (m) shas.push(m[1]);
+  }
+  return [...new Set(shas)];
+}
+
+export function candidateCommitsForFile(scanRoot, file, { since } = {}) {
+  const rel = _relPath(scanRoot, file);
+  if (!rel) return [];
+  if (since && !_isSafeRevision(since)) return [];
+  const args = ['log', '--format=%H', '--follow', '--reverse'];
+  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 function resolveRevision(scanRoot, revision) {
+  if (!_isSafeRevision(revision)) return null;
+  const r = _run(scanRoot, ['rev-parse', revision]);
+  return r.ok ? r.stdout.trim() : null;
+}
+
+// The commit(s) HEAD's history walk treats as having no parent — the true
+// repository root in a full clone, or the shallow-clone graft boundary in a
+// `--depth=N` clone (git's history walk cannot tell the two apart without
+// separately consulting `.git/shallow`, and this project doesn't need to:
+// either way, it is precisely "as far back as this checkout can see").
+// `--max-parents=0` returns them oldest-reachable-first is NOT guaranteed by
+// git, so a caller wanting a single deterministic boundary should treat the
+// first line as "a" boundary commit, not "the" canonical one when there is
+// more than one (a repo with multiple disconnected roots, or more than one
+// shallow-grafted commit).
+export function getRootCommits(scanRoot) {
+  const r = _run(scanRoot, ['rev-list', '--max-parents=0', 'HEAD']);
+  if (!r.ok) return [];
+  return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+export function blameLine(scanRoot, file, line) {
+  const rel = _relPath(scanRoot, file);
+  if (!rel || !line || line < 1) return null;
+  // `--no-textconv`: VERIFIED exploitable without it — `git blame` applies
+  // a hostile `.gitattributes` textconv driver by default in current git.
+  const r = _run(scanRoot, ['blame', '-L', `${line},${line}`, '--porcelain', '--no-textconv', '--', rel]);
+  if (!r.ok || !r.stdout) return null;
+  const lines = r.stdout.split('\n');
+  const head = lines[0].split(' ');
+  const sha = head[0];
+  if (!sha) return null;
+  if (/^0+$/.test(sha)) return { commit: null, uncommitted: true };
+  const meta = { commit: sha };
+  for (const ln of lines) {
+    if (ln.startsWith('author ')) meta.authorName = ln.slice(7);
+    else if (ln.startsWith('author-mail ')) meta.authorEmail = ln.slice(12).replace(/[<>]/g, '');
+    else if (ln.startsWith('author-time ')) meta.authorDate = new Date(parseInt(ln.slice(12), 10) * 1000).toISOString();
+    else if (ln.startsWith('summary ')) meta.summary = ln.slice(8);
+  }
+  return meta;
+}