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

package/src/posture/provenance/repo-lineage.js

@@ -0,0 +1,74 @@
+// Cross-repository lineage declaration (Finding Provenance PRD, M4 §4.2).
+//
+// Git has no native cross-repo history — this is an OPERATOR-DECLARED link,
+// read from .agentic-security/repo-lineage.json:
+//   { "linkedFrom": { "path": "../old-repo-clone", "atCommit": "<sha>" } }
+//
+// Scoped to LOCAL clones only — no remote fetch, matching this codebase's
+// "no runtime cloud calls" convention. Never throws; a missing, malformed,
+// or unreachable link degrades to null, which origin-resolver.js reads as
+// "no lineage available" and proceeds exactly as it did before M4.
+//
+// NOTE on git-evidence.js reuse (checked as of M3's final fix round, and
+// re-checked against the file's FULL export surface after a review caught
+// an incomplete first pass): `_isSha` and its `GIT_TIMEOUT_MS` constant are
+// NOT exported there (both are module-local), and the two exported
+// low-level helpers (`_relPath`, `_isSafeRevision`) genuinely don't fit —
+// `_isSafeRevision` intentionally accepts ref/branch names, looser than the
+// full-SHA-only check `atCommit` needs, and `_relPath` resolves paths
+// relative to `scanRoot`, which is the wrong side of this module's job
+// (validating a path OUTSIDE scanRoot). BUT two of the file's HIGHER-level
+// exports are directly reusable and are used below instead of being
+// reimplemented: `isGitRepo(scanRoot)` treats its argument purely as a cwd
+// for `git rev-parse --git-dir`, with no assumption that cwd is "the"
+// scanned repo, so it works unchanged on the linked repo's path; and
+// `commitMeta(scanRoot, sha)` already runs `atCommit` through the file's own
+// hardened `_isSha` guard before ever invoking `git show`, and returns
+// `null` on both an invalid shape and a nonexistent commit — exactly what
+// this module's existence check needs, with real commit metadata as a
+// bonus. See the M3 §3.3 finding in missing-control-resolver.js's history
+// for what skipping this check cost there.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isGitRepo, commitMeta } from './git-evidence.js';
+import { statePath } from '../state-dir.js';
+
+// Kept as a local pre-check, deliberately NOT dropped even though
+// `commitMeta` re-validates internally: this regex must reject an
+// unsafe-looking `atCommit` (e.g. `--upload-pack=evil`) BEFORE the value is
+// even handed to `commitMeta`/`isGitRepo`, so the argument-injection defense
+// fires as the first line of defense rather than relying solely on a
+// downstream module's own guard.
+const SHA_RE = /^[0-9a-f]{4,40}$/i;
+
+/**
+ * Returns { path: <absolute, verified-reachable local git repo>, atCommit: <verified-existing sha> }
+ * or null on ANY problem — missing config, malformed JSON, missing fields,
+ * an unsafe-looking atCommit, a path that isn't a real local git repo, or a
+ * commit that doesn't exist there. This function's whole job is to hand
+ * back either a fully-verified link or nothing; it never hands back a
+ * half-verified one for a caller to trust blindly.
+ */
+export function loadRepoLineage(scanRoot) {
+  const configPath = statePath(scanRoot, 'repo-lineage.json');
+  let text;
+  try { text = fs.readFileSync(configPath, 'utf8'); } catch { return null; }
+  let doc;
+  try { doc = JSON.parse(text); } catch { return null; }
+  const linked = doc?.linkedFrom;
+  if (!linked || typeof linked !== 'object') return null;
+  const { path: relOrAbsPath, atCommit } = linked;
+  if (typeof relOrAbsPath !== 'string' || !relOrAbsPath) return null;
+  if (typeof atCommit !== 'string' || !SHA_RE.test(atCommit)) return null;
+
+  const absPath = path.isAbsolute(relOrAbsPath) ? relOrAbsPath : path.resolve(scanRoot, relOrAbsPath);
+  // No separate fs.statSync/isDirectory pre-check: isGitRepo's underlying
+  // `git rev-parse --git-dir` call already degrades to false (not a throw)
+  // when `absPath` doesn't exist at all — verified directly rather than
+  // assumed — so a second existence check here would just be the same
+  // reimplementation-avoidance lesson applied halfway.
+  if (!isGitRepo(absPath)) return null;
+  if (commitMeta(absPath, atCommit) === null) return null;
+
+  return { path: absPath, atCommit };
+}

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

@@ -0,0 +1,139 @@
+import * as crypto from 'node:crypto';
+import { candidateCommitsForFile, getFirstParent, getBlobAtCommit, commitMeta } from './git-evidence.js';
+import { PROVENANCE_METHOD } from './schema.js';
+
+function parseSemver(v) {
+  const m = String(v || '').replace(/^[^\d]*/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+
+function cmpSemver(a, b) {
+  for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] - b[i]; }
+  return 0;
+}
+
+export function versionInRange(version, range) {
+  const v = parseSemver(version);
+  if (!v) return false;
+  if (range.introduced) {
+    const lo = parseSemver(range.introduced);
+    if (lo && cmpSemver(v, lo) < 0) return false;
+  }
+  if (range.fixed) {
+    const hi = parseSemver(range.fixed);
+    if (hi && cmpSemver(v, hi) >= 0) return false;
+  }
+  return true;
+}
+
+export function scaStableId(entry) {
+  const material = `${entry.osvId || ''}|${entry.name || ''}|${entry.ecosystem || ''}|${(entry.filePath || '').split('/').slice(-2).join('/')}`;
+  return crypto.createHash('sha256').update(material).digest('hex').slice(0, 16);
+}
+
+function extractDeclaredVersion(blobText, depName, filePath) {
+  const base = filePath.split('/').pop();
+  if (base === 'package.json') {
+    try {
+      const d = JSON.parse(blobText);
+      return (d.dependencies && d.dependencies[depName]) || (d.devDependencies && d.devDependencies[depName]) || null;
+    } catch {
+      return null;
+    }
+  }
+  if (/^requirements(?:[._-][\w.-]+)?\.txt$/i.test(base)) {
+    for (const line of blobText.split('\n')) {
+      const m = line.trim().match(/^([A-Za-z0-9_.-]+)\s*[=~<>!]+\s*([^\s;#,]*)/);
+      if (m && m[1].toLowerCase() === depName.toLowerCase()) return m[2];
+    }
+    return null;
+  }
+  return null;
+}
+
+function originResult({ meta, commitsConsidered, absentInParents, parentBoundaryVerified }) {
+  return {
+    status: 'complete', method: PROVENANCE_METHOD.DEPENDENCY_GRAPH_DIFF, commitsConsidered,
+    findingOrigin: { commit: meta.commit, authorName: meta.authorName, authorEmail: meta.authorEmail,
+      authorDate: meta.authorDate, committerDate: meta.committerDate, summary: meta.summary,
+      presentInCommit: true, absentInParents },
+    parentBoundaryVerified,
+  };
+}
+
+export async function resolveDirectSCAOrigin(scanRoot, scaEntry, { since, deadlineAt } = {}) {
+  const file = scaEntry.filePath;
+  if (!file) return { status: 'not_available', reason: 'no-manifest-path', commitsConsidered: 0 };
+
+  const candidates = candidateCommitsForFile(scanRoot, file, { since });
+  if (candidates.length === 0) return { status: 'not_available', reason: 'no-candidate-commits', commitsConsidered: 0 };
+
+  const range = { introduced: null, fixed: (scaEntry.fixedVersions || [])[0] || null };
+  let commitsConsidered = 0;
+  // With no `introduced` lower bound, `versionInRange` treats any version below
+  // `fixed` as "in range" (by design — see the versionInRange unit test: a
+  // fixed-only range means "vulnerable since inception"). That makes two
+  // distinct real-world situations indistinguishable by pure range membership:
+  // (1) a genuinely safer earlier version that nonetheless also falls below
+  // `fixed`, later bumped into the actually-vulnerable value, vs. (2) a
+  // routine patch-level bump (e.g. a dependabot PR) that moves the declared
+  // version WITHIN an already-vulnerable window. Both look identical as
+  // "parent in range, child in range, version string differs" — there is no
+  // way to tell them apart without an introduced bound. So a parent whose
+  // version is ALSO in-range is never treated as a confirmed transition (that
+  // would misattribute case 2 to the bump commit — a Critical bug caught in
+  // review: reporting `parentBoundaryVerified:true` at a routine patch bump
+  // when the dependency was vulnerable from the very first commit). Instead
+  // it's an unresolved ambiguity, and it downgrades even a root-commit
+  // fallback claim to `partial` rather than asserting a possibly-wrong commit
+  // with high confidence — the two situations render identically because they
+  // ARE identical given only a `fixed` version and no lower bound.
+  let rootFallback = null;
+  let ambiguousBump = false;
+
+  for (const sha of candidates) {
+    if (deadlineAt && Date.now() > deadlineAt) return { status: 'budget_exhausted', commitsConsidered };
+    commitsConsidered++;
+    const blob = getBlobAtCommit(scanRoot, sha, file);
+    if (blob == null) continue;
+    const declaredVersion = extractDeclaredVersion(blob, scaEntry.name, file);
+    if (!declaredVersion || !versionInRange(declaredVersion, range)) continue;
+
+    const parent = getFirstParent(scanRoot, sha);
+    if (!parent) {
+      if (!rootFallback) {
+        const meta = commitMeta(scanRoot, sha);
+        if (meta) rootFallback = meta;
+      }
+      continue;
+    }
+
+    const parentBlob = getBlobAtCommit(scanRoot, parent, file);
+    const parentVersion = parentBlob ? extractDeclaredVersion(parentBlob, scaEntry.name, file) : null;
+    const parentOutOfRange = !parentVersion || !versionInRange(parentVersion, range);
+    if (!parentOutOfRange) {
+      // Parent was already in the vulnerable range too. If the declared value
+      // actually changed here, this is the ambiguous "still-vulnerable bump"
+      // case described above — never attribute origin to it, and don't trust
+      // an earlier root fallback either, since it proves the history isn't as
+      // clean as a single unchanging value since repo creation.
+      if (parentVersion !== declaredVersion) ambiguousBump = true;
+      continue;
+    }
+
+    const meta = commitMeta(scanRoot, sha);
+    if (!meta) continue;
+    return originResult({ meta, commitsConsidered, absentInParents: [parent], parentBoundaryVerified: true });
+  }
+
+  if (rootFallback && !ambiguousBump) {
+    return originResult({ meta: rootFallback, commitsConsidered, absentInParents: [], parentBoundaryVerified: false });
+  }
+
+  return {
+    status: 'partial',
+    reason: ambiguousBump ? 'ambiguous-range-no-introduced-bound' : 'version-never-confirmed-in-candidates',
+    commitsConsidered,
+  };
+}

package/src/posture/provenance/schema.js

@@ -0,0 +1,255 @@
+import * as crypto from 'node:crypto';
+
+export const FINDING_PROVENANCE_SCHEMA_VERSION = '1.0';
+
+export const PROVENANCE_STATUS = Object.freeze({
+  COMPLETE: 'complete',
+  PARTIAL: 'partial',
+  NOT_AVAILABLE: 'not_available',
+  UNCOMMITTED: 'uncommitted',
+  BUDGET_EXHAUSTED: 'budget_exhausted',
+  ERROR: 'error',
+});
+
+export const PROVENANCE_METHOD = Object.freeze({
+  SEMANTIC_REPLAY: 'semantic-history-replay',
+  DEPENDENCY_GRAPH_DIFF: 'dependency-graph-diff',
+  LINE_ATTRIBUTION: 'line-attribution',
+  SCAN_HISTORY: 'scan-history',
+  // FR-PROV-017: a missing-control-resolver.js regression — "commit removed a
+  // previously-present safeguard" — not a code-INTRODUCTION event, so it is
+  // kept distinct from SEMANTIC_REPLAY (which always names the commit that
+  // introduced a bad pattern). A reader relying on `method` to interpret what
+  // `findingOrigin` means must be able to tell the two apart.
+  MISSING_CONTROL_REGRESSION: 'missing-control-regression',
+  NONE: 'none',
+});
+
+export const CONFIDENCE_LEVEL = Object.freeze({ HIGH: 'high', MEDIUM: 'medium', LOW: 'low', UNKNOWN: 'unknown' });
+
+// PRD Section 8 "Compliance evidence boundary" — REQUIRED DISCLAIMER, verbatim.
+// Second independent audit (2026-08-29): this exact sentence appeared nowhere
+// in shipped code or docs. It is distinct from evidence-grade-wording.js's
+// EVIDENCE_GRADE_DISCLAIMER_SHORT (which disclaims the WALKTHROUGH narrative
+// as a whole — "this isn't a certification/attestation") — this one disclaims
+// what git PROVENANCE data specifically can and cannot support once it is
+// used as compliance evidence. Any renderer that surfaces a findingProvenance-
+// derived fact (an origin commit, an author, a confidence level) alongside a
+// compliance claim must show this next to it. Kept verbatim per the PRD
+// rather than paraphrased, so a reader comparing this tool's output against
+// the PRD text can confirm the boundary was actually implemented.
+export const PROVENANCE_COMPLIANCE_DISCLAIMER =
+  'Provenance establishes repository history for technical evidence. It does not prove ' +
+  'developer intent, control operation outside code, organizational compliance, or certification.';
+
+// Second independent Finding Provenance PRD audit: this enum is the PRD's
+// full role vocabulary, but not every value has a producer. Honest status
+// per role, so a reader does not assume "defined here" means "emitted
+// somewhere".
+//
+// LIVE (something in src/ actually constructs one): SOURCE, SINK,
+// TRANSFORMATION (evidence-attribution.js's source/sink/pathSteps walk);
+// MANIFEST (coordinator.js's SCA evidence node); REMOVED_GUARD via the
+// missingControlCandidate hint (rate-limit.js's routes,
+// evidence-attribution.js's `opts.removedGuard`); SECRET via the
+// `findingType: 'secret'` hint (`opts.secret`).
+//
+// DECLARED BUT EMITTED BY NOTHING: GUARD ("a control IS present at this
+// location"), CONFIG ("a misconfigured setting, not a taint sink"),
+// LOCKFILE, and OTHER. Verified by grep, not assumed. Wiring GUARD or
+// CONFIG would mean new detector-side work (a "guard present" evidence
+// producer, or classifying which SAST findings are config-shaped), out of
+// scope for a schema-fidelity fix. LOCKFILE is the subtler one and the
+// reason this list is spelled out rather than summarized: the transitive-SCA
+// path IS lockfile-diff-derived, so it reads as though it should emit
+// LOCKFILE — but coordinator.js labels both the direct and transitive SCA
+// evidence nodes MANIFEST, so LOCKFILE has no producer at all. (An earlier
+// version of this very comment grouped it with the live roles; a review
+// caught it. The failure mode this comment exists to prevent is easy to
+// reintroduce inside the comment itself — check `grep -rn
+// "EVIDENCE_ROLE.<NAME>" src/` before moving any role between these lists.)
+//
+// None of these are dead in the sense of unreachable code — the enum values
+// and their consumers (`validate.js` callers, PRD-shaped JSON readers) are
+// correct — they are simply never produced today.
+export const EVIDENCE_ROLE = Object.freeze({
+  SOURCE: 'source', SINK: 'sink', GUARD: 'guard', REMOVED_GUARD: 'removed_guard',
+  TRANSFORMATION: 'transformation', CONFIG: 'config', SECRET: 'secret',
+  MANIFEST: 'manifest', LOCKFILE: 'lockfile', OTHER: 'other',
+});
+
+// M3: the AGE_BASIS enum, re-added now that M2 shipped its two consumers
+// (mttr.js's ageBasis field, fix-history.js's provenanceAtFix.ageBasis) —
+// both previously used bare string literals matching this vocabulary
+// without importing a shared source of truth for it.
+export const AGE_BASIS = Object.freeze({
+  FINDING_ORIGIN: 'finding_origin',
+  EARLIEST_OBSERVABLE: 'earliest_observable',
+  FIRST_OBSERVED: 'first_observed',
+  UNCOMMITTED: 'uncommitted',
+});
+
+// The `['complete', 'uncommitted']` "provenance is healthy enough to trust"
+// check independently existed in TWO places (bin/agentic-security.js's
+// --require-provenance block and pipeline/assurance-mode.js's strict check),
+// both re-deriving the same status set locally; unified into this one shared
+// predicate, so a future change to what counts as "healthy" is a one-line
+// edit, not a grep-and-fix-N-places. mttr.js's/fix-history.js's ageBasis
+// tiering is a DIFFERENT thing — it buckets a finding's age basis for
+// reporting, not a healthy/unhealthy gate — and was never converted to use
+// this predicate; do not conflate the two.
+export function isProvenanceHealthy(findingProvenance) {
+  return ['complete', 'uncommitted'].includes(findingProvenance?.status);
+}
+
+export function emptyProvenance(status, extra = {}) {
+  return {
+    schemaVersion: FINDING_PROVENANCE_SCHEMA_VERSION,
+    status,
+    findingOrigin: null,
+    branchIntroduction: null,
+    // FR-PROV-022: PR/reviewer/CODEOWNERS metadata is a distinct concern from
+    // "which commit/branch introduced this" (branchIntroduction) — a sibling
+    // top-level field, not nested inside it, matching this schema's existing
+    // convention of keeping origin/branch-entry/evidence-attribution as
+    // separate top-level objects. Populated only when a provider is
+    // configured AND a PR/MR was actually found for the origin commit;
+    // otherwise stays at this default (never a half-filled object).
+    providerEnrichment: null,
+    firstObserved: null,
+    evidenceAttribution: [],
+    method: PROVENANCE_METHOD.NONE,
+    confidence: { level: CONFIDENCE_LEVEL.UNKNOWN, score: 0, reasons: [] },
+    historyCoverage: { complete: false, shallow: false, boundaryCommit: null, commitsConsidered: 0, crossRepoLineage: false },
+    analysisBasis: { head: null, ruleset: null, detector: null, dirty: false },
+    limitations: [],
+    evidenceDigest: null,
+    ...extra,
+  };
+}
+
+/**
+ * A stable, one-way pseudonym for an author -- PRD Section 8: "support
+ * organization policy to pseudonymize names while retaining an internal
+ * stable identity reference." Keyed on email when available (more stable
+ * across commits than a display name, which can vary in capitalization or
+ * formatting across different commits by the same person) with a fallback
+ * to name alone. Deterministic: the SAME author always gets the SAME
+ * pseudonym within one run (and across runs, since it's a pure function of
+ * the input, not randomized) -- this is what "stable identity reference"
+ * means: a reader can tell "these five findings share an author" without
+ * learning who that author is.
+ */
+export function pseudonymizeAuthor(authorName, authorEmail) {
+  const key = authorEmail || authorName || '';
+  if (!key) return 'Contributor-unknown';
+  const hash = crypto.createHash('sha256').update(key).digest('hex').slice(0, 8);
+  return `Contributor-${hash}`;
+}
+
+// Fix-round item 3: `providerEnrichment` (FR-PROV-022) carries reviewer
+// logins and raw CODEOWNERS lines -- both routinely name real people
+// (GitHub/GitLab usernames as `@handle`s, and CODEOWNERS lines commonly
+// embed plain email addresses too) -- but were never touched by
+// `redactFindingProvenance`, so `--pseudonymize-authors` redacted
+// `findingOrigin.authorName` while `providerEnrichment.reviewers`/
+// `codeowners` still carried real identities in plain text through
+// `.agentic-security/findings.json` and SARIF. Same two knobs as
+// `redactOrigin` below: `includeEmail` gates raw email ADDRESSES embedded in
+// a codeowners line (withheld by default, same precedent as
+// `origin.authorEmail`); `pseudonymize` replaces any identifier (a reviewer
+// login, an `@handle` in a codeowners line, or an embedded email substring)
+// with `pseudonymizeAuthor`'s stable per-identifier hash, so re-running
+// produces the SAME pseudonym for the SAME person rather than a blanket
+// redaction that destroys the "which findings share a reviewer" structure.
+// Neither knob touches a bare login/handle when `pseudonymize` is off --
+// same precedent as `authorName`, which is NOT redacted by default either.
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+// `.`/`_` included: GitLab usernames legally contain both (`@r.smith`,
+// `@jane_doe`) — a narrower class left real surname fragments unredacted
+// under `pseudonymize:true` (found in the plan's own re-review of this fix).
+const HANDLE_RE = /@[A-Za-z0-9][A-Za-z0-9._-]*/g;
+
+function redactEmailSubstrings(text, { includeEmail, pseudonymize }) {
+  if (typeof text !== 'string') return text;
+  if (includeEmail && !pseudonymize) return text;
+  return text.replace(EMAIL_RE, (email) => (pseudonymize ? pseudonymizeAuthor(null, email) : '[email redacted]'));
+}
+
+function redactHandleSubstrings(text, { pseudonymize }) {
+  if (typeof text !== 'string' || !pseudonymize) return text;
+  // Runs AFTER redactEmailSubstrings, so an email's local-part `@` has
+  // already been consumed by the full-email replacement above and cannot be
+  // mistaken for a bare handle here.
+  return text.replace(HANDLE_RE, (match) => `@${pseudonymizeAuthor(match.slice(1), null)}`);
+}
+
+function redactCodeownersLine(line, opts) {
+  if (typeof line !== 'string') return line;
+  return redactHandleSubstrings(redactEmailSubstrings(line, opts), opts);
+}
+
+function redactProviderEnrichment(pe, opts) {
+  if (!pe) return null;
+  return {
+    ...pe,
+    reviewers: Array.isArray(pe.reviewers)
+      ? pe.reviewers.map((r) => (opts.pseudonymize ? pseudonymizeAuthor(r, null) : r))
+      : pe.reviewers,
+    codeowners: Array.isArray(pe.codeowners)
+      ? pe.codeowners.map((line) => redactCodeownersLine(line, opts))
+      : pe.codeowners,
+  };
+}
+
+export function redactFindingProvenance(fp, { includeEmail = false, pseudonymize = false } = {}) {
+  if (!fp) return null;
+  const redactOrigin = (origin) => origin
+    ? {
+        ...origin,
+        authorEmail: includeEmail ? origin.authorEmail : null,
+        authorName: pseudonymize ? pseudonymizeAuthor(origin.authorName, origin.authorEmail) : origin.authorName,
+      }
+    : null;
+  return {
+    ...fp,
+    findingOrigin: redactOrigin(fp.findingOrigin),
+    providerEnrichment: redactProviderEnrichment(fp.providerEnrichment, { includeEmail, pseudonymize }),
+  };
+}
+
+// Untrusted commit metadata (author name, commit summary) must never reach
+// a terminal or a Markdown/HTML renderer un-sanitized — PRD FR-PROV-026.
+// Strips ANSI/control escape sequences (a malicious author name containing
+// \x1b[2J or similar could manipulate terminal state) and collapses
+// newlines (a multi-line "author name" could forge extra output lines).
+// This is layered UNDER the existing HTML-escaping path (which already
+// protects the HTML renderer via JSON-escaping before embedding) — this
+// helper is specifically for the CLI/terminal text path, which had none.
+//
+// Lives here (rather than in report/index.js, which re-exports it) because
+// it has consumers on opposite sides of the report/posture boundary:
+// report/index.js's explainProvenance/toMarkdown, and
+// posture/auditor-walkthrough.js's renderWalkthrough — both of which are
+// console.log'd verbatim (bin/agentic-security.js), so both need the
+// terminal-safety guarantee. Putting it in report/ would make posture/
+// depend on report/, backwards from every other dependency in this tree.
+//
+// A Markdown-specific sibling (backslash-escaping CommonMark punctuation)
+// was added and then removed here: it was applied to renderWalkthrough's
+// output, but that text's only LIVE consumer is bin/agentic-security.js's
+// raw `console.log`, and its file-writing sibling (persistWalkthrough) has
+// zero callers anywhere in the CLI/command surface — nothing in this repo
+// ever runs this text through an actual Markdown renderer. Backslash-
+// escaping is only inert once a real renderer processes it; printed raw or
+// read as a plain-text file, `Jean-Luc Picard` becoming `Jean\-Luc Picard`
+// and `dependabot[bot]` becoming `dependabot\[bot\]` is a visible
+// regression on ordinary, common real-world names, not a security fix. If
+// a genuine Markdown-rendering consumer of this text is added later, revisit
+// this decision informed by that consumer's actual escaping requirements —
+// don't reintroduce blind punctuation-escaping speculatively.
+export function sanitizeForTerminal(str) {
+  if (typeof str !== 'string') return str;
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '').replace(/[\r\n]+/g, ' ').trim();
+}

package/src/posture/provenance/transitive-sca.js

@@ -0,0 +1,147 @@
+// Transitive dependency origin resolution (Finding Provenance PRD, M3 §3.2).
+//
+// A transitive vulnerable_dep finding's vulnerable version was never
+// declared directly in this repo's manifest — some DIRECT dependency's
+// version bump pulled it into the graph. This module answers "which commit
+// changed the lockfile such that the vulnerable transitive version first
+// appears," re-deriving the dependency's ancestry AT EACH HISTORICAL
+// CANDIDATE COMMIT rather than trusting the CURRENT depChain (Task 5) —
+// the graph's shape can itself change across commits, so the current
+// ancestry is a hint for the fixture/test author, not evidence a resolver
+// can rely on for a historical claim.
+//
+// Scope: package-lock.json only for M3 — see the plan's Task 6 scope note.
+
+import { candidateCommitsForFile, getFirstParent, getBlobAtCommit, commitMeta } from './git-evidence.js';
+import { versionInRange } from './sca-origin.js';
+import { PROVENANCE_METHOD } from './schema.js';
+
+const LOCKFILE_BASENAME = 'package-lock.json';
+
+function _sameDepChain(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  return a.every((seg, i) => seg === b[i]);
+}
+
+// Extract {version, depChain} for `depName` from a package-lock.json blob's
+// text, using the same `packages` key structure engine.js's
+// _parsePackageLockJson reads at scan time (lockfile v2/v3 shape: keys are
+// paths like "node_modules/express/node_modules/qs"). Returns null if the
+// package isn't present in this blob at all (e.g., an OLDER lockfile before
+// it was ever pulled in).
+//
+// `preferredDepChain` (M3 §3.2 follow-up, final whole-branch review item #7)
+// is the finding's OWN depChain (Task 5, propagated from engine.js's
+// _parsePackageLockJson) identifying which specific nested copy the finding
+// is actually about, when a lockfile has multiple nested copies of the same
+// package name at different depths. When a `packages` key at THIS historical
+// blob computes to that exact chain, it wins outright — the shortest-path
+// heuristic below is a heuristic guess about "the" instance, and an exact
+// match is not a guess. It is only ever a hint, though, per this module's own
+// header comment: the graph's shape can differ commit-to-commit, so a
+// historical blob may simply have no key whose chain matches the CURRENT
+// depChain at all — in that case fall back to the shortest-path heuristic
+// exactly as before, since re-deriving ancestry per-commit rather than
+// trusting a mismatched hint is the whole reason this module doesn't just
+// trust the current depChain outright.
+function extractTransitiveVersion(blobText, depName, preferredDepChain) {
+  let doc;
+  try { doc = JSON.parse(blobText); } catch { return null; }
+  const packages = doc.packages;
+  if (!packages || typeof packages !== 'object') return null;
+  // Prefer the SHORTEST matching path (closest to a direct dependency) when
+  // multiple nested copies of the same package exist at different depths —
+  // matches the ancestry a reader would consider "the" instance most of the
+  // time. Ties resolve to whichever JSON.stringify/Object.keys ordering
+  // returns first (lockfiles preserve insertion order; this is deterministic
+  // for a given blob, which is what matters for a repeatable resolution).
+  let best = null;
+  let exact = null;
+  for (const key of Object.keys(packages)) {
+    if (!key.endsWith(`node_modules/${depName}`)) continue;
+    const depChain = key.split('node_modules/').filter(Boolean).map((s) => s.replace(/\/$/, ''));
+    const entry = packages[key];
+    const version = entry && entry.version;
+    if (!version) continue;
+    if (!exact && Array.isArray(preferredDepChain) && preferredDepChain.length > 0 && _sameDepChain(depChain, preferredDepChain)) {
+      exact = { version, depChain };
+    }
+    if (!best || depChain.length < best.depChain.length) best = { version, depChain };
+  }
+  return exact || best;
+}
+
+function originResult({ meta, commitsConsidered, depChain, absentInParents, parentBoundaryVerified }) {
+  return {
+    status: 'complete', method: PROVENANCE_METHOD.DEPENDENCY_GRAPH_DIFF, commitsConsidered,
+    findingOrigin: {
+      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,
+    },
+    parentBoundaryVerified,
+    depChain,
+  };
+}
+
+export async function resolveTransitiveSCAOrigin(scanRoot, scaEntry, { since, deadlineAt } = {}) {
+  const file = scaEntry.filePath || scaEntry.file;
+  if (!file) return { status: 'not_available', reason: 'no-manifest-path', commitsConsidered: 0 };
+  const basename = file.split('/').pop();
+  if (basename !== LOCKFILE_BASENAME) {
+    return { status: 'not_available', reason: 'unsupported-lockfile-format', commitsConsidered: 0 };
+  }
+
+  const candidates = candidateCommitsForFile(scanRoot, file, { since });
+  if (candidates.length === 0) return { status: 'not_available', reason: 'no-candidate-commits', commitsConsidered: 0 };
+
+  const range = { introduced: null, fixed: (scaEntry.fixedVersions || [])[0] || null };
+  const preferredDepChain = Array.isArray(scaEntry.depChain) ? scaEntry.depChain : null;
+  let commitsConsidered = 0;
+  let rootFallback = null;
+  let rootFallbackChain = null;
+  let ambiguousBump = false;
+
+  for (const sha of candidates) {
+    if (deadlineAt && Date.now() > deadlineAt) return { status: 'budget_exhausted', commitsConsidered };
+    commitsConsidered++;
+    const blob = getBlobAtCommit(scanRoot, sha, file);
+    if (blob == null) continue;
+    const declared = extractTransitiveVersion(blob, scaEntry.name, preferredDepChain);
+    if (!declared || !versionInRange(declared.version, range)) continue;
+
+    const parent = getFirstParent(scanRoot, sha);
+    if (!parent) {
+      if (!rootFallback) {
+        const meta = commitMeta(scanRoot, sha);
+        if (meta) { rootFallback = meta; rootFallbackChain = declared.depChain; }
+      }
+      continue;
+    }
+
+    const parentBlob = getBlobAtCommit(scanRoot, parent, file);
+    const parentDeclared = parentBlob ? extractTransitiveVersion(parentBlob, scaEntry.name, preferredDepChain) : null;
+    const parentOutOfRange = !parentDeclared || !versionInRange(parentDeclared.version, range);
+    if (!parentOutOfRange) {
+      // Same ambiguity sca-origin.js's resolveDirectSCAOrigin documents: a
+      // fixed-only range with no lower bound can't distinguish "vulnerable
+      // since inception, unrelated bump" from "just became vulnerable here."
+      if (parentDeclared.version !== declared.version) ambiguousBump = true;
+      continue;
+    }
+
+    const meta = commitMeta(scanRoot, sha);
+    if (!meta) continue;
+    return originResult({ meta, commitsConsidered, depChain: declared.depChain, absentInParents: [parent], parentBoundaryVerified: true });
+  }
+
+  if (rootFallback && !ambiguousBump) {
+    return originResult({ meta: rootFallback, commitsConsidered, depChain: rootFallbackChain, absentInParents: [], parentBoundaryVerified: false });
+  }
+
+  return {
+    status: 'partial',
+    reason: ambiguousBump ? 'ambiguous-range-no-introduced-bound' : 'version-never-confirmed-in-candidates',
+    commitsConsidered,
+  };
+}

package/src/posture/provenance/validate.js

@@ -0,0 +1,30 @@
+import { PROVENANCE_STATUS, FINDING_PROVENANCE_SCHEMA_VERSION } from './schema.js';
+
+const VALID_STATUSES = new Set(Object.values(PROVENANCE_STATUS));
+
+export function validateFindingProvenance(finding) {
+  const errors = [];
+  const fp = finding && finding.findingProvenance;
+  if (!fp || typeof fp !== 'object') {
+    errors.push('missing findingProvenance object');
+    return { valid: false, errors };
+  }
+  if (!VALID_STATUSES.has(fp.status)) errors.push(`invalid status: ${fp.status}`);
+  if (!Array.isArray(fp.evidenceAttribution)) errors.push('evidenceAttribution must be an array');
+  if (!Array.isArray(fp.limitations)) errors.push('limitations must be an array');
+  // A version field nothing ever compares against is decoration, not a
+  // contract. These objects are persisted (last-scan.json, the provenance
+  // cache) and read back by later releases, so an object stamped with a
+  // version this build does not know is exactly what the field exists to
+  // catch — and it is the only reason to carry it at all.
+  if (!fp.schemaVersion) errors.push('missing schemaVersion');
+  else if (fp.schemaVersion !== FINDING_PROVENANCE_SCHEMA_VERSION) {
+    errors.push(`unsupported schemaVersion: ${fp.schemaVersion} (this build understands ${FINDING_PROVENANCE_SCHEMA_VERSION})`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function validateFindingsProvenance(findings) {
+  const results = (findings || []).map((f) => ({ id: f.id, ...validateFindingProvenance(f) }));
+  return { valid: results.every((r) => r.valid), failures: results.filter((r) => !r.valid) };
+}