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

package/src/posture/vuln-archaeology.js

@@ -34,6 +34,7 @@
 // timeout, degrading to an empty result in a non-repository.
 
 import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 const CVE_RE = /\b(?:CVE-\d{4}-\d{4,7}|GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})\b/i;
 
@@ -87,14 +88,19 @@ export function classifyCommit(subject) {
   return { tier: 'mentioned', evidence: `mentions "${noun[0]}" with no fix verb` };
 }
 
+// `scanRoot` is the scanned project'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's `_run`). No `--no-textconv` needed: this
+// invocation has no `-p`/`-L`, so no diff/blob content is rendered.
 function _gitLog(scanRoot, { maxCommits, timeoutMs }) {
   // NUL-delimited records so subjects containing newlines cannot split a
   // record — a commit message is arbitrary user text and must not be able to
   // forge a record boundary.
-  const out = execFileSync('git', [
+  const out = execFileSync('git', hardenGitArgs([
     '-C', scanRoot, 'log', '-n', String(maxCommits), '--no-merges', '--no-color',
     '--name-only', '--format=%x00%H%x1f%aI%x1f%s',
-  ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  ]), { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() });
   const commits = [];
   for (const block of out.split('\0')) {
     if (!block.trim()) continue;

package/src/pr-delta.js

@@ -24,18 +24,27 @@
 // comment) can transform without re-walking IR.
 
 import { spawnSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from './util/git-hardening.js';
 import { runFullScan } from './engine.js';
 
 const FILE_EXT_RE = /\.(?:js|jsx|ts|tsx|mjs|cjs|py|java|cs|kt|go|rb|php|sol|swift|rs|tf|yml|yaml|json|toml|md)$/i;
 const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
 
+// `root` is the PR's repository — a scan target, 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's `_run`).
 function _git(root, args) {
-  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync('git', hardenGitArgs(args), { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: hardenGitEnv() });
   return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '' };
 }
 
 function _readFileAtRef(root, ref, file) {
-  const r = _git(root, ['show', `${ref}:${file}`]);
+  // `--no-textconv`: this blob-cat form of `show` (`<ref>:<file>`, not a
+  // diff) was verified NOT reachable via a hostile textconv driver in
+  // current git, same as git-evidence.js's getBlobAtCommit — kept for
+  // defense-in-depth/uniformity.
+  const r = _git(root, ['show', '--no-textconv', `${ref}:${file}`]);
   return r.ok ? r.stdout : null;
 }
 
@@ -56,7 +65,12 @@ async function _scanAtRef(root, ref) {
     const c = _readFileAtRef(root, ref, f);
     if (c != null) fileContents[f] = c;
   }
-  return runFullScan({ fileContents, scanRoot: root }, () => {});
+  // `provenance:false` — a base-ref snapshot, not the current working state.
+  // Beyond the wasted git walks, updateLifecycle marks every open stableId
+  // absent from the finding set it is handed as `remediated`; running the PR
+  // delta gate would silently rewrite the project's lifecycle store from the
+  // base ref's findings.
+  return runFullScan({ fileContents, scanRoot: root, provenance: false }, () => {});
 }
 
 function _summary(findings) {
@@ -71,7 +85,14 @@ function _summary(findings) {
 }
 
 function _changedFiles(root, baseRef, headRef) {
-  const r = _git(root, ['diff', '--name-only', `${baseRef}...${headRef}`]);
+  // `--no-ext-diff`: found during the second-audit-remediation sweep — this
+  // is a `git diff` call site (`--name-only`, no content rendered, so not
+  // itself a verified exploit path today, same as runScan.js's
+  // `changedSince`), but every `diff` invocation in this codebase gets it
+  // uniformly per the live exploit VERIFIED in material-change.js's
+  // classifyGitDiff (external diff drivers fire on `git diff` even with
+  // `--no-textconv`, which is a surface `--no-textconv` alone does not close).
+  const r = _git(root, ['diff', '--name-only', '--no-ext-diff', `${baseRef}...${headRef}`]);
   if (!r.ok) return new Set();
   return new Set(r.stdout.trim().split('\n').filter(Boolean));
 }

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/server/CLAUDE.md

@@ -0,0 +1,47 @@
+# scanner/src/server/
+
+The `agentic-security explore` local server — Milestone 3 of the Data
+Flow Explorer PRD ("local server and secure API," PRD §17). Read-only in
+this increment; serves the already-scanned, already-signed
+`DataFlowGraph v1` artifact over a hardened loopback HTTP API.
+
+## What's here
+
+**Sub-project Server, increment 1 (read-only GET endpoints + full
+security posture) — COMPLETE:**
+
+| Module | Responsibility |
+|---|---|
+| `docs/superpowers/plans/2026-09-01-data-flow-explorer-m3-server-scoping.md` + `…-s1-plan.md` | Confirms the entire deliverable was greenfield (no HTTP server code anywhere; the MCP server is JSON-RPC-over-stdio, the LSP server a different stdio protocol — neither has an HTTP surface). Scopes S1 to the five P0 GET endpoints only, deferring `query`/`export` (real design work of their own) to S2/M4. Every §17.4 security bullet is a first-class S1 requirement, not a follow-up pass, since `docs/DATA_FLOW_EXPLORER_THREAT_MODEL.md`'s own T2 (DNS rebinding)/T3 (CSRF)/T4 (path traversal) entries are explicitly gated on "the server does not exist yet." |
+| `graph-loader.js` | `loadSignedGraph(scanRoot)` — reads `.agentic-security/lineage-graph.json` + `.sig`, reusing `posture/integrity.js`'s `verifyLastScan` DIRECTLY (never a second, parallel verification mechanism — that function already uses `crypto.timingSafeEqual` internally). Four distinct, clearly-messaged failure reasons: `missing` (no file), `unsigned` (`.sig` absent), `tampered` (signature mismatch), `malformed` (valid signature, invalid JSON). Loaded once at server startup, held in memory — this is a read-only, single-scan-snapshot server; a change to the graph on disk mid-session is out of scope (the threat model doc's own "P0 is read-only" framing). |
+| `security.js` | `generateSessionToken()` (32 random bytes, hex); `constantTimeEqual(a, b)` (wraps `crypto.timingSafeEqual`, length-guarded the same way `verifyLastScan` guards its own HMAC comparison — never throws on mismatched-length input); `isValidHost(hostHeader, expectedPort)` — the T2 DNS-rebinding defense, accepting only `127.0.0.1`/`localhost`/`::1` (bare or bracketed) at the exact expected port, rejecting everything else including alternate-encoded loopback forms (decimal/octal/hex IP literals) — a hostile page's own Host header carries ITS OWN origin, never `127.0.0.1`, so this check defeats DNS rebinding regardless of browser same-origin-policy quirks; `CSP_HEADER_VALUE = "default-src 'none'; frame-ancestors 'none'"` (maximally restrictive — this server serves JSON only in S1, no HTML/inline script surface at all). |
+| `routes.js` | Six PURE handler functions, each `(graph, ...) -> {status, body}` — `handleScan`, `handleGraph`, `handleNode`, `handleEdge`, `handleFlow`, `handleQuery` — no `req`/`res` access anywhere in this file, independently unit-testable without an HTTP layer. `wrapResponse(data, graph, {canonicalIds})` wraps every body in the exact envelope PRD line 1326 requires ("base graph/snapshot digest, schema/extension versions, scope, coverage, limitations, and contributing canonical IDs"), mapped onto the graph's own real fields (`graphId`→digest, `schemaVersion`, `extensions`, `scope`, `coverage`, `limitations`). `canonicalIds` is `null` for `handleScan`/`handleGraph`/`handleQuery` (all three describe the whole graph or a filtered projection of it — `handleGraph`'s own body already IS the full node/edge/flow arrays, so re-listing every id would be pure duplication with real cost on a large graph), `[id]` for `handleNode`/`handleEdge`, and the flow's own id plus its `source`/`sink`/`edgeIds` for `handleFlow` (a derived record referencing several other entities — naming them is genuinely useful metadata, not duplication). **`handleQuery(graph, filter)`** (Milestone 5, large-graph pagination — the `POST /api/v1/query` endpoint the S1-era header comment above and this file's own "What this does NOT do" section used to defer) shape-validates `filter` via `export-json.js`'s `validateFilterShape` (400 on a malformed filter, never a thrown exception) and, when valid, narrows the graph via that same module's already-shipped, already-tested `_filterGraph` — the identical `{nodeIds, edgeIds}` shape `dataflow export --filter` and the MCP `dataflow_get_graph` tool already use, reused rather than reimplemented. `undefined`/`{}` returns the whole graph, identical to `handleGraph`. |
+| `http-server.js` | `createExploreServer({graph, port, sessionToken, idleTimeoutMs, keepOpen})` — the first `node:http` usage anywhere in `scanner/src/`. Binds explicitly to `127.0.0.1` (never `0.0.0.0`, never an omitted host argument — that is NOT the same as `127.0.0.1` on every platform). Every request: `Host` header validated (T2, 400 on failure) BEFORE the session token (T3, 401 on failure, `constantTimeEqual`) BEFORE a uniform request-size cap (`MAX_REQUEST_BODY_BYTES = 64KB`, 413 on excess — S1's GET endpoints have no meaningful body; Milestone 5's `POST /api/v1/query` is the first real consumer of the body-accumulation this cap now gates) BEFORE routing. `POST /api/v1/query`'s request body is accumulated alongside the pre-existing size-cap check and JSON-parsed only for a matched route with a non-empty body (malformed JSON → 400, never a 500) — every pre-M5 GET route still ignores the handler's 3rd `body` argument entirely, so an empty/missing body for them stays a no-op, unchanged. Every response: `Content-Security-Policy` set, `Cache-Control: no-store` set, `Access-Control-Allow-Origin` NEVER set anywhere in this file (CORS stays disabled by the header's own absence — do not add a permissive default later without re-reading this line). Idle-timeout auto-stop (`DEFAULT_IDLE_TIMEOUT_MS = 30 min`, no PRD-specified number exists, a disclosed reasoned default) resets ONLY on requests that pass BOTH the Host and token checks — an unauthenticated prober (a DNS-rebinding attempt, a stray scan) can never keep the server alive by hammering it; only genuine authenticated activity extends the session. `keepOpen: true` suppresses auto-stop entirely. Logging is metadata-only (method/path/status/duration) — never response bodies, never the session token, even on a failed-auth attempt. A 500 from a route handler returns a generic `{error: 'internal error'}` body, never the underlying exception's message/stack. **Disclosed, non-security gap**: no `SIGINT`/`SIGTERM` handler exists yet, so Ctrl-C relies on Node's default abrupt-exit rather than a graceful `server.close()` — functionally fine (the process does exit) but not maximally graceful; a future increment could add one for a cleaner shutdown message. |
+| `bin/agentic-security.js` (extended, additively) | `case 'explore':` + `cmdExplore(args)` — parses the scan root (`args._[1]`, default cwd), `--port` (validated: digits-only, ≤65535), `--keep-open`. Calls `loadSignedGraph` FIRST; on any failure, prints the specific clear message and exits non-zero WITHOUT ever starting the server (never binds a port, never generates a token, on a missing/tampered/unsigned/malformed graph). On success, generates a fresh session token per invocation and prints it to stdout EXACTLY ONCE — the only place it is ever displayed, never written to a file, never logged again after this one print. Returns a Promise resolving to exit code 0 when the server eventually closes (idle-timeout or an external kill), matching every other `cmdX(args)` function's own "returns a numeric exit code" contract while still supporting a long-running process. `explore` never triggers a scan itself — it requires a pre-existing artifact, matching §17.3's own "P0 is read-only with respect to source" framing exactly. |
+| `test/server/*.test.js` (41 tests) | `security.test.js`/`graph-loader.test.js`/`routes.test.js` — pure-function unit tests (isolated `constantTimeEqual`/`isValidHost` edge cases; all four `loadSignedGraph` failure reasons via a real signed/tampered/unsigned/malformed fixture; all five route handlers' shapes). `http-server.test.js` — REAL end-to-end `node:http.request` calls against a REAL running server (never a mocked/isolated unit test for the security-critical properties): a forged `Host` header rejected live (T2); a missing AND a wrong session token rejected live on every one of the five endpoints (T3); response headers asserted present/absent on BOTH a 200 and a rejected response; a real short-idle-timeout variant proving the server genuinely stops listening and refuses new connections (`ECONNREFUSED`), and a `keepOpen: true` variant proving it doesn't; an oversized-body 413. `cmd-explore.test.js` — the real spawned CLI end to end (missing graph → non-zero exit, no token ever printed, connection refused; a valid signed graph → a real server whose printed URL + token authenticate a real request). Independently re-verified by the coordinator via a THIRD path beyond the implementer's own tests: a real `explore` invocation launched manually, hit with `curl` from outside any test harness, confirming the same 200/401/400 outcomes and headers live. |
+
+**Sub-project Wire (live-API wiring for the frontend) — COMPLETE:**
+
+| Module | Responsibility |
+|---|---|
+| `docs/superpowers/plans/2026-09-01-data-flow-explorer-m3-wire-scoping.md` + `…-plan.md` | The load-bearing correction this increment starts from: §17.4's CORS-disabled-by-default posture means the frontend MUST be served from the SAME origin as the API, or the browser blocks every `fetch()` regardless of what the server returns. Decides the session token travels via a URL FRAGMENT (`#token=...`), never a query string or cookie — a fragment is never sent to the server in any HTTP request. |
+| `static-assets.js` | `FRONTEND_ROOT` (located via the exact `path.dirname(fileURLToPath(import.meta.url))` pattern `mcp/server.js` already established, resolved to the real `frontend/` directory). `resolveStaticAsset(requestPath)` — a PURE function, no fs/http access — resolving a request pathname against an explicit ALLOWLIST (`index.html`; `src/**/*.js`; top-level `styles/*.css` only, no nested subdirs) and returning `{ok:true, relativePath, contentType}` or `{ok:false, reason}`. This is a real allowlist, not merely a `../`-traversal guard: `test/`, `scripts/`, `package.json`, `README.md`, `CLAUDE.md`, `.gitignore` are all real files that exist on disk under `frontend/` and are REJECTED (`reason: 'not-allowlisted'`) even though a naive "stays inside frontend/" check would happily serve them. Traversal defense re-checks AFTER `path.posix.normalize` (never trusts normalization alone) for both literal and percent-encoded (`%2e%2e`) `..`; null bytes are rejected both literally and as a decoded `%00`; absolute-URL-looking input (a scheme, or `//host/...`) is rejected outright. `STATIC_CSP_HEADER_VALUE` is a SEPARATE, same-origin-permitting CSP (`script-src 'self'` etc., no `'unsafe-inline'`) from `security.js`'s `CSP_HEADER_VALUE` (`default-src 'none'`, unchanged, still used on every `/api/v1/*` response). |
+| `http-server.js` (extended) | New static-asset branch, checked for every `GET` request whose path does NOT start with `/api/` — resolved BEFORE the session-token check (the ONE deliberate, disclosed exception to "every request requires a token": the token lives in a URL fragment the browser never sends, so the very first page-load request is structurally incapable of carrying it) but AFTER the Host-header check (T2 applies uniformly, auth or not). A rejected static path is a 404, never a 403 (never confirms a path's existence to a prober). Static responses carry `STATIC_CSP_HEADER_VALUE` + `Cache-Control: no-store` (unchanged) + the resolved Content-Type; `Access-Control-Allow-Origin` is still never set. The idle-auto-stop timer is deliberately NOT reset by an unauthenticated static-asset request — only genuine, authenticated `/api/v1/*` activity extends the session, unchanged from S1's own invariant. |
+| `bin/agentic-security.js`'s `cmdExplore` (extended) | The printed URL changed from `http://127.0.0.1:<port>/api/v1/scan` to `http://127.0.0.1:<port>/#token=<64-hex-token>` — still the ONE place the token is ever displayed, now carried as a URL fragment instead of a separate "Token:" line, with updated wording ("open this URL in a browser" rather than "pass the token as a header manually"). |
+| `frontend/src/lib/api-client.js` (new, in `frontend/`) | `extractTokenFromFragment()` (parses `location.hash` for `#token=<hex>`, tolerant of other hash params shell.js may also be writing) and `fetchGraph({token, baseUrl})` (fetches `/api/v1/graph` with the token header, unwraps the `.data` envelope field). `baseUrl` defaults to `''` (a same-origin relative fetch — the only thing the shipped page itself ever passes) and exists solely so a test can point this at a real running server without a headless browser. |
+| `frontend/src/main.js` (new, in `frontend/`) | Replaces `index.html`'s old inline `<script type="module">` block (which would have needed `'unsafe-inline'` under `STATIC_CSP_HEADER_VALUE`) with an external module: extracts the token, calls `fetchGraph`, calls the EXISTING, UNCHANGED `bootstrap(root, graph)`, and shows a plain visible error in `#app-root` on fetch failure — never a silent blank page. |
+| `test/server/static-assets.test.js` (new) | Pure-function tests — every real allowlisted path resolves with the right content type; several REAL on-disk-but-not-allowlisted files (`test/dom-shim.js`, `package.json`, `README.md`, `CLAUDE.md`, `.gitignore`, the generator script) are rejected; traversal (several encodings, including percent-encoded `..` and multi-segment escapes) and null-byte (literal and `%00`) rejection. |
+| `test/server/http-server.test.js` (extended) | Real, live HTTP requests against a real running server for the new surface: `GET /` with NO token succeeds and serves the real `index.html`; `GET /api/v1/graph` with no token still 401 (the exemption is static-route-only); static responses carry the separate static CSP, never `default-src 'none'`; a forged `Host` header is still rejected on a static route; a live `../`-traversal attempt is rejected 404; the same on-disk-but-unlisted files are rejected 404 over real HTTP, never 403. |
+| `test/server/cmd-explore.test.js` (updated) | Re-asserts the CLI's printed-URL regex against the new fragment-token form and that no separate "Token:" line is ever printed. |
+| `frontend/test/api-client.test.js`, `frontend/test/live-fetch-parity.test.js` (new, in `frontend/`) | `extractTokenFromFragment`/`fetchGraph` unit tests (mocked fetch) plus the AC-16 proof: a REAL `explore` server started over the REAL flagship-graph fixture, fetched through the REAL `api-client.js` over a REAL loopback HTTP connection (no mock), asserted content-identical to the static-import baseline, then rendered through the SAME, UNCHANGED `bootstrap()` and asserted to produce a structurally IDENTICAL DOM tree to the existing static-import baseline's own render. |
+
+## What this does NOT do
+
+`POST /api/v1/export` (the self-contained-export pipeline, §17.5 — Milestone 4 territory per the parent M3 scoping doc). Any Milestone 4/5 decision-intelligence endpoint (`stories/`, `scenarios/`, `snapshots/`, `diffs/`, `obligations/`, `runtime/`, `recipients/`, `impact/`, `remediation/`, `rescan`). Wiring `frontend/` to this server (Sub-project Wire's own job — this server is built and tested standalone, in complete isolation from `frontend/`). File/line evidence path resolution and its own T4 path-traversal confinement test (no such lookup exists in S1's five endpoints — the graph JSON is served verbatim, so T4 correctly has no surface yet, the same honest status the threat model doc itself records). Triggering a scan from `explore` itself. Any language beyond what the graph itself already covers (this server is language-agnostic — it serves whatever graph exists).
+
+## Conventions
+
+- **No new npm dependency, ever, without re-opening this decision first.** `node:http`/`node:crypto`/`node:fs` only — matches this repo's own minimalism convention (`validate.js`'s own "no new npm dependency" precedent) and the MCP/LSP servers' own hand-rolled-protocol precedent. If a future increment genuinely needs a framework, that is a real, separately-justified decision, not a default.
+- **CORS stays disabled by the ABSENCE of `Access-Control-Allow-Origin`.** Never add this header with a permissive value (`*`, or an echoed `Origin`) anywhere in this package without a real, disclosed threat-model reason — its absence is load-bearing security posture, not an oversight.
+- **Every security-relevant string comparison goes through `constantTimeEqual`** (`security.js`), never `===`/`!==` on a token or secret.
+- **A route handler's thrown error must never reach the client verbatim** — `http-server.js`'s own catch-and-genericize behavior around route dispatch is load-bearing; a future endpoint must not bypass it.