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

package/src/report/index.js

@@ -4,6 +4,20 @@ import { _isCustomSuppressed } from '../engine.js';
 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' };
@@ -83,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);
@@ -107,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
@@ -249,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,
@@ -348,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||[])) {
@@ -375,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||[])) {
@@ -424,8 +534,28 @@ 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
+  // before this shape reaches ANY consumer (JSON/SARIF/HTML/CSV/JUnit/MCP
+  // all derive from this one function) — one place, covers every output
+  // format, matches this function's own role as "the canonical shape".
+  for (const f of out) applyLegacyCompat(f);
+
   // Sort by severity tier, then within a tier by EPSS percentile (desc) so that
   // CVEs with active in-the-wild abuse float above theoretical CVEs.
   return out.sort((a, b) => {
@@ -516,6 +646,13 @@ export function toJSON(scan, meta={}, opts={}){
     // threw and were skipped. The findings still ship; downstream consumers
     // see the gap.
     annotatorErrors: Array.isArray(scan.annotatorErrors) ? scan.annotatorErrors : [],
+    // FR-201 (assurance-hardening PRD, E2): per-file SAST/logic/secrets
+    // detector errors, captured by pipeline/detector-runner.js's runDetector()
+    // isolation wrapper. Empty array means clean; entries here mean one or
+    // more detectors threw on a specific file and were skipped -- other
+    // detectors and other files still ran (that isolation is the acceptance
+    // criterion itself, not just this field's presence).
+    detectorErrors: Array.isArray(scan.detectorErrors) ? scan.detectorErrors : [],
     // R4 — run attestation: a stable, order-independent digest over this
     // finding set bound to the engine/ruleset/bundle that produced it.
     // Attached by the CLI (posture/attestation.js); null when not computed.
@@ -529,6 +666,10 @@ export function toJSON(scan, meta={}, opts={}){
     // render an empty one. An AUTHORISED suppression is reported too — the
     // signature proves who asked for it, not that the results are absent.
     suppressedRules: scan.suppressedRules || null,
+    // FR-108: null in the (eventual, intended) steady state where no finding
+    // used a deprecated field name; present only when normalizeFindings()
+    // actually backfilled a legacy alias, naming exactly which and why.
+    legacyFieldNotice: legacyFieldDeprecationNotice(findings),
     _scanMeta: scan._scanMeta || null,
     // S7: engine.js computes these on every scan with components, and their
     // own findings already flow into `findings` above — but the structured
@@ -546,6 +687,21 @@ export function toJSON(scan, meta={}, opts={}){
     rootCauseSweep: scan.rootCauseSweep || null,
     attackTaxonomy: scan.attackTaxonomy || null,
     privacyFramework: scan.privacyFramework || null,
+    // FR-405: `false` is a real, meaningful value here (privacy analysis
+    // ran but was not IR-backed) — must not collapse to null via `||`,
+    // which would make it indistinguishable from "never ran at all".
+    privacyIrBacked: scan.privacyIrBacked ?? null,
+    // FR-402: which privacy data-classification taxonomy version actually
+    // classified this scan (built-in, or built-in+custom when an operator's
+    // .agentic-security/privacy-taxonomy.json extended it) — see
+    // dataflow/privacy-taxonomy.js. Null means the annotator never ran.
+    privacyTaxonomyVersion: scan.privacyTaxonomyVersion ?? null,
+    // Assurance-hardening PRD FR-206 (Milestone 0): additive scan-health
+    // summary (pipeline/scan-health.js) — separates "no findings" from
+    // "analysis complete". Null when the engine did not compute one (e.g. a
+    // hand-built `scan` object in a test), same convention as the S7 fields
+    // above; a real scan always computes it.
+    scanHealth: scan.scanHealth || null,
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];
   return out;
@@ -643,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');
@@ -699,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', ''];
@@ -731,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');
@@ -808,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 => {
@@ -872,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 } : {}),
         },
       };}),
     }],
@@ -933,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;
@@ -1011,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>
@@ -1066,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;
@@ -1145,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;
@@ -1171,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 };
@@ -1284,17 +1511,33 @@ export function toShipVerdict(scan, options = {}) {
   const confirmedCount = findings.filter(f => f.validated === true || f.confirmed === true).length;
   const cats = categoryScores(findings);
 
+  // FR-206: "a partial zero-finding scan never says clean." `scanHealth`
+  // (computeScanHealth, scan-health.js) was already computed correctly —
+  // an annotator error, a file timeout, or a skipped analyzer already
+  // demoted `status` to 'partial' — but nothing in this, the actual
+  // human-facing one-screen verdict, ever consulted it. Zero actionable
+  // findings on a scan that didn't finish cleanly is "we don't know," not
+  // "safe."
+  const scanIncomplete = scan.scanHealth && scan.scanHealth.status && scan.scanHealth.status !== 'complete';
+
   const lines = [];
   const bar = '─────────────────────────────────────────';
   // Patch the mascot reacts to the result — APPROVE if clean, ALERT if findings.
-  lines.push(actionable.length === 0 ? approveFace({ color }) : alertFace({ color }));
+  const clean = actionable.length === 0 && !scanIncomplete;
+  lines.push(clean ? approveFace({ color }) : alertFace({ color }));
   lines.push(bar);
-  if (actionable.length === 0) {
+  if (clean) {
     lines.push(c('  ✅  Safe to deploy', SEV_COLOR.low + BOLD));
+  } else if (actionable.length === 0) {
+    lines.push(c('  ⚠️  Scan incomplete — cannot confirm safe to deploy', SEV_COLOR.high + BOLD));
   } else {
     lines.push(c('  ❌  Not safe to deploy', SEV_COLOR.critical + BOLD));
   }
   lines.push(bar);
+  if (scanIncomplete) {
+    const conditions = Array.isArray(scan.scanHealth.conditions) ? scan.scanHealth.conditions : [];
+    lines.push(c(`  ${scan.scanHealth.status}: ${conditions[0] || 'analysis did not complete cleanly'}${conditions.length > 1 ? ` (+${conditions.length - 1} more)` : ''}`, SEV_COLOR.high));
+  }
   lines.push(`  • ${sev.critical} critical · ${sev.high} high · ${advisoryCount} advisory`);
   // Per-category 0..100 score bars — Secrets / Permissions / Hooks / MCP / Agents.
   // Only render when at least one category has been contributed to (skip the

package/src/report/oscal.js

@@ -50,6 +50,7 @@
 import crypto from 'node:crypto';
 import { isDeterministic, SCANNER_VERSION } from '../posture/deterministic.js';
 import { normalizeFindings, TOOL_CAVEATS } from './index.js';
+import { EVIDENCE_GRADE_DISCLAIMER } from '../posture/evidence-grade-wording.js';
 
 // The OSCAL release these documents declare conformance to. Bump deliberately:
 // `oscal-version` is a claim a validator checks the rest of the document
@@ -620,9 +621,13 @@ export function toOSCALCompliance(framework, rows, meta = {}) {
       observations,
       ...(findings.length ? { findings } : {}),
       ...(risks.length ? { risks } : {}),
+      // FR-507: names all three assurance tiers explicitly, not just "not
+      // certified" — see evidence-grade-wording.js for why that distinction
+      // matters (a reader who has never heard "attestation" used correctly
+      // has no way to know a real one is a different, valid artifact they
+      // might separately need).
       remarks:
-        'This document organizes automated scanner evidence against a control set. It is not an attestation '
-        + 'of compliance and no licensed assessor reviewed it. '
+        `${EVIDENCE_GRADE_DISCLAIMER} No licensed assessor reviewed this document. `
         + TOOL_CAVEATS.map(c => `${c.id}: ${c.shortDescription}`).join(' | '),
     }],
     'back-matter': { resources: [frameworkResource, ...caveats] },

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/cpp.js

@@ -16,6 +16,7 @@
 //   - hardcoded         hardcoded user/password in fopen / connect calls
 
 import { blankComments } from './_comment-strip.js';
+import { classifySecretCandidate as _entropyClassifySecret } from './_secret-entropy.js';
 
 // ── context detectors ───────────────────────────────────────────────────────
 
@@ -279,14 +280,8 @@ const FINDINGS = [
       const val = m && m[2];
       if (!val) return false;
       try {
-        // Lazy import — avoids a circular dep on the entropy module being
-        // present in older snapshots.
-        // eslint-disable-next-line no-unused-vars
-        const { classifySecretCandidate } = _entropyMod || {};
-        if (classifySecretCandidate) {
-          const r = classifySecretCandidate(val);
-          if (r.skip) return false;
-        }
+        const r = _entropyClassifySecret(val);
+        if (r.skip) return false;
       } catch { /* fail open */ }
       return true;
     },
@@ -319,12 +314,6 @@ const FINDINGS = [
   },
 ];
 
-// Late-bound entropy module — imported via a dynamic require shim so the
-// rule table can lazy-call it from inside gate functions without creating
-// a circular import at module load time.
-let _entropyMod = null;
-import('./_secret-entropy.js').then(m => { _entropyMod = m; }).catch(() => { _entropyMod = null; });
-
 function lineOf(raw, idx) { return raw.substring(0, idx).split('\n').length; }
 
 export function scanCpp(fp, raw) {

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/sca/llm-function-extract.js

@@ -9,6 +9,7 @@
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { evaluateEgress } from '../egress/policy.js';
 
 const CACHE_DIR = process.env.XDG_CONFIG_HOME
   ? path.join(process.env.XDG_CONFIG_HOME, 'agentic-security', 'llm-sca-cache')
@@ -63,6 +64,11 @@ export async function extractVulnFunctionsViaLLM(supplyChain, opts = {}) {
   if (!isLlmScaEnabled()) return [];
   const config = _endpointConfig();
   if (!config) return [];
+  // FR-601: one decision for the whole batch (same endpoint for every CVE in
+  // this run) — evaluated before any of the per-candidate prompts below are
+  // built.
+  const egressDecision = evaluateEgress({ scanRoot: opts.scanRoot, purpose: 'sca-llm-function-extract', endpoint: config.endpoint });
+  if (!egressDecision.allowed) return [];
 
   const enriched = [];
   const candidates = (supplyChain || []).filter(sc =>