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

package/src/report/index.js

@@ -5,6 +5,19 @@ import { alertFace, approveFace } from './mascot.js';
 import { SCANNER_VERSION } from '../posture/version.js';
 import { proofBlock } from '../posture/proof-artifact.js';
 import { applyLegacyCompat, legacyFieldDeprecationNotice } from '../pipeline/legacy-compat.js';
+// Finding Provenance (M0/M1). NOTE the name: `findingProvenance` is the
+// git-origin record from posture/provenance/. It is NOT `finding.provenance`
+// (posture/ai-code-fingerprint.js's AI-authorship signal, normalized a few
+// hundred lines below) and NOT `supplyChainEntry.provenance`
+// (sca/sigstore-verify.js's SLSA/Sigstore build attestation). Three unrelated
+// things, three distinct keys — do not collapse them.
+import { redactFindingProvenance, sanitizeForTerminal } from '../posture/provenance/schema.js';
+// Re-exported: FR-PROV-026. Lives in provenance/schema.js (shared with
+// posture/auditor-walkthrough.js, a second CLI renderer of the same
+// untrusted fields — see that module's header for why it lives there
+// rather than here); re-exported so `explainProvenance`'s own module keeps
+// being the discoverable home for provenance-text callers.
+export { sanitizeForTerminal };
 
 const SEV_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 const SEV_TO_SARIF = { critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'none' };
@@ -84,6 +97,62 @@ function explainParts(f, { verbose = false } = {}) {
   return { why, how, fix: fix.replace(/\s+/g, ' ').trim(), fixCode };
 }
 
+// Human-readable rendering of a finding's git-origin provenance (FR-PROV
+// output surface). Returns null when the finding carries none — a caller
+// prints the block or omits it, and never has to know the schema.
+//
+// Every one of the six TERMINAL statuses gets a line of its own, and the
+// non-`complete` ones say WHY in the status word itself rather than rendering
+// an empty origin: that is the whole reason the status enum exists (see
+// posture/provenance/coordinator.js's header). `Method` and `Confidence` are
+// unconditional — a block that omitted them for a degraded status would read
+// as "origin unknown" when the honest statement is "resolved by <method> to
+// <confidence>". Nothing here throws on a partially-populated object; every
+// field access is optional-chained or defaulted, because a provenance record
+// that survived a failure path is exactly the input this has to render.
+export function explainProvenance(f) {
+  const fp = f && f.findingProvenance;
+  if (!fp) return null;
+  const short = (v) => String(v || '').slice(0, 7);
+  const day = (v) => String(v || '').slice(0, 10);
+  const lines = [];
+  const o = fp.findingOrigin;
+  if (fp.status === 'complete' && o) {
+    lines.push(`Introduced:      ${short(o.commit)}  •  ${day(o.authorDate)}  •  ${sanitizeForTerminal(o.authorName) || 'unknown'}`);
+    const bi = fp.branchIntroduction;
+    if (bi && bi.commit !== o.commit) {
+      // relationship is an internal enum ('merge'/'direct', see
+      // branch-entry.js) never sourced from untrusted git text — wrapped
+      // anyway for defense in depth and consistency with authorName above.
+      lines.push(`Branch entry:    ${short(bi.commit)}  •  ${sanitizeForTerminal(bi.relationship) || 'unknown relationship'}`);
+    }
+  } else if (fp.status === 'partial') {
+    lines.push(`Origin:          EARLIEST OBSERVABLE${o ? '  ' + short(o.commit) : ''}`);
+  } else if (fp.status === 'uncommitted') {
+    lines.push('Origin:          UNCOMMITTED (working tree only)');
+  } else if (fp.status === 'not_available') {
+    lines.push('Origin:          NOT AVAILABLE');
+  } else if (fp.status === 'error') {
+    lines.push('Origin:          ERROR resolving provenance');
+  } else if (fp.status === 'budget_exhausted') {
+    lines.push('Origin:          BUDGET EXHAUSTED before resolution completed');
+  } else {
+    // An unrecognised status is reported as itself, not silently dropped — a
+    // future status added to the enum must be visible here on the day it
+    // ships, even before this renderer learns a nicer wording for it.
+    lines.push(`Origin:          ${String(fp.status || 'unknown').toUpperCase()}`);
+  }
+  if (fp.firstObserved) {
+    lines.push(`First observed:  ${fp.firstObserved.scanId || 'unknown scan'}  •  ${day(fp.firstObserved.observedAt)}`);
+  }
+  lines.push(`Method:          ${fp.method || 'none'}`);
+  lines.push(`Confidence:      ${String(fp.confidence?.level || 'unknown').toUpperCase()}`);
+  if (Array.isArray(fp.limitations) && fp.limitations.length) {
+    lines.push(`Limitations:     ${fp.limitations.join('; ')}`);
+  }
+  return lines.join('\n');
+}
+
 function fingerprint(f){
   const s = `${f.file}:${f.line||f.source?.line||0}:${f.vuln||f.type||''}`;
   return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
@@ -108,6 +177,24 @@ export function _remediationOf(f) {
   return null;
 }
 
+// Redacted passthrough for the git-origin provenance record (FR-PROV output
+// surface). Author EMAIL is PII and is withheld by default EVERYWHERE — raw
+// JSON included, since `toJSON` derives from this same function and an email
+// in a committed report artifact is a leak nobody opted into. Set
+// AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL=1 to include it (read per call, not
+// cached at module load, so a test or a wrapper can set it per invocation).
+// `authorName` is deliberately NOT redacted by default: it is already the
+// value the existing `introducedBy` field has carried for releases. Set
+// AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS=1 (--pseudonymize-authors) to replace
+// it with a stable Contributor-XXXXXXXX id instead — PRD Section 8.
+function _normalizedProvenance(f) {
+  if (!f || !f.findingProvenance) return null;
+  return redactFindingProvenance(f.findingProvenance, {
+    includeEmail: process.env.AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL === '1',
+    pseudonymize: process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS === '1',
+  });
+}
+
 export function normalizeFindings(scan){
   const out = [];
   // Feat-4: filter findings via custom suppressions, recording the suppression
@@ -250,6 +337,10 @@ export function normalizeFindings(scan){
       cloneClusterSize: typeof f.cloneClusterSize === 'number' ? f.cloneClusterSize : null,
       provenance: f.provenance || null,
       provenanceScore: typeof f.provenanceScore === 'number' ? f.provenanceScore : null,
+      // posture/provenance/coordinator.js#annotateGitProvenance — WHICH COMMIT
+      // introduced this finding. A different question, and a different field,
+      // from the two lines above it (see the import comment at the top).
+      findingProvenance: _normalizedProvenance(f),
       typeNarrowed: f.typeNarrowed || null,
       strideCategory: f.strideCategory || null,
       personaScores: f.personaScores || null,
@@ -349,6 +440,15 @@ export function normalizeFindings(scan){
       commit: s.commit || null,
       historical: s._historical === true,
       description: s.description || null,
+      // Second independent Finding Provenance PRD audit (Task 7, item 4):
+      // `stableId` was emitted for the SAST channel only (below), so a
+      // consumer of a secrets/logic/SCA finding could not recompute
+      // `findingProvenance.evidenceDigest` (it binds `stableId` as its first
+      // input — coordinator.js's `computeDigest`) — the exact case this
+      // channel needs it for, since `annotateStableIds(aSecrets)` (engine.js)
+      // already backfills a real one before provenance resolution runs.
+      stableId: s.stableId || null,
+      findingProvenance: _normalizedProvenance(s),
     });
   }
   for (const lv of (scan.logicVulns||[])) {
@@ -376,6 +476,15 @@ export function normalizeFindings(scan){
       ecosystem: lv.ecosystem || null,
       license: lv.license || null,
       description: lv.description || null,
+      // Second independent Finding Provenance PRD audit (Task 7, item 4) —
+      // same reasoning as the secrets channel above. Note: only the
+      // `blameableLogic` subset (engine.js) gets a real backfilled stableId
+      // via `annotateStableIds`; the three synthetic-line producers
+      // (license-policy:/deploy-platform:/stack-playbook:) never go through
+      // that backfill and stay `null` here — honest, since they also stay on
+      // the permanent not_available provenance path (posture/CLAUDE.md).
+      stableId: lv.stableId || null,
+      findingProvenance: _normalizedProvenance(lv),
     });
   }
   for (const sc of (scan.supplyChain||[])) {
@@ -425,6 +534,20 @@ export function normalizeFindings(scan){
       toxicity: sc.toxicityScore ?? null,
       toxicityFactors: sc.toxicityFactors || null,
       toxicityLabel: sc.toxicityLabel || null,
+      // Git-origin provenance for the dependency declaration (which commit
+      // moved the declared version into the advisory's vulnerable range).
+      // Distinct from `sc.provenance`, which sca/sigstore-verify.js uses for
+      // the package's Sigstore/SLSA build attestation — that one is NOT
+      // carried here today and must not be conflated with this field.
+      // Second independent Finding Provenance PRD audit (Task 7, item 4) —
+      // same reasoning as the secrets/logic channels above. Only entries
+      // routed through annotateGitProvenance (engine.js's `directDeps`/
+      // `transitiveDeps`, `isSca`/`isTransitiveSca` in coordinator.js) get a
+      // real backfilled `scaStableId`; an entry that was never routed
+      // through it (e.g. `unpinned_dep`/`no_lockfile` types) honestly stays
+      // `null` here rather than fabricating one.
+      stableId: sc.stableId || null,
+      findingProvenance: _normalizedProvenance(sc),
     });
   }
   // FR-108: backfill deprecated field names from their current replacements
@@ -676,15 +799,22 @@ export function toCSV(scan){
     const s = String(v);
     return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
   };
-  const header = ['id', 'severity', 'vuln', 'cwe', 'cvss', 'owasp', 'file', 'line', 'confidence', 'reachable', 'kind', 'snippet'];
+  // FR-PROV-018: a nested findingProvenance object has no natural CSV
+  // representation, so this is a deliberate flattening (status/commit/
+  // authorDate/confidence), not full fidelity. Appended after the existing
+  // columns so a spreadsheet already keyed on column position is unaffected.
+  const header = ['id', 'severity', 'vuln', 'cwe', 'cvss', 'owasp', 'file', 'line', 'confidence', 'reachable', 'kind', 'snippet', 'provenanceStatus', 'provenanceCommit', 'provenanceAuthorDate', 'provenanceConfidence'];
   const rows = [header.join(',')];
   for (const f of findings) {
+    const fp = f.findingProvenance;
     rows.push([
       esc(f.id), esc(f.severity), esc(f.vuln), esc(f.cwe), esc(f.cvss || ''),
       esc(f.owasp || ''), esc(f.file), esc(f.line),
       esc(f.confidence == null ? '' : f.confidence.toFixed(3)),
       esc(f.reachable == null ? '' : f.reachable),
       esc(f.kind), esc((f.snippet || '').slice(0, 200)),
+      esc(fp?.status || ''), esc(fp?.findingOrigin?.commit || ''),
+      esc(fp?.findingOrigin?.authorDate || ''), esc(fp?.confidence?.level || ''),
     ].join(','));
   }
   return rows.join('\n');
@@ -732,6 +862,15 @@ export function toJUnit(scan, meta={}){
   return lines.join('\n');
 }
 
+// FR-PROV-026: length of the Markdown code fence needed to safely wrap
+// `text` without it being able to break out via an embedded backtick run
+// (e.g. from an unsanitized-for-backticks authorName). Minimum 3, per
+// CommonMark; longer only when `text` itself contains a run that long.
+function _mdFenceLen(text) {
+  const runs = String(text == null ? '' : text).match(/`+/g) || [];
+  return Math.max(3, ...runs.map(r => r.length + 1));
+}
+
 export function toMarkdown(scan, meta={}){
   const findings = normalizeFindings(scan);
   const lines = ['# Agentic Security — Scan Report', ''];
@@ -764,6 +903,32 @@ export function toMarkdown(scan, meta={}){
         lines.push(`| \`${f.file}:${f.line}\` | ${f.vuln} | ${f.cwe||'—'} | ${epss} | ${fix.replace(/\|/g,'\\|').slice(0,140)} |`);
       }
     }
+    // FR-PROV-018: one provenance block per finding that has one, reusing
+    // explainProvenance's content — never a second, divergent renderer.
+    const withProvenance = bySev[sev].filter(f => f.findingProvenance);
+    if (withProvenance.length) {
+      lines.push('');
+      lines.push('<details><summary>Provenance</summary>');
+      lines.push('');
+      for (const f of withProvenance) {
+        const block = explainProvenance(f);
+        if (!block) continue;
+        lines.push(`**\`${f.file}:${f.line}\`** — ${f.vuln}`);
+        // FR-PROV-026: sanitizeForTerminal (applied inside explainProvenance)
+        // strips control chars but NOT backticks, which are ordinary text —
+        // a malicious authorName containing ``` could otherwise break out of
+        // a fixed 3-backtick fence and inject raw Markdown/HTML into the
+        // report. Use a fence one backtick longer than any run already in
+        // the block (CommonMark's own escaping mechanism for fenced code),
+        // so normal content (never containing backticks) is unaffected.
+        const fence = '`'.repeat(_mdFenceLen(block));
+        lines.push(fence);
+        lines.push(block);
+        lines.push(fence);
+        lines.push('');
+      }
+      lines.push('</details>');
+    }
     lines.push('');
   }
   return lines.join('\n');
@@ -841,6 +1006,16 @@ export function toSARIF(scan, meta={}){
           ...(scan && scan._rulesetVersion ? { rulesetVersion: scan._rulesetVersion } : {}),
           ...(scan && scan._rulesetVersionSource ? { rulesetVersionSource: scan._rulesetVersionSource } : {}),
           ...(scan && scan._rulesetVersionMismatch ? { rulesetVersionMismatch: scan._rulesetVersionMismatch } : {}),
+          // FR-PROV-018: run-level provenance summary — how many results
+          // resolved which terminal status, so a SARIF consumer can judge
+          // history coverage without walking every result's properties.
+          ...(findings.some(f => f.findingProvenance) ? {
+            provenanceCoverage: findings.reduce((acc, f) => {
+              const s = f.findingProvenance?.status || 'none';
+              acc[s] = (acc[s] || 0) + 1;
+              return acc;
+            }, {}),
+          } : {}),
         },
       }],
       results: findings.map(f => {
@@ -905,6 +1080,12 @@ export function toSARIF(scan, meta={}){
           signatureStatus: f.signatureStatus || (f._passThroughSigning ? 'pass-through' : (f._unsigned ? 'unsigned' : 'verified')),
           ...(f._unsigned ? { unsigned: true } : {}),
           ...(f._passThroughSigning ? { passThroughSigning: true } : {}),
+          // FR-PROV-018: `f` is already normalized (findingProvenance already
+          // passed through _normalizedProvenance/redactFindingProvenance by
+          // normalizeFindings), so this is a redacted passthrough, never a
+          // second redaction pass and never a read of a raw pre-normalization
+          // finding.
+          ...(f.findingProvenance ? { findingProvenance: f.findingProvenance } : {}),
         },
       };}),
     }],
@@ -966,7 +1147,7 @@ export function toHTML(scan, meta = {}) {
   // server-side) so the browser render shows them without a second command.
   const findings = normalizeFindings(scan).map(f => {
     const ex = explainParts(f, { verbose: true });
-    return { ...f, _riskNote: riskNote(f), _explainWhy: ex.why, _explainHow: ex.how };
+    return { ...f, _riskNote: riskNote(f), _explainWhy: ex.why, _explainHow: ex.how, _explainProvenance: explainProvenance(f) };
   });
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
   for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
@@ -1044,6 +1225,8 @@ export function toHTML(scan, meta = {}) {
   .f-how{margin-top:6px;color:#94a3b8;font-size:13px}
   .f-how code{font-family:ui-monospace,monospace;color:#e2e8f4}
   .f-fix{background:#0d1f3d;border-left:3px solid #38bdf8;padding:8px 12px;margin-top:8px;border-radius:0 4px 4px 0}
+  .f-provenance{background:#0f1f14;border-left:3px solid #34d058;padding:8px 12px;margin-top:8px;border-radius:0 4px 4px 0}
+  .f-provenance pre{background:transparent;padding:0;margin:4px 0 0 0}
   .hidden{display:none!important}
 </style></head>
 <body>
@@ -1099,6 +1282,7 @@ function makeCard(f) {
       (f.snippet ? '<pre>' + esc(f.snippet) + '</pre>' : '') +
       (f.masked ? '<pre style="color:#f97316">' + esc(f.masked) + ' (masked)</pre>' : '') +
       (f.fix && f.fix.description ? '<div class="f-fix"><b>Fix:</b> ' + esc(f.fix.description) + (f.fix.code ? '<pre>' + esc(f.fix.code) + '</pre>' : '') + '</div>' : '') +
+      (f._explainProvenance ? '<div class="f-provenance"><b>Provenance:</b><pre>' + esc(f._explainProvenance) + '</pre></div>' : '') +
     '</div>';
   div.addEventListener('click', () => div.classList.toggle('expanded'));
   return div;
@@ -1178,7 +1362,10 @@ const RESET = '\x1b[0m';
 const DIM = '\x1b[2m';
 const BOLD = '\x1b[1m';
 
-export function toCLI(scan, { verbose=false, color=true }={}){
+// `provenance` defaults to FALSE on purpose: the block is five-plus extra
+// lines per finding, and the default CLI listing is already dense. It prints
+// only when the operator asks for it.
+export function toCLI(scan, { verbose=false, color=true, provenance=false }={}){
   const findings = normalizeFindings(scan);
   const lines = [];
   const c = (s, code) => color ? `${code}${s}${RESET}` : s;
@@ -1204,6 +1391,13 @@ export function toCLI(scan, { verbose=false, color=true }={}){
     if (ex.how) lines.push(`        ${c('how:', DIM)} ${ex.how}`);
     if (ex.fix) lines.push(`        ${c('fix:', DIM)} ${ex.fix}`);
     if (ex.fixCode) for (const ln of ex.fixCode.split('\n').slice(0, 6)) lines.push(`           ${c(ln, DIM)}`);
+    if (provenance) {
+      // `f` here is already normalized, so its findingProvenance has been
+      // through redactFindingProvenance — the email is gone before it can
+      // reach a terminal.
+      const prov = explainProvenance(f);
+      if (prov) for (const ln of prov.split('\n')) lines.push(`        ${c(ln, DIM)}`);
+    }
   }
   lines.push('');
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };

package/src/runScan.js

@@ -4,6 +4,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
 import { listFiles } from './util/glob.js';
+import { hardenGitArgs, hardenGitEnv } from './util/git-hardening.js';
 import { runFullScan, shouldScan, isKubernetesManifest, isCloudFormationTemplate, isInstructionFile } from './engine.js';
 import { appendScanSnapshot } from './posture/security-trend.js';
 import { recover as recoverFixHistory } from './posture/fix-history.js';
@@ -111,17 +112,28 @@ export async function readTree(root, { ignore = [] } = {}) {
 
 // Feat-10: incremental scan via `--changed-since <git-ref>`. Returns the set of
 // repo-relative paths modified since the ref, or null if git is unavailable.
+//
+// `root` is the scan target's repository, not this project's own trusted
+// checkout — hardened per FR-PROV-024 / the second Finding Provenance PRD
+// audit (same exposure class as provenance/git-evidence.js: a hostile
+// .git/config's `core.fsmonitor` fires on the `git status --porcelain`
+// call below just from reading repo state). `--no-ext-diff` is added to the
+// `diff --name-only` call too: VERIFIED that shape does not itself invoke an
+// external diff driver in current git (no content is rendered), but it costs
+// nothing and keeps every `git diff` call site in this codebase uniformly
+// hardened against the surface `material-change.js`'s `classifyGitDiff` was
+// actually caught on (see that file's comment for the live exploit).
 export function changedSince(root, gitRef) {
   if (!gitRef) return null;
   try {
-    const out = cp.execFileSync('git', ['diff', '--name-only', `${gitRef}...HEAD`], {
-      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    const out = cp.execFileSync('git', hardenGitArgs(['diff', '--name-only', '--no-ext-diff', `${gitRef}...HEAD`]), {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv(),
     });
     const set = new Set(out.split('\n').filter(Boolean));
     // Also include uncommitted changes
     try {
-      const dirty = cp.execFileSync('git', ['status', '--porcelain'], {
-        cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      const dirty = cp.execFileSync('git', hardenGitArgs(['status', '--porcelain']), {
+        cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv(),
       });
       for (const line of dirty.split('\n')) {
         const f = line.slice(3).trim();
@@ -151,9 +163,22 @@ export async function runScan(rootDir, opts = {}) {
   // Caller may pre-build fileContents (used by the MCP server's scan_diff to
   // scope a scan to a specific file list without walking the whole tree).
   let fileContents, depFileContents;
+  // `completeScan` answers ONE question for the whole pipeline: does the file
+  // set below cover all of `root`, or only a subset of it? Anything downstream
+  // that reasons about the ABSENCE of a finding — most importantly the
+  // provenance lifecycle ledger, whose remediation pass closes every open
+  // stableId missing from this scan — is only sound on a complete scan. A
+  // subset scan that claims completeness marks the entire rest of the project
+  // remediated. It starts true and is only ever narrowed, so a new subsetting
+  // path added later must opt OUT explicitly rather than silently inherit a
+  // false claim of coverage.
+  let completeScan = true;
   if (opts.fileContents) {
+    // Caller-supplied file list (MCP `scan_diff`, the LSP's on-save scan): by
+    // construction a subset of the tree, not a scan of it.
     fileContents = opts.fileContents;
     depFileContents = opts.depFileContents || {};
+    completeScan = false;
   } else {
     ({ fileContents, depFileContents } = await readTree(root, opts));
   }
@@ -167,6 +192,10 @@ export async function runScan(rootDir, opts = {}) {
         if (changed.has(f)) filtered[f] = fileContents[f];
       }
       fileContents = filtered;
+      // Only when the filter actually applied. A `changedSince` that resolved
+      // to null (not a git repo / bad ref) is warned about below and scans the
+      // whole tree, which IS complete.
+      completeScan = false;
     } else if (opts.onProgress) {
       opts.onProgress({ phase: 'warning', file: 'changedSince ignored: not a git repo or invalid ref', current: 0, total: 0 });
     }
@@ -174,7 +203,7 @@ export async function runScan(rootDir, opts = {}) {
 
   // R8: `resume` is opt-in. Left undefined here, runFullScan falls back to the
   // AGENTIC_SECURITY_RESUME=1 env var, which is off by default.
-  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume, deep: opts.deep, deepInCi: opts.deepInCi }, opts.onProgress || (()=>{}));
+  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume, deep: opts.deep, deepInCi: opts.deepInCi, completeScan }, opts.onProgress || (()=>{}));
   // Premortem 2R4.2: stamp ruleset version + source on the scan result, and
   // notify if the operator pinned a different version than what's installed.
   try { stampScan(root, scan); } catch {}

package/src/sast/rate-limit.js

@@ -31,7 +31,13 @@ const AI_PATH_RE = /\/(?:ai|chat|generate|complete|completion|embed|embedding|gp
 const PAYMENT_PATH_RE = /\/(?:pay(?:ment)?|checkout|stripe|order|subscribe|billing|invoice|charge|purchase)\b/i;
 const CONTACT_PATH_RE = /\/(?:contact|submit|feedback|form|newsletter|subscribe|waitlist|signup|onboard)\b/i;
 
-function _hasRateLimit(content) {
+// Exported (FR-PROV-017) so posture/provenance/coordinator.js can reuse the
+// EXACT SAME presence test as a `resolveMissingControl` predicate: "did a
+// commit's historical blob have rate limiting" must be answered by the same
+// logic that decides "does HEAD have rate limiting", or a drift between the
+// two could fabricate a regression (or miss a real one) that only existed in
+// the predicate's own disagreement with the detector, not in the code.
+function hasRateLimit(content) {
   return RL_IMPORT_RE.test(content) || RL_USAGE_RE.test(content) || REDIS_RL_RE.test(content);
 }
 
@@ -77,7 +83,7 @@ const CATEGORY_META = {
 function scanRateLimit(file, content) {
   if (!_SCAN_EXT_RE.test(file)) return [];
   if (_NONPROD_RE.test(file)) return [];
-  if (_hasRateLimit(content)) return [];
+  if (hasRateLimit(content)) return [];
   const findings = [];
   const lines = content.split('\n');
 
@@ -99,6 +105,18 @@ function scanRateLimit(file, content) {
         description: meta.description,
         remediation: meta.remediation,
         cwe: meta.cwe,
+        // FR-PROV-017: routes posture/provenance/coordinator.js to
+        // resolveMissingControl instead of the plain SAST origin-resolver.
+        // "A route lacks rate limiting" is exactly the "was this control
+        // ever present, and if so when did it disappear" question that
+        // resolver answers — a plain SAST resolver would instead ask "when
+        // was this LINE introduced," which is the wrong question for a
+        // finding about something ABSENT. An explicit boolean marker set
+        // here (rather than coordinator.js string-matching finding.id/vuln)
+        // keeps the two modules' string formats decoupled, matching how
+        // isDirect/isTransitiveSca-style markers already route elsewhere in
+        // this pipeline.
+        missingControlCandidate: true,
       });
     }
   }
@@ -120,6 +138,18 @@ function scanRateLimit(file, content) {
         description: meta.description,
         remediation: meta.remediation,
         cwe: meta.cwe,
+        // FR-PROV-017: routes posture/provenance/coordinator.js to
+        // resolveMissingControl instead of the plain SAST origin-resolver.
+        // "A route lacks rate limiting" is exactly the "was this control
+        // ever present, and if so when did it disappear" question that
+        // resolver answers — a plain SAST resolver would instead ask "when
+        // was this LINE introduced," which is the wrong question for a
+        // finding about something ABSENT. An explicit boolean marker set
+        // here (rather than coordinator.js string-matching finding.id/vuln)
+        // keeps the two modules' string formats decoupled, matching how
+        // isDirect/isTransitiveSca-style markers already route elsewhere in
+        // this pipeline.
+        missingControlCandidate: true,
       });
     }
   }
@@ -127,4 +157,4 @@ function scanRateLimit(file, content) {
   return findings;
 }
 
-export { scanRateLimit };
+export { scanRateLimit, hasRateLimit };

package/src/util/git-hardening.js

@@ -0,0 +1,128 @@
+// Hardening for every `git` subprocess call this scanner makes against a
+// SCANNED repository it does not control — i.e. any git invocation whose
+// `cwd` (or `-C <dir>`) is a project the scanner was asked to scan, as
+// opposed to this project's own trusted checkout.
+//
+// Verified RCE (second independent Finding Provenance PRD audit,
+// FR-PROV-024 / PRD Section 8 "never run repository hooks or untrusted
+// build scripts"): git-evidence.js's `_run` invoked `git` with no config
+// hardening at all. A hostile repo's `.git/config` can set `core.fsmonitor`
+// to point at an attacker script; git executes it on an ordinary READ-ONLY
+// command like `git status --porcelain` — no clone, no checkout, no
+// deliberate command needed, just `getRepoState()` reading repo state.
+// Reproduced against this exact repro shape before this module existed:
+// `getRepoState()` alone wrote a marker file outside the repo.
+//
+// Four independent hostile-config surfaces, each closed by a different
+// flag/env var (do not assume one covers another — a same-class RCE
+// survived the first round of this hardening precisely because
+// `--no-textconv` was assumed to cover `git diff` the same way it covers
+// `git show`/`git log -p`/`git blame`, and it does not):
+//   - `core.fsmonitor`   -> fires on `git status` (and other porcelain
+//                           commands that consult the index). Closed by
+//                           `-c core.fsmonitor=` (empty value disables it).
+//   - `core.hooksPath`   -> redirects git's hook lookup to an
+//                           attacker-controlled directory (pre-commit,
+//                           post-checkout, ...). None of THIS module's
+//                           read-only operations should fire a hook, but a
+//                           caller elsewhere in the tree that does invoke a
+//                           hook-shaped command (checkout, commit) inherits
+//                           the same exposure — hardened uniformly rather
+//                           than relying on each call site to reason about
+//                           whether its own command can trigger a hook.
+//                           Closed by `-c core.hooksPath=/dev/null`
+//                           (verified: git tries to stat
+//                           `/dev/null/<hookname>`, which is not a
+//                           directory, so hook lookup fails closed — this
+//                           is NOT relying on /dev/null being an empty
+//                           *file*, it works because it isn't a directory).
+//   - `.gitattributes`   -> a `diff=<name>` attribute + a matching
+//     textconv driver     `diff.<name>.textconv` config key points a text
+//                           filter at an attacker script; fires on any
+//                           command that renders blob/diff CONTENT (`git
+//                           show`/`git diff`/`git log -p`/`git log -L`/
+//                           `git blame`) unless `--no-textconv` is passed.
+//                           Verified per-subcommand: `git show -s` (no
+//                           content shown) and `git show <sha>:<path>`
+//                           (blob cat, not a diff) were NOT exploitable in
+//                           this git version, but `git show -U0`, `git log
+//                           -L`, and `git blame` all were.
+//   - `.git/config` /       an EXTERNAL diff driver — `.gitattributes`
+//     `.gitattributes`      `diff=<name>` + `.git/config [diff "<name>"]
+//     external diff driver  command=<script>`, or the repo-local/global
+//                           `diff.external` config key — is a DIFFERENT
+//                           mechanism from the textconv driver above and is
+//                           NOT closed by `--no-textconv`. VERIFIED: `git
+//                           -c core.fsmonitor= -c core.hooksPath=/dev/null
+//                           diff --unified=0 --no-textconv <ref>...HEAD`
+//                           still runs the attacker's `diff.evil.command`
+//                           script — `--no-textconv` only suppresses the
+//                           TEXTCONV driver, and `git diff` (unlike `git
+//                           show`/`git log -p`/`git blame`, which were all
+//                           verified safe with just `--no-textconv`) honours
+//                           an external diff driver by default regardless.
+//                           Closed by `--no-ext-diff`, which must be passed
+//                           explicitly on every `git diff` invocation (same
+//                           reason `--no-textconv` isn't a `-c` flag: it's a
+//                           diff-machinery option, not repo config). This
+//                           was the live RCE a second review found after the
+//                           first round of this hardening shipped —
+//                           material-change.js's `classifyGitDiff` (the real
+//                           entry point for `/scan --diff`) had
+//                           `--no-textconv` but not `--no-ext-diff` and was
+//                           still exploitable end-to-end.
+//
+// A FIFTH surface is known but not exploitable through any call site in this
+// codebase today, so it is documented rather than closed: a `clean` smudge
+// filter (`.gitattributes` `filter=<name>` + `filter.<name>.clean`) fires on
+// a WORKTREE diff (e.g. `git diff --name-only HEAD` with no `<ref>` on the
+// other side) and has no git flag to disable it at all (unlike textconv/
+// ext-diff). Every `git diff` call site in this codebase diffs two refs
+// (`<ref>...HEAD`), never the worktree against HEAD, so nothing here hits
+// it — but a future worktree-diff call site would silently reintroduce this
+// exact vulnerability class and must not assume `hardenGitArgs` covers it.
+//
+// `GIT_CONFIG_NOSYSTEM=1` additionally blocks a SYSTEM-level git config
+// (outside any repository, e.g. /etc/gitconfig) from re-introducing a
+// hostile setting the `-c` flags above didn't anticipate; `GIT_TERMINAL_PROMPT=0`
+// stops a git invocation from ever blocking on an interactive credential
+// prompt (a hostile repo pointing `origin`/a submodule at a URL that
+// prompts). Both are environment variables, not `-c` flags — git does not
+// expose either as repo-local config.
+//
+// Every `git` subprocess call this scanner makes against a scan target's
+// repository MUST route its args through `hardenGitArgs` and its env
+// through `hardenGitEnv`. A `git show`/`git diff`/`git log -p`/`git log -L`/
+// `git blame` invocation must ALSO pass `--no-textconv` explicitly (it is
+// not a `-c` config value, so it isn't folded into `GIT_HARDENED_CONFIG_ARGS`
+// — it must appear in the invocation's own args, after the config args), and
+// a `git diff` invocation must ADDITIONALLY pass `--no-ext-diff` (a
+// different flag for a different surface — see above; `--no-textconv` does
+// not imply it).
+
+export const GIT_HARDENED_CONFIG_ARGS = Object.freeze([
+  '-c', 'core.fsmonitor=',
+  '-c', 'core.hooksPath=/dev/null',
+]);
+
+export const GIT_HARDENED_ENV = Object.freeze({
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_TERMINAL_PROMPT: '0',
+});
+
+// Prepend the hardening `-c` flags to a git argv. These are GLOBAL options
+// and must appear before the subcommand, which is why this always prepends
+// rather than appending — a `-c` after the subcommand name is parsed as a
+// positional argument to that subcommand, not a global option.
+export function hardenGitArgs(args) {
+  return [...GIT_HARDENED_CONFIG_ARGS, ...(Array.isArray(args) ? args : [])];
+}
+
+// Build the `env` option for execFileSync/spawnSync. Node's `env` option
+// REPLACES the child's environment rather than merging with it, so this
+// always spreads `process.env` first — passing `hardenGitEnv()` with no
+// argument must be behaviourally identical to inheriting the parent
+// environment plus the two hardening vars, never a stripped-down one.
+export function hardenGitEnv(extraEnv) {
+  return { ...process.env, ...GIT_HARDENED_ENV, ...(extraEnv || {}) };
+}