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

package/src/posture/provenance/origin-resolver.js

@@ -0,0 +1,342 @@
+// Candidate-seeded linear-replay origin resolution (Finding Provenance PRD,
+// Scenarios A/B/F).
+//
+// Given a finding, walk the commits git identifies as having touched its
+// line (oldest-first, via `candidateCommitsForLine`) and, for each one,
+// semantically replay the detector at that commit's blob content
+// (`predicate-replay.js`) to answer "did this finding's condition hold
+// here". The origin commit is the OLDEST candidate where the predicate is
+// present AND absent in that commit's first parent — i.e. the commit that
+// introduced it, not merely a commit that happens to contain it (a later
+// candidate might just be an unrelated edit to the same line that leaves
+// the vulnerable shape intact).
+//
+// The one subtlety this module exists to get right: a commit with no first
+// parent is ambiguous. It might genuinely be the repository's root commit
+// (real evidence: nothing precedes it, so "absent in parent" is vacuously
+// true) — or it might be the boundary of a SHALLOW clone, where a parent
+// exists in real history but was never fetched. Those two cases must never
+// be reported the same way: reporting a shallow boundary as `complete`
+// would be exactly the false certainty the PRD forbids (claiming to have
+// proven the finding wasn't present a commit earlier, when the truth is we
+// simply couldn't look). `repoState.shallow` is the caller-supplied signal
+// that disambiguates them; see the branch below for exactly how each is
+// handled.
+
+import { candidateCommitsForLine, commitMeta, getBlobAtCommit, isAncestor } from './git-evidence.js';
+import { replayAt } from './predicate-replay.js';
+import { PROVENANCE_METHOD } from './schema.js';
+import { checkAbsentInSomeParent, detectRevert, detectCherryPick } from './dag-walk.js';
+import { loadRepoLineage } from './repo-lineage.js';
+import { resolveAIAuthorship } from './ai-authorship.js';
+
+function relevantFiles(finding) {
+  const files = new Set();
+  if (finding.file) files.add(finding.file);
+  if (finding.source?.file) files.add(finding.source.file);
+  if (finding.sink?.file) files.add(finding.sink.file);
+  if (Array.isArray(finding.pathSteps)) {
+    for (const step of finding.pathSteps) if (step.file) files.add(step.file);
+  }
+  return [...files];
+}
+
+function originFrom(meta, { absentInParents }) {
+  return {
+    commit: meta.commit, authorName: meta.authorName, authorEmail: meta.authorEmail,
+    authorDate: meta.authorDate, committerDate: meta.committerDate, summary: meta.summary,
+    presentInCommit: true, absentInParents, revertOf: null, cherryPickOf: null,
+    aiAuthorship: resolveAIAuthorship(meta),
+  };
+}
+
+// Extracts line `lineNo` (1-based) from a blob, trimmed, or null if the blob
+// doesn't have that many lines or the line is blank. Shared by the initial
+// gate and the per-candidate walk in `tryCrossRepoLineage` below, so both
+// apply the exact same normalization.
+function trimmedLineAt(blob, lineNo) {
+  if (blob == null) return null;
+  const lines = blob.split('\n');
+  if (lineNo > lines.length) return null;
+  const text = lines[lineNo - 1];
+  if (!text || !text.trim()) return null;
+  return text.trim();
+}
+
+/**
+ * Best-effort cross-repo continuation when the standard walk reaches this
+ * repo's TRUE root commit (no parent, non-shallow) without resolving. Only
+ * fires when a repo-lineage link is declared and verified (`loadRepoLineage`
+ * — Task 4).
+ *
+ * A REAL content-presence check, not merely a non-blank-line check: the
+ * finding's OWN line text is read fresh from THIS repo at `rootMeta.commit`
+ * (the commit the standard walk actually resolved to) and compared, trimmed,
+ * against the linked repo's line at `atCommit`. Only an exact match is any
+ * evidence at all that "this same line of code" exists in the linked repo —
+ * an earlier version of this check merely asked "is *something* non-blank at
+ * this line index", which could fabricate an attribution for code that never
+ * existed in the linked repo at all (caught by review; see the M4 §4.2 fix
+ * commit). This is still a textual match, NOT a predicate replay — the
+ * detector pipeline that proved the finding's predicate true in THIS repo
+ * cannot be assumed identical in the linked one.
+ *
+ * The same comparison is applied PER CANDIDATE when walking
+ * `candidateCommitsForLine` in the linked repo (restricted to candidates
+ * reachable from atCommit, via `isAncestor`): `-L` tracks a LINE NUMBER's
+ * history, which can include commits where a completely unrelated statement
+ * occupied that same line number before/after the finding's actual code, so
+ * "oldest eligible candidate" alone is not evidence either — it must also be
+ * the oldest eligible candidate whose content at that line actually matches.
+ *
+ * Returns null on ANY failure to extend (no lineage, file/line absent or
+ * non-matching there, nothing further resolves) — the caller falls through
+ * to its existing not-linked-or-unresolved behavior unchanged.
+ *
+ * `deadlineAt` is the SAME budget `resolveOrigin` checks in its own loops
+ * ("one budget for the whole scan" — see posture/CLAUDE.md). This function
+ * spawns two git subprocesses per candidate against a SEPARATE repository
+ * whose history size this scan does not control, so it must honor the same
+ * deadline rather than running unbounded. A `null` return here just means
+ * "cross-repo lineage did not extend the answer" — the caller already falls
+ * through to the honest same-repo result, so an early bail-out degrades
+ * safely by construction.
+ */
+export function tryCrossRepoLineage(scanRoot, finding, rootMeta, deadlineAt) {
+  const lineage = loadRepoLineage(scanRoot);
+  if (!lineage) return null;
+
+  const lineNo = finding.line || finding.sink?.line;
+  if (!lineNo) return null;
+
+  // The real basis for comparison: THIS repo's own committed line text at
+  // the commit the standard walk resolved to — not a detector-supplied
+  // snippet, which could be stale, normalized, or absent.
+  const ownTrimmed = trimmedLineAt(getBlobAtCommit(scanRoot, rootMeta.commit, finding.file), lineNo);
+  if (!ownTrimmed) return null;
+
+  const linkedTrimmedAtBoundary = trimmedLineAt(getBlobAtCommit(lineage.path, lineage.atCommit, finding.file), lineNo);
+  if (linkedTrimmedAtBoundary !== ownTrimmed) return null;
+
+  if (deadlineAt && Date.now() > deadlineAt) return null;
+
+  const linkedCandidates = candidateCommitsForLine(lineage.path, finding.file, lineNo, {});
+  // Only candidates reachable from (at or before) atCommit are eligible —
+  // the lineage link says history was imported AT that commit, so anything
+  // the linked repo's own timeline added after it is not part of what
+  // became this repo. `isAncestor` (git-evidence.js, backed by `git
+  // merge-base --is-ancestor`) is true for atCommit itself as well as any
+  // real ancestor of it, so this both bounds the walk and keeps atCommit
+  // itself eligible.
+  //
+  // A plain `.filter()` can't early-exit, so a large linked-repo candidate
+  // list means one `git merge-base` per candidate with no aggregate cap —
+  // the same "one budget for the whole scan" gap the entry check above
+  // guards against, just one loop later. An explicit loop with the same
+  // deadline check closes it.
+  const eligible = [];
+  for (const sha of linkedCandidates) {
+    if (deadlineAt && Date.now() > deadlineAt) return null;
+    if (isAncestor(lineage.path, sha, lineage.atCommit)) eligible.push(sha);
+  }
+  if (eligible.length === 0) return null;
+
+  // Oldest-first: the first candidate whose OWN content at this line also
+  // matches is the real answer. A candidate that is merely eligible (reaches
+  // atCommit) but whose content at this line differs is not evidence of
+  // anything and must be skipped, not accepted for being oldest.
+  let meta = null;
+  for (const sha of eligible) {
+    if (deadlineAt && Date.now() > deadlineAt) return null;
+    const candidateTrimmed = trimmedLineAt(getBlobAtCommit(lineage.path, sha, finding.file), lineNo);
+    if (candidateTrimmed !== ownTrimmed) continue;
+    meta = commitMeta(lineage.path, sha);
+    if (meta) break;
+  }
+  if (!meta) return null;
+
+  return {
+    status: 'partial',
+    reason: 'cross-repo-lineage-best-effort',
+    commitsConsidered: eligible.length,
+    findingOrigin: originFrom(meta, { absentInParents: [] }),
+    method: PROVENANCE_METHOD.SEMANTIC_REPLAY,
+    crossRepoLineage: true,
+  };
+}
+
+export async function resolveOrigin(scanRoot, finding, { since, deadlineAt, repoState, mode } = {}) {
+  const file = finding?.file;
+  const line = finding?.line || finding?.sink?.line;
+  const stableId = finding?.stableId;
+  if (!file || !line || !stableId) {
+    return { status: 'not_available', reason: 'missing-file-line-or-stableId', commitsConsidered: 0 };
+  }
+
+  const candidates = candidateCommitsForLine(scanRoot, file, line, { since });
+  if (candidates.length === 0) {
+    return { status: 'not_available', reason: 'no-candidate-commits', commitsConsidered: 0 };
+  }
+
+  const files = relevantFiles(finding);
+  let commitsConsidered = 0;
+  // Second independent Finding Provenance PRD audit: the generic fallback
+  // reason at the bottom of this function ('predicate-never-confirmed-in-
+  // candidates') was reported for every kind of replay miss alike, including
+  // the specific rename-shaped one `bench/provenance-accuracy/fixtures/
+  // rename.mjs`'s header and `provenance-origin-resolver.test.js`'s
+  // "Rename-boundary honesty" test already traced precisely: `-L` has its
+  // own built-in rename tracing independent of `--follow` (verified in both
+  // places above), so a candidate this search returns for the finding's
+  // CURRENT path can legitimately be a commit where the content lived under
+  // an OLDER path — `replayAt`/`getBlobAtCommit` only ever look up the
+  // CURRENT path, so such a candidate reproducibly fails with
+  // `reason:'no-files-at-commit'` (`predicate-replay.js`), never
+  // `stableId-not-reproduced` (the "we looked at the right file and the
+  // predicate just wasn't true here" case). That distinction is already
+  // sitting in `presentHere.reason` below — no extra git call needed to
+  // surface it. This flag does NOT make the resolver follow the rename (that
+  // is the separately-scoped, honestly-disclosed engine gap); it only makes
+  // the fallback reason say which honest-miss shape actually occurred.
+  let renameShapedMiss = false;
+
+  // M2 §2.4 performance fix: within ONE resolveOrigin call, replayAt(sha) is
+  // pure given (scanRoot, sha, files, stableId) — all fixed for this call.
+  // The SAME sha is asked about twice whenever one candidate's first parent
+  // equals the previous candidate: candidate i's "presentHere" check IS
+  // candidate i+1's "presentInParent" check when parent(candidate i+1) ===
+  // candidate i, which is the common case for a file with no gaps in its
+  // edit history. Memoized here (not in predicate-replay.js itself) so the
+  // cache stays scoped to one finding's walk — a cross-finding cache is
+  // coordinator.js's job (Task 7), not this module's.
+  const replayCache = new Map();
+  const replay = (sha) => {
+    if (replayCache.has(sha)) return replayCache.get(sha);
+    const p = replayAt(scanRoot, sha, files, stableId);
+    replayCache.set(sha, p);
+    return p;
+  };
+
+  for (const sha of candidates) {
+    if (deadlineAt && Date.now() > deadlineAt) {
+      return { status: 'budget_exhausted', commitsConsidered };
+    }
+    commitsConsidered++;
+    const presentHere = await replay(sha);
+    if (!presentHere.present) {
+      if (presentHere.reason === 'no-files-at-commit') renameShapedMiss = true;
+      continue;
+    }
+
+    // Task 6 (provenance-second-audit-remediation): one `git show` call, not
+    // two — `commitMeta` now carries `parents` (see git-evidence.js), so the
+    // separate `getFirstParent(scanRoot, sha)` subprocess spawn this loop
+    // used to make for the SAME sha right before this line is gone. `<sha>^1`
+    // (what getFirstParent asked for) and `parents[0]` (the first token of
+    // `%P`) are the same first-parent semantics for both a normal and a
+    // merge commit.
+    const meta = commitMeta(scanRoot, sha);
+    if (!meta) continue;
+    const parent = meta.parents.length ? meta.parents[0] : null;
+
+    if (!parent) {
+      if (repoState && repoState.shallow) {
+        // Shallow boundary — cannot prove absence in a parent we cannot see.
+        // This is exactly the false-certainty case the PRD forbids.
+        return {
+          status: 'partial', reason: 'shallow-boundary-reached', commitsConsidered,
+          findingOrigin: originFrom(meta, { absentInParents: [] }),
+          method: PROVENANCE_METHOD.SEMANTIC_REPLAY,
+        };
+      }
+      // True repository root, non-shallow. Before settling for "no parent
+      // exists to verify absence in" (M2/M3's existing weaker-evidence
+      // path), try extending the walk into a declared cross-repo lineage
+      // link (M4 §4.2) — this repo's root may not be where the code was
+      // actually first written, just where THIS repo's history starts.
+      const crossRepo = tryCrossRepoLineage(scanRoot, finding, meta, deadlineAt);
+      if (crossRepo) return crossRepo;
+      // True repository root, non-shallow, no lineage link (or the link
+      // didn't extend the answer) — valid but weaker evidence: no parent
+      // exists to verify absence in, so parentBoundaryVerified stays false
+      // and confidence.js will cap this at MEDIUM.
+      return {
+        status: 'complete', method: PROVENANCE_METHOD.SEMANTIC_REPLAY, commitsConsidered,
+        findingOrigin: originFrom(meta, { absentInParents: [] }),
+        parentBoundaryVerified: false,
+      };
+    }
+
+    const presentInParent = await replay(parent);
+    const absentInParent = !presentInParent.present;
+    if (!absentInParent) continue; // predicate already true in parent — keep walking older candidates
+
+    return {
+      status: 'complete', method: PROVENANCE_METHOD.SEMANTIC_REPLAY, commitsConsidered,
+      findingOrigin: originFrom(meta, { absentInParents: [parent] }),
+      parentBoundaryVerified: true,
+    };
+  }
+
+  // M3 §3.1: `--provenance deep`. The standard walk above only ever checks a
+  // candidate's FIRST parent for absence — correct for linear history, but a
+  // vulnerability introduced via a merged feature branch can be absent from
+  // a NON-first parent while the first parent (inherited from mainline
+  // before the merge) already carries it — the standard check never looks
+  // past parents[0], so it never sees that other, absent parent. Deep mode
+  // re-checks the SAME candidates the standard walk already found, this
+  // time via `checkAbsentInSomeParent` — absence in AT LEAST ONE parent, not
+  // necessarily the first. See that function's own doc comment in
+  // dag-walk.js for why "any parent absent" (a strict superset of the
+  // first-parent-only check) is the correct generalization here, and why
+  // `checkAbsentInAllParents` (a strict SUBSET, used only for lifecycle
+  // safety checks elsewhere) can never resolve anything this retry couldn't
+  // already resolve via the primary loop above.
+  if (mode === 'deep') {
+    for (const sha of candidates) {
+      if (deadlineAt && Date.now() > deadlineAt) {
+        return { status: 'budget_exhausted', commitsConsidered };
+      }
+      const presentHere = await replay(sha);
+      if (!presentHere.present) continue;
+      commitsConsidered++;
+      const { absentInSome, absentParents, rootCommit } = await checkAbsentInSomeParent(scanRoot, sha, replay);
+      if (!absentInSome) continue;
+      const meta = commitMeta(scanRoot, sha);
+      if (!meta) continue;
+      if (rootCommit && repoState && repoState.shallow) {
+        return {
+          status: 'partial', reason: 'shallow-boundary-reached', commitsConsidered,
+          findingOrigin: originFrom(meta, { absentInParents: [] }),
+          method: PROVENANCE_METHOD.SEMANTIC_REPLAY,
+        };
+      }
+      const { isRevert, revertsCommit } = detectRevert(scanRoot, sha, candidates);
+      const { isCherryPick, originalCommit } = detectCherryPick(scanRoot, sha);
+      const origin = originFrom(meta, { absentInParents: absentParents });
+      origin.revertOf = isRevert ? revertsCommit : null;
+      origin.cherryPickOf = isCherryPick ? originalCommit : null;
+      return {
+        status: 'complete', method: PROVENANCE_METHOD.SEMANTIC_REPLAY, commitsConsidered,
+        findingOrigin: origin,
+        parentBoundaryVerified: !rootCommit,
+      };
+    }
+  }
+
+  // 'rename-detected-not-followed': at least one candidate's blob lookup
+  // failed with 'no-files-at-commit' — the specific, cheaply-observed shape
+  // that means git found this content living at a path other than the
+  // finding's current one, and this resolver never re-tries the lookup
+  // under an older name (see the comment on `renameShapedMiss` above). This
+  // does NOT mean every such miss IS a rename — the same shape could
+  // theoretically come from an unrelated path mismatch — only that it is
+  // never the generic "we looked at the right path and the predicate simply
+  // wasn't true" miss, so reporting the generic reason here would be
+  // actively misleading about WHAT the search looked at, not merely vague.
+  return {
+    status: 'partial',
+    reason: renameShapedMiss ? 'rename-detected-not-followed' : 'predicate-never-confirmed-in-candidates',
+    commitsConsidered,
+  };
+}

package/src/posture/provenance/predicate-replay.js

@@ -0,0 +1,133 @@
+// Historical-blob predicate replay (Finding Provenance PRD).
+//
+// Given a finding's stableId and the commit it is being investigated against,
+// answer "does this finding's condition hold at that point in history" by
+// re-running the FULL detector suite (`runFullScan`) scoped to just the
+// finding's file(s) at that commit's blob content, and checking whether the
+// same stableId reappears. This deliberately reuses the real pipeline instead
+// of hand-mapping a finding to one of 60+ detector modules — it costs a real
+// (if narrowly-scoped) scan, not a cheap pattern match, which is the tradeoff
+// `origin-resolver.js` (Task 6) accepts for correctness.
+
+import { runFullScan, _snapshotSuppressionLog, _restoreSuppressionLog } from '../../engine.js';
+import { computeStableId } from '../stable-id.js';
+import { getBlobAtCommit } from './git-evidence.js';
+
+// Task 11 concurrency fix: `coordinator.js` resolves several findings' origins
+// CONCURRENTLY (its own comment: "the scheduler runs these four at a time"),
+// and each finding's `resolveOrigin` walk can call `replayAt` more than once
+// sequentially -- so two DIFFERENT findings' replay calls can legitimately be
+// in flight at the same time, interleaved at `runFullScan`'s own internal
+// await points. `runFullScan` clears+writes a module-level suppression log
+// (engine.js's `_suppressionLog`) unconditionally on every call; a plain
+// snapshot/restore around one call is not safe under that interleaving.
+//
+// The actual failure shape (traced through, not guessed): call A snapshots
+// the outer log, then awaits its nested `runFullScan`, which resets the log
+// to empty and starts writing its OWN (nested-scan) entries. Before A's
+// nested call finishes, call B starts: B's snapshot now captures A's
+// in-progress nested state, not the outer scan's real log. When A finishes
+// and restores ITS (correct) snapshot, that's fine -- but B's `finally` then
+// restores what B snapshotted (A's nested state), overwriting A's correct
+// restore with garbage that belongs to neither scan. It is not simply "the
+// last restore wins" as a symmetric race between two correct values; the
+// corrupting snapshot (B's) was already wrong the moment it was taken,
+// because it read the log mid-mutation by a DIFFERENT nested scan.
+//
+// This queue serializes every `replayAt` call process-wide so the
+// snapshot -> runFullScan -> restore critical section below is never entered
+// by two calls at once -- call B cannot snapshot until call A has fully
+// restored, so B always sees a clean outer-scan log. Correctness over
+// throughput: `replayAt` is already the expensive path (a full nested scan
+// per call, ~39ms fixed overhead) and this queue only serializes that nested
+// scan itself, not the rest of each finding's concurrent resolution walk
+// (blame calls, cache reads, etc. all still run unserialized).
+//
+// Exported (test-only) so a dedicated regression test can drive this queue
+// directly and prove it serializes -- see
+// test/posture/provenance-secrets-logic.test.js's "_runExclusive serializes
+// concurrent critical sections" test, which fails if this queue is ever
+// removed or replaced with a no-op passthrough.
+let _replayQueue = Promise.resolve();
+export function _runExclusive(fn) {
+  const run = _replayQueue.then(fn, fn);
+  // Never let one rejected replay poison the queue for subsequent callers --
+  // `run`'s own rejection still propagates to ITS caller below.
+  _replayQueue = run.then(() => {}, () => {});
+  return run;
+}
+
+export async function replayAt(scanRoot, sha, files, targetStableId) {
+  const fileContents = {};
+  for (const f of files) {
+    const content = getBlobAtCommit(scanRoot, sha, f);
+    if (content != null) fileContents[f] = content;
+  }
+  if (Object.keys(fileContents).length === 0) {
+    return { present: false, reason: 'no-files-at-commit' };
+  }
+  let scan;
+  try {
+    scan = await _runExclusive(async () => {
+      // Task 11 reentrancy fix: `runFullScan` clears its module-level
+      // suppression log unconditionally at the top of every call. This
+      // function calls `runFullScan` recursively FROM WITHIN an outer, still-
+      // running scan's provenance resolution -- without a snapshot/restore
+      // around it, the nested call below silently wipes the OUTER scan's
+      // suppression log before its own return value reads it (found via
+      // `test/fixtures/entropy-fp`'s suppression count going to 0 once
+      // scan.secrets was wired into real provenance resolution and started
+      // reaching this recursive call for the first time). The nested scan's
+      // own suppression output is never read below, so nothing is lost by
+      // discarding it here. Safe from the concurrency hazard described above
+      // ONLY because this whole callback runs inside `_runExclusive`.
+      const _suppSnapshot = _snapshotSuppressionLog();
+      try {
+        // `provenance:false` is mandatory, not an optimisation: runFullScan
+        // now runs the provenance pass, which lands back here — an unbounded
+        // scan→provenance→replay→scan recursion that never returns. See the
+        // comment on runFullScan's signature.
+        //
+        // `skipAnnotators:true` (FR-PROV-029): this function only ever reads
+        // `scan.findings`/`scan.secrets` to recompute `computeStableId()`
+        // below — it never reads anything any of runFullScan's ~54 post-
+        // detection annotators set, nor the other finalization steps the
+        // same option also skips (secret dedup, orphan classification,
+        // freeze, checkpoint-close — see the guard comment in engine.js).
+        // Skipping all of it avoids paying its cost (measured ~39ms fixed
+        // overhead per call) on every one of the ~2 replay calls per finding
+        // the resolution walk already makes. Verified empirically (byte-
+        // identical computeStableId output with and without annotators, over
+        // a real scan) before this was wired in — see the FR-PROV-029 commit
+        // message for methodology.
+        return await runFullScan({ fileContents, scanRoot, provenance: false, skipAnnotators: true }, () => {});
+      } finally {
+        _restoreSuppressionLog(_suppSnapshot);
+      }
+    });
+  } catch (e) {
+    return { present: false, reason: 'replay-error' };
+  }
+  // scan.logicVulns is included here too (Task 11, PRD P0 secrets/logicVulns
+  // scope). This is safe even though scan.logicVulns includes the 3
+  // synthetic-line producers (license-policy:/deploy-platform:/stack-playbook:
+  // — fixed placeholder `line`, read scanRoot-level files directly rather than
+  // from the `fileContents` this replay scan is scoped to) because those
+  // producers are NEVER routed through resolveOrigin in the first place (see
+  // engine.js's isSyntheticLogicFinding classification) — replayAt is never
+  // asked to match against them. Their presence in this array when SOME OTHER
+  // finding's replay runs is harmless: they just won't match that other
+  // finding's stableId. Do NOT be tempted to wire ALL of scan.logicVulns
+  // through provenance without reading the plan this task came from — see
+  // docs/superpowers/plans/2026-08-28-finding-provenance-prd-completion.md's
+  // "Global Research Findings" section.
+  const candidates = [...(scan.findings || []), ...(scan.secrets || []), ...(scan.logicVulns || [])];
+  for (const f of candidates) {
+    let sid;
+    try { sid = computeStableId(f); } catch { continue; }
+    if (sid === targetStableId) {
+      return { present: true, replayedFinding: f };
+    }
+  }
+  return { present: false, reason: 'stableId-not-reproduced' };
+}

package/src/posture/provenance/providers/config.js

@@ -0,0 +1,39 @@
+// Shared opt-in config resolution for provider enrichment (Finding
+// Provenance PRD, M3 §3.4). Strictly opt-in: with neither an env var nor a
+// config file present, resolveProviderConfig returns null and NEITHER
+// providers/github.js nor providers/gitlab.js makes any network call —
+// this is the property provenance-providers.test.js's hermeticity test
+// proves. Modeled on llm-validator/index.js's existing
+// AGENTIC_SECURITY_LLM_ENDPOINT precedent (opt-in via env var, degrades to
+// a no-op when unset) rather than inventing a new convention.
+import * as fs from 'node:fs';
+import { statePath } from '../../state-dir.js';
+import { load as loadYaml } from '../../../util/yaml.js';
+
+const ENV_VAR_BY_PROVIDER = { github: 'AGENTIC_SECURITY_GITHUB_TOKEN', gitlab: 'AGENTIC_SECURITY_GITLAB_TOKEN' };
+
+/**
+ * `provider` is 'github' | 'gitlab'. Returns {token, baseUrl} or null.
+ * Env var wins if both are present — the same "explicit beats inferred"
+ * precedent config-resolution follows elsewhere in this codebase (e.g.
+ * state-dir.js's caller-supplied-scanRoot-wins-over-cwd-walk).
+ */
+export function resolveProviderConfig(scanRoot, provider) {
+  const envVar = ENV_VAR_BY_PROVIDER[provider];
+  const envToken = envVar ? process.env[envVar] : undefined;
+  if (envToken) return { token: envToken, baseUrl: null };
+
+  // .agentic-security/provenance-providers.yml — NOT gated behind
+  // stateWritesEnabled()/isSafeStateDir() the way STATE WRITES are; this is
+  // a READ of an operator-authored config file, the same class of read
+  // rules.yml already performs unconditionally.
+  const configPath = statePath(scanRoot, 'provenance-providers.yml');
+  let text;
+  try { text = fs.readFileSync(configPath, 'utf8'); } catch { return null; }
+  let doc;
+  try { doc = loadYaml(text); } catch { return null; }
+  if (!doc || typeof doc !== 'object') return null;
+  const entry = doc[provider];
+  if (!entry || !entry.token) return null;
+  return { token: entry.token, baseUrl: entry.baseUrl || null };
+}

package/src/posture/provenance/providers/github.js

@@ -0,0 +1,62 @@
+// GitHub provider enrichment (Finding Provenance PRD, M3 §3.4). Strictly
+// opt-in — see config.js's resolveProviderConfig. Every export returns null
+// immediately, with zero network calls, when unconfigured.
+import { resolveProviderConfig } from './config.js';
+
+const DEFAULT_API_BASE = 'https://api.github.com';
+
+function ownerRepoFromRemote(remoteUrl) {
+  // Handles both "git@github.com:owner/repo.git" and
+  // "https://github.com/owner/repo.git" — the two forms `git remote -v`
+  // actually produces.
+  const m = String(remoteUrl || '').match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  return m ? { owner: m[1], repo: m[2] } : null;
+}
+
+export async function fetchPRMetadata(scanRoot, commitSha, remoteUrl, config) {
+  if (!config || !config.token) return null;
+  const or = ownerRepoFromRemote(remoteUrl);
+  if (!or) return null;
+  const base = config.baseUrl || DEFAULT_API_BASE;
+  try {
+    const r = await fetch(`${base}/repos/${or.owner}/${or.repo}/commits/${commitSha}/pulls`, {
+      headers: { Authorization: `Bearer ${config.token}`, Accept: 'application/vnd.github+json' },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!r.ok) return null;
+    const prs = await r.json();
+    if (!Array.isArray(prs) || prs.length === 0) return null;
+    const pr = prs[0];
+    return {
+      prNumber: pr.number,
+      reviewers: (pr.requested_reviewers || []).map((u) => u.login),
+      approvals: null, // GitHub's PR-list-by-commit endpoint doesn't include review state; a real approvals count needs a second call, deliberately not made here to keep this a single-request enrichment.
+      mergedAt: pr.merged_at || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchCodeowners(scanRoot, remoteUrl, config) {
+  if (!config || !config.token) return null;
+  const or = ownerRepoFromRemote(remoteUrl);
+  if (!or) return null;
+  const base = config.baseUrl || DEFAULT_API_BASE;
+  for (const path of ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS']) {
+    try {
+      const r = await fetch(`${base}/repos/${or.owner}/${or.repo}/contents/${path}`, {
+        headers: { Authorization: `Bearer ${config.token}`, Accept: 'application/vnd.github+json' },
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!r.ok) continue;
+      const body = await r.json();
+      if (!body.content) continue;
+      const text = Buffer.from(body.content, 'base64').toString('utf8');
+      return text.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+    } catch { continue; }
+  }
+  return null;
+}
+
+export { resolveProviderConfig };

package/src/posture/provenance/providers/gitlab.js

@@ -0,0 +1,58 @@
+// GitLab provider enrichment (Finding Provenance PRD, M3 §3.4). Same
+// contract as providers/github.js — strictly opt-in, zero network calls
+// when unconfigured.
+import { resolveProviderConfig } from './config.js';
+
+const DEFAULT_API_BASE = 'https://gitlab.com/api/v4';
+
+function projectPathFromRemote(remoteUrl) {
+  const m = String(remoteUrl || '').match(/gitlab\.com[:/](.+?)(?:\.git)?$/);
+  return m ? m[1] : null;
+}
+
+export async function fetchPRMetadata(scanRoot, commitSha, remoteUrl, config) {
+  if (!config || !config.token) return null;
+  const projectPath = projectPathFromRemote(remoteUrl);
+  if (!projectPath) return null;
+  const base = config.baseUrl || DEFAULT_API_BASE;
+  const encodedProject = encodeURIComponent(projectPath);
+  try {
+    const r = await fetch(`${base}/projects/${encodedProject}/repository/commits/${commitSha}/merge_requests`, {
+      headers: { 'PRIVATE-TOKEN': config.token },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!r.ok) return null;
+    const mrs = await r.json();
+    if (!Array.isArray(mrs) || mrs.length === 0) return null;
+    const mr = mrs[0];
+    return {
+      prNumber: mr.iid,
+      reviewers: (mr.reviewers || []).map((u) => u.username),
+      approvals: typeof mr.upvotes === 'number' ? mr.upvotes : null,
+      mergedAt: mr.merged_at || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchCodeowners(scanRoot, remoteUrl, config) {
+  if (!config || !config.token) return null;
+  const projectPath = projectPathFromRemote(remoteUrl);
+  if (!projectPath) return null;
+  const base = config.baseUrl || DEFAULT_API_BASE;
+  const encodedProject = encodeURIComponent(projectPath);
+  try {
+    const r = await fetch(`${base}/projects/${encodedProject}/repository/files/CODEOWNERS/raw?ref=HEAD`, {
+      headers: { 'PRIVATE-TOKEN': config.token },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!r.ok) return null;
+    const text = await r.text();
+    return text.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+  } catch {
+    return null;
+  }
+}
+
+export { resolveProviderConfig };