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

package/src/posture/provenance-evidence-bundle.js

@@ -0,0 +1,144 @@
+// Signed provenance evidence bundles (Finding Provenance PRD, M4 §4.1).
+//
+// Sibling to posture/evidence-bundle.js, not a generalization of it — that
+// module's bundle shape (proofTier, taintPath, exploitability...) answers
+// "is this finding real"; this one answers "who/when introduced it, how
+// sure are we." Forcing one shape to cover both would leave half of every
+// bundle null. Same four-function pattern (build/sign/verify + a schema
+// string + a top-level-key allowlist), same Ed25519 key material — reused,
+// not reimplemented.
+//
+// The allowlisted fields mirror provenance/coordinator.js's own
+// computeDigest() material EXACTLY (stableId, findingOrigin.commit,
+// branchIntroduction.commit, evidenceAttribution role:path:line:commit
+// strings, method, confidence.reasons, limitations) plus repo/HEAD identity
+// (not in computeDigest's material, since that digest never leaves the repo
+// it was computed in, but a bundle does). Everything here is copied from
+// what findingProvenance already computed. Nothing is inferred.
+//
+// canonicalJson vs canonicalBytes — resolved before writing this file
+// -------------------------------------------------------------------
+// evidence-bundle.js exports TWO canonicalisation helpers, not one, and they
+// are not interchangeable. `canonicalJson(value)` is a pure, shape-agnostic
+// deterministic serialiser (sorted keys at every level, order-preserving
+// arrays) — safe to reuse for any bundle shape. `canonicalBytes(bundle)`
+// is NOT generic: it hardcodes evidence-bundle.js's own six top-level keys
+// (`schema, finding, evidence, engine, proves, doesNotProve`) when building
+// the object it signs. Reusing `canonicalBytes` here would silently sign a
+// filtered object missing this module's `repo` and `provenance` fields
+// (and would read `bundle.evidence`, which a provenance bundle never has) —
+// exactly the EA-03 failure mode the allowlist check below exists to catch,
+// just introduced from the signing side instead of the verifying side. So
+// this module imports the generic `canonicalJson` (as the brief's Step 1
+// sketch already did) and signs `canonicalJson(bundle)` directly, since
+// `buildProvenanceEvidenceBundle` never puts anything on the unsigned
+// object beyond this module's own allowlisted fields.
+
+import * as crypto from 'node:crypto';
+import { ensureKeyPair, keyPaths, canonicalJson } from './evidence-bundle.js';
+
+export const PROVENANCE_BUNDLE_SCHEMA = 'agentic-security/provenance-evidence@1';
+
+const PROVES = 'This bundle\'s contents are exactly what was signed at attestation time.';
+const DOES_NOT_PROVE = 'This bundle does NOT prove the origin commit is correctly identified — read confidence.level and limitations for that. It proves the RECORD is unmodified, not that the record is right.';
+
+/**
+ * Build an unsigned provenance bundle from one finding's findingProvenance.
+ * Returns null for a finding with no findingProvenance at all (nothing to
+ * attest) — this is a caller error (attest a scan before its provenance
+ * pass ran), not a case to paper over with an empty bundle.
+ */
+export function buildProvenanceEvidenceBundle(finding, { engineVersion, repoIdentity, head } = {}) {
+  if (!finding || typeof finding !== 'object') return null;
+  const fp = finding.findingProvenance;
+  if (!fp || typeof fp !== 'object') return null;
+  return {
+    schema: PROVENANCE_BUNDLE_SCHEMA,
+    finding: {
+      id: finding.id ?? null,
+      stableId: finding.stableId ?? null,
+    },
+    repo: {
+      identity: repoIdentity ?? null,
+      head: head ?? fp.analysisBasis?.head ?? null,
+    },
+    provenance: {
+      status: fp.status ?? null,
+      findingOrigin: fp.findingOrigin
+        ? {
+            commit: fp.findingOrigin.commit ?? null,
+            authorName: fp.findingOrigin.authorName ?? null,
+            authorDate: fp.findingOrigin.authorDate ?? null,
+            summary: fp.findingOrigin.summary ?? null,
+          }
+        : null,
+      branchIntroduction: fp.branchIntroduction
+        ? { commit: fp.branchIntroduction.commit ?? null, branch: fp.branchIntroduction.branch ?? null }
+        : null,
+      evidenceAttribution: (fp.evidenceAttribution || []).map((n) => ({
+        role: n.role ?? null, path: n.path ?? null, line: n.line ?? null, commit: n.commit ?? null,
+      })),
+      method: fp.method ?? null,
+      confidence: fp.confidence
+        ? { level: fp.confidence.level ?? null, score: fp.confidence.score ?? null, reasons: fp.confidence.reasons || [] }
+        : null,
+      limitations: fp.limitations || [],
+      // M4 §4.2 final-review fix: this module was written (Task 1) before
+      // the cross-repo lineage feature existed (Task 5), so a
+      // cross-repo-resolved origin's boundary-crossing marker was dropped
+      // from the signed bundle — a foreign repository's commit SHA and a
+      // real author name, with no MACHINE-READABLE signal that the origin
+      // crossed a repository boundary (only the prose in `limitations`
+      // said so, and a programmatic verifier does not read prose). Nested
+      // under `provenance` alongside the fields above, so it is part of
+      // what gets signed — never a new top-level key.
+      historyCoverage: { crossRepoLineage: fp.historyCoverage?.crossRepoLineage ?? false },
+    },
+    engine: { engineVersion: engineVersion ?? null },
+    proves: PROVES,
+    doesNotProve: DOES_NOT_PROVE,
+  };
+}
+
+export function signProvenanceEvidenceBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, Buffer.from(canonicalJson(bundle), 'utf8'), privateKeyPem);
+  return {
+    ...bundle,
+    signature: { algorithm: 'ed25519', canonicalisation: PROVENANCE_BUNDLE_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+const PROVENANCE_BUNDLE_TOP_LEVEL_KEYS = new Set([
+  'schema', 'finding', 'repo', 'provenance', 'engine', 'proves', 'doesNotProve', 'signature',
+]);
+
+/**
+ * Verify with a PUBLIC key only. Rejects any top-level key outside the
+ * allowlist BEFORE checking the signature — same EA-03 fix evidence-bundle.js
+ * carries: a signature only covers the bytes it was computed over, so an
+ * unknown key stapled on after signing would otherwise verify as authentic.
+ */
+export function verifyProvenanceEvidenceBundle(bundle, publicKeyPem) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  if (bundle.schema !== PROVENANCE_BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  const unknownKeys = Object.keys(bundle).filter((k) => !PROVENANCE_BUNDLE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  const { signature, ...unsigned } = bundle;
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(canonicalJson(unsigned), 'utf8'), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return ok
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+}
+
+export { ensureKeyPair, keyPaths };

package/src/posture/retention-policy.js

@@ -0,0 +1,132 @@
+// Retention policy: default and maximum TTL by artifact class (assurance-
+// hardening PRD FR-702).
+//
+// "Enforce default and maximum TTL by artifact class | Expired caches,
+// scans, evidence, tickets, and backups are purged or archived according
+// to policy."
+//
+// TWO NUMBERS PER CLASS, ON PURPOSE
+// --------------------------------------------------------------------------
+// `defaultDays` is what applies when nobody configures anything — a
+// reasonable, disclosed starting point, not a regulatory citation (an
+// operator with a real compliance regime should configure their own via
+// the policy file below). `maxDays` is a CEILING an operator's own
+// configuration cannot exceed: the literal "default AND maximum" wording
+// asks for both a floor-free default and a hard cap, not just a knob. An
+// operator who wants indefinite retention for `evidence` for their own
+// audit reasons should say so in their own retention program — this
+// module will not silently allow a TTL past its built-in ceiling for a
+// class, because "TTL" than can be configured to "never" is not a TTL.
+//
+// PURGE, NOT ARCHIVE
+// --------------------------------------------------------------------------
+// The acceptance criterion allows either. This implements PURGE (delete)
+// only — the simpler, safer, and more directly verifiable of the two.
+// "Archive" implies a defined export format and destination, which is
+// FR-706's own separate scope (manifest-based export); an operator who
+// wants to archive before purging already has the tool for it once FR-706
+// exists, or can back up `.agentic-security/` by their own means before
+// running the enforcement command.
+//
+// WHICH ARTIFACTS THIS APPLIES TO
+// --------------------------------------------------------------------------
+// Only 'generated' artifacts carrying a `retentionClass` in
+// artifact-registry.js — deliberately a SUBSET of all generated artifacts
+// (see that module's own header for which ones were left classless and
+// why). An 'operator-config' artifact is NEVER touched by this module,
+// regardless of age, matching FR-703's own "reset preserves operator-
+// authored configuration" precedent.
+
+import * as fs from 'node:fs';
+import * as yaml from '../util/yaml.js';
+import { statePath, stateDir } from './state-dir.js';
+import { listArtifactsWithRetentionClass } from './artifact-registry.js';
+import { loadLegalHolds, isUnderHold } from './legal-hold.js';
+
+const POLICY_FILE = 'retention-policy.yml';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// Engineering defaults, not a regulatory claim — see the header above.
+export const RETENTION_DEFAULTS = {
+  cache: { defaultDays: 7, maxDays: 30 },
+  scan: { defaultDays: 90, maxDays: 365 },
+  evidence: { defaultDays: 365, maxDays: 1095 },
+  ticket: { defaultDays: 180, maxDays: 730 },
+  backup: { defaultDays: 30, maxDays: 180 },
+};
+
+/**
+ * Load an operator's `.agentic-security/retention-policy.yml`. Never
+ * throws — a missing or malformed file degrades to "no overrides," the
+ * same no-op-until-configured convention this repo uses for every other
+ * policy surface. Shape:
+ *   cache: { defaultDays: 3 }
+ *   evidence: { defaultDays: 730 }
+ * A class not mentioned, or a file not present at all, uses
+ * RETENTION_DEFAULTS unmodified.
+ */
+export function loadRetentionPolicy(scanRoot) {
+  if (!scanRoot) return null;
+  let fp;
+  try { fp = statePath(scanRoot, POLICY_FILE); } catch { return null; }
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return null; }
+  try {
+    const doc = yaml.load(raw);
+    if (!doc || typeof doc !== 'object') return null;
+    return doc;
+  } catch { return null; }
+}
+
+/**
+ * The TTL (in days) actually in effect for a class, after applying any
+ * operator override and clamping it to the class's own maxDays — an
+ * override CANNOT raise retention past the ceiling, only lower it (or
+ * leave it at the default). An unrecognised class (should not happen —
+ * only artifact-registry.js's own 5 named classes are ever passed in)
+ * degrades to null, meaning "not subject to a TTL."
+ */
+export function effectiveTtlDays(retentionClass, policy) {
+  const bounds = RETENTION_DEFAULTS[retentionClass];
+  if (!bounds) return null;
+  const override = policy?.[retentionClass]?.defaultDays;
+  if (typeof override === 'number' && Number.isFinite(override) && override >= 0) {
+    return Math.min(override, bounds.maxDays);
+  }
+  return bounds.defaultDays;
+}
+
+/**
+ * Which registered, retention-classed artifacts under `scanRoot`'s state
+ * dir are currently past their effective TTL. Never throws — a missing
+ * state dir or an artifact that does not exist on disk is simply absent
+ * from the result, not an error.
+ *
+ * @returns {Array<{name: string, isDir: boolean, retentionClass: string,
+ *   ageDays: number, ttlDays: number}>}
+ */
+export function findExpiredArtifacts(scanRoot, { now = Date.now() } = {}) {
+  const dir = stateDir(scanRoot);
+  let dirExists = true;
+  try { fs.accessSync(dir); } catch { dirExists = false; }
+  if (!dirExists) return [];
+  const policy = loadRetentionPolicy(scanRoot);
+  // FR-707: an artifact under an active legal hold is NEVER reported as
+  // expired, regardless of TTL — checked here (not just in cmdReset) so
+  // any future caller of this function inherits the same guarantee.
+  const holds = loadLegalHolds(scanRoot);
+  const expired = [];
+  for (const artifact of listArtifactsWithRetentionClass()) {
+    const ttlDays = effectiveTtlDays(artifact.retentionClass, policy);
+    if (ttlDays === null) continue;
+    if (isUnderHold(artifact.name, holds, now)) continue;
+    const p = `${dir}/${artifact.name}`;
+    let st;
+    try { st = fs.statSync(p); } catch { continue; } // not present — nothing to expire
+    const ageDays = (now - st.mtimeMs) / MS_PER_DAY;
+    if (ageDays > ttlDays) {
+      expired.push({ name: artifact.name, isDir: st.isDirectory(), retentionClass: artifact.retentionClass, ageDays, ttlDays });
+    }
+  }
+  return expired;
+}

package/src/posture/risk-dollars.js

@@ -9,7 +9,7 @@
 //   Discount       reachability tier (route-reachable > function-reachable
 //                  > unknown > unreachable)
 //
-// EV per finding = P × Impact × Discount × ConfidenceFloor
+// EV per finding = P × Impact × Discount × ConfidenceWeight
 //
 // Industry breach-cost figures used here are sourced from publicly
 // reported aggregates (Ponemon Cost of a Data Breach Report — IBM/Verizon
@@ -19,6 +19,14 @@
 //
 // Disclaimer: this is an order-of-magnitude estimate for prioritization.
 // It is NOT an actuarial or insurance assessment.
+//
+// FR-803/FR-805 (assurance-hardening PRD): the single `ev` number above is
+// only ever the BASE scenario. Every finding also gets `range` (low/base/
+// high spanning conservative/base/severe), `scenarios` (all three, named),
+// `assumptions` (which table entry and which tier produced each factor),
+// and `modelVersion` — so a reader can trace any dollar figure back to
+// exactly the inputs and methodology version that produced it, and compare
+// scenarios without any of this ever touching `finding.severity`.
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -78,36 +86,126 @@ const REACH_DISCOUNT = {
   'function-reachable-but-not-route':0.4,
 };
 
+// Tiny YAML — parses the two flat "section:\n  key: number" blocks
+// (impactUSD, familyBaseProb) plus four top-level flat scalar keys (FR-802's
+// organization-specific inputs, added below). Deliberately line-based rather
+// than one multi-line regex: a single regex here
+// (`(?:\s+\w+\s*:\s*\d+\s*\n?)+`) looked correct but had a real, silent bug
+// — `\s*` before the optional trailing `\n?` greedily consumed the NEXT
+// line's leading indentation too, so the repeated group's `+` quantifier
+// only ever matched ONE entry before its required leading `\s+` failed to
+// find any whitespace left to consume. A risk-config.yml with more than one
+// impactUSD entry silently kept only the first — found while adding
+// familyBaseProb support (which inherited the identical bug) and testing
+// it with more than one entry, per this session's standing rule of testing
+// multi-entry cases, not just the single-entry case a hand-rolled parser's
+// own author tends to reach for first.
+//
+// FR-802: `organizationScale`, `industry`, `recordCount`, `controlStrength`
+// are free-form top-level scalars (not sections) — an operator states them
+// directly, e.g. `industry: healthcare`. `recordCount` is parsed as an
+// integer; a non-numeric value is treated as not configured (never silently
+// coerced to NaN, which `!= null` would otherwise count as "present").
+const FLAT_SCALAR_KEYS = ['organizationScale', 'industry', 'recordCount', 'controlStrength'];
+
 function _loadConfig(scanRoot) {
   const fp = statePath(scanRoot, 'risk-config.yml');
   if (!fs.existsSync(fp)) return null;
   try {
     const body = fs.readFileSync(fp, 'utf8');
-    // Tiny YAML — look for impactUSD / familyBaseProb overrides
     const cfg = {};
-    const impactMatch = body.match(/^impactUSD\s*:\s*\n((?:\s+\w+\s*:\s*\d+\s*\n?)+)/m);
-    if (impactMatch) {
-      cfg.impactUSD = {};
-      for (const m of impactMatch[1].matchAll(/(\w+)\s*:\s*(\d+)/g)) cfg.impactUSD[m[1]] = parseInt(m[2], 10);
+    let section = null;
+    for (const line of body.split(/\r?\n/)) {
+      const sectionMatch = line.match(/^(impactUSD|familyBaseProb)\s*:\s*$/);
+      if (sectionMatch) { section = sectionMatch[1]; continue; }
+      const flatMatch = !section && line.match(/^([A-Za-z][\w-]*)\s*:\s*(\S.*?)\s*$/);
+      if (flatMatch && FLAT_SCALAR_KEYS.includes(flatMatch[1])) {
+        if (flatMatch[1] === 'recordCount') {
+          const n = parseInt(flatMatch[2], 10);
+          if (Number.isFinite(n)) cfg.recordCount = n;
+        } else {
+          cfg[flatMatch[1]] = flatMatch[2];
+        }
+        continue;
+      }
+      if (!section) continue;
+      const entryMatch = line.match(/^[ \t]+([\w-]+)\s*:\s*([\d.]+)\s*$/);
+      if (entryMatch) {
+        if (!cfg[section]) cfg[section] = {};
+        cfg[section][entryMatch[1]] = section === 'impactUSD' ? parseInt(entryMatch[2], 10) : parseFloat(entryMatch[2]);
+      } else if (line.trim() !== '') {
+        section = null; // a non-indented, non-blank line ends the current section
+      }
     }
     return cfg;
   } catch { return null; }
 }
 
-function _baseProb(family) {
+// FR-801/FR-802: every dollar estimate is a SCENARIO by default — generic,
+// industry-wide probability/impact tables, not this organization's actual
+// exposure. `ORG_SPECIFIC_DIMENSIONS` is the full set of tunable knobs this
+// module recognizes (includes `familyBaseProb`, a bonus calibration input
+// that isn't one of FR-802's five named inputs). The stronger claim FR-802
+// gates — "likely organizational loss" — requires ALL FIVE of its literally
+// named inputs (scale, industry, record count, control strength, impact),
+// tracked separately as `REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS` so that
+// configuring `familyBaseProb` alone (or any subset of the five) can never
+// unlock that label — only 'scenario_partially_configured', same as before.
+const ORG_SPECIFIC_DIMENSIONS = ['impactUSD', 'familyBaseProb', 'organizationScale', 'industry', 'recordCount', 'controlStrength'];
+const REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS = ['impactUSD', 'organizationScale', 'industry', 'recordCount', 'controlStrength'];
+
+function _scenarioDisclosure(cfg) {
+  const configured = ORG_SPECIFIC_DIMENSIONS.filter(d => cfg && cfg[d] != null);
+  const unconfigured = ORG_SPECIFIC_DIMENSIONS.filter(d => !configured.includes(d));
+  const requiredMissing = REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS.filter(d => !(cfg && cfg[d] != null));
+
+  let status, message;
+  if (requiredMissing.length === 0) {
+    status = 'scenario_organization_specific';
+    message = `All organization-specific inputs are configured (${REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS.join(', ')}) — this estimate reflects a likely organizational loss for your organization, not a generic industry scenario.`;
+  } else if (configured.length > 0) {
+    status = 'scenario_partially_configured';
+    message = `Uses organization-configured values for: ${configured.join(', ')}. Still missing for a likely-organizational-loss estimate: ${requiredMissing.join(', ')}. This is NOT a likely-organizational-loss estimate.`;
+  } else {
+    status = 'scenario_default';
+    message = 'Uses generic industry-wide scenario defaults. No organization-specific inputs are configured (see .agentic-security/risk-config.yml) — this is NOT a likely-organizational-loss estimate.';
+  }
+
+  return {
+    status,
+    configuredInputs: configured,
+    unconfiguredInputs: unconfigured,
+    requiredForOrganizationSpecificLoss: REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS,
+    missingRequiredInputs: requiredMissing,
+    message,
+  };
+}
+
+function _baseProb(family, cfg) {
   if (!family) return 0.05;
+  const overrides = cfg && cfg.familyBaseProb;
+  if (overrides) {
+    const hit = overrides[family] ?? overrides[String(family).toLowerCase()];
+    if (typeof hit === 'number') return hit;
+  }
   return FAMILY_BASE_PROB[family] || FAMILY_BASE_PROB[String(family).toLowerCase()] || 0.05;
 }
 
+// FR-803: split out from _impactFor so an assumption can name WHICH tier
+// produced the number, not just the number itself.
+function _impactTierOf(finding) {
+  const dc = Array.isArray(finding.dataClasses) ? finding.dataClasses : [];
+  if (dc.includes('PHI')) return 'PHI';
+  if (dc.includes('PCI')) return 'PCI';
+  if (dc.includes('PII')) return 'PII';
+  if (dc.includes('Confidential')) return 'Confidential';
+  if (finding.threatModel?.crownJewel) return 'crown-jewel';
+  return 'default';
+}
+
 function _impactFor(finding, cfg) {
   const table = cfg && cfg.impactUSD ? { ...IMPACT_USD, ...cfg.impactUSD } : IMPACT_USD;
-  const dc = Array.isArray(finding.dataClasses) ? finding.dataClasses : [];
-  if (dc.includes('PHI')) return table.PHI;
-  if (dc.includes('PCI')) return table.PCI;
-  if (dc.includes('PII')) return table.PII;
-  if (dc.includes('Confidential')) return table.Confidential;
-  if (finding.threatModel?.crownJewel) return table['crown-jewel'];
-  return table.default;
+  return table[_impactTierOf(finding)];
 }
 
 // SCA entries carry reachabilityTier/routeReachable (engine.js's SCA
@@ -124,12 +222,16 @@ function _relevanceTierToReachTier(relevanceTier) {
   }
 }
 
-function _reachDiscount(finding) {
-  const tier = finding.reachabilityTier
+// FR-803: split out from _reachDiscount so an assumption can name the tier.
+function _reachTierOf(finding) {
+  return finding.reachabilityTier
     || (finding.routeReachable && 'route-reachable')
     || _relevanceTierToReachTier(finding.relevanceTier)
     || 'unknown';
-  return REACH_DISCOUNT[tier] || 0.3;
+}
+
+function _reachDiscount(finding) {
+  return REACH_DISCOUNT[_reachTierOf(finding)] || 0.3;
 }
 
 function _epssProb(finding) {
@@ -138,28 +240,111 @@ function _epssProb(finding) {
   return null;
 }
 
+// FR-803: names WHERE the probability number came from, for the assumptions
+// list — not just the value.
+function _probSource(finding, cfg) {
+  if (_epssProb(finding) != null) return 'EPSS score (finding-specific)';
+  const overrides = cfg && cfg.familyBaseProb;
+  if (overrides && (overrides[finding.family] != null || overrides[String(finding.family).toLowerCase()] != null)) {
+    return 'operator-configured familyBaseProb override';
+  }
+  return 'built-in industry base-rate table';
+}
+
+// Bump ONLY when the EV formula or a table's underlying MEANING changes
+// (e.g. re-deriving FAMILY_BASE_PROB from a new source) — never for an
+// additive field on the output shape, which stays backward compatible.
+export const RISK_MODEL_VERSION = '1.0.0';
+
+// FR-805: scenario multipliers apply only to the two GENERIC assumption
+// inputs — probability-of-exploit and impact-per-incident — that FR-801
+// already discloses as industry-wide defaults. Reachability discount and
+// confidence weight are both measured facts about THIS finding in THIS
+// scan, not assumptions with real-world spread, so they stay fixed across
+// scenarios rather than being perturbed for effect.
+const SCENARIO_MULTIPLIERS = {
+  conservative: { prob: 0.5, impact: 0.6 },
+  base: { prob: 1.0, impact: 1.0 },
+  severe: { prob: 1.75, impact: 1.5 },
+};
+
 /**
  * Compute EV per finding. Mutates the finding in place: adds
- * .riskDollars = { ev, prob, impact, discount }.
+ * .riskDollars = { ev, prob, impact, discount, confidenceWeight,
+ *   scenarioStatus, range: {low, base, high}, scenarios: {conservative,
+ *   base, severe}, assumptions: [...], modelVersion, confidence }.
  */
 export function annotateRiskDollars(scanRoot, findings) {
-  if (!Array.isArray(findings) || findings.length === 0) return { total: 0, sumEv: 0 };
+  const disclosure = _scenarioDisclosure(_loadConfig(scanRoot));
+  if (!Array.isArray(findings) || findings.length === 0) return { total: 0, sumEv: 0, scenario: disclosure };
   const cfg = _loadConfig(scanRoot);
   let sumEv = 0;
   let critEv = 0, highEv = 0;
   for (const f of findings) {
     const epss = _epssProb(f);
-    const prob = epss != null ? epss : _baseProb(f.family);
+    const prob = epss != null ? epss : _baseProb(f.family, cfg);
+    const impactTier = _impactTierOf(f);
     const impact = _impactFor(f, cfg);
-    const discount = _reachDiscount(f);
-    const confidenceFloor = Math.max(0.4, f.confidence || 0.8);
-    const ev = Math.round(prob * impact * discount * confidenceFloor);
-    f.riskDollars = { ev, prob: Number(prob.toFixed(3)), impact, discount, confidenceFloor: Number(confidenceFloor.toFixed(2)) };
+    const reachTier = _reachTierOf(f);
+    const discount = REACH_DISCOUNT[reachTier] || 0.3;
+    // FR-804 (assurance-hardening PRD): this used to be
+    // `Math.max(0.4, f.confidence || 0.8)` — TWO stacked bugs. First, `||`
+    // treats a real confidence of 0 (a legitimate, very-low value) as falsy
+    // and silently substitutes 0.8, the HIGH default — a genuinely
+    // near-zero-confidence finding got the same dollar weight as a
+    // near-certain one. Second, the unconditional `Math.max(0.4, ...)`
+    // floor inflated every OTHER low-confidence finding (0.05, 0.1, ...) up
+    // to 0.4 regardless, which is exactly "an artificially high confidence
+    // without an explicit reason" FR-804 names. Fixed: use the finding's
+    // real confidence whenever it is genuinely present (including 0), with
+    // no floor; 0.8 remains the default ONLY when confidence is absent
+    // (not a number at all), which is a "we don't know" default, not an
+    // inflation of a known low value.
+    const confidenceWeight = typeof f.confidence === 'number' ? f.confidence : 0.8;
+
+    // FR-805: three named scenarios, sharing the SAME discount/confidence —
+    // only the two generic inputs (prob, impact) are perturbed. `ev` (base
+    // scenario) is unchanged from before this cycle, since base's
+    // multipliers are 1.0/1.0.
+    const scenarios = {};
+    for (const [name, mult] of Object.entries(SCENARIO_MULTIPLIERS)) {
+      const scenarioProb = Math.min(1, prob * mult.prob);
+      const scenarioImpact = Math.round(impact * mult.impact);
+      scenarios[name] = Math.round(scenarioProb * scenarioImpact * discount * confidenceWeight);
+    }
+    const ev = scenarios.base;
+
+    // FR-803: every dollar value traces to its own assumptions and a model
+    // version — not just a bare number.
+    const assumptions = [
+      `probability of exploit: ${Number(prob.toFixed(3))} (source: ${_probSource(f, cfg)})`,
+      `impact estimate: ${fmtUsd(impact)} (tier: ${impactTier}, ${cfg?.impactUSD?.[impactTier] != null ? 'operator-configured' : 'built-in default'})`,
+      `reachability discount: ${discount} (tier: ${reachTier})`,
+      `confidence weight: ${Number(confidenceWeight.toFixed(2))} (${typeof f.confidence === 'number' ? 'measured from this scan' : 'unknown — defaulted'})`,
+    ];
+    // FR-803: a distinct confidence indicator on the estimate itself — not
+    // the per-finding confidenceWeight multiplier, but a coarse tier
+    // reflecting how much of this number is organization-specific vs.
+    // generic-default, folded with the finding's own detection confidence.
+    const confidence = disclosure.status === 'scenario_organization_specific' && confidenceWeight >= 0.7
+      ? 'high'
+      : (disclosure.status === 'scenario_default' || confidenceWeight < 0.4 ? 'low' : 'medium');
+
+    f.riskDollars = {
+      ev, prob: Number(prob.toFixed(3)), impact, discount,
+      confidenceWeight: Number(confidenceWeight.toFixed(2)),
+      scenarioStatus: disclosure.status,
+      range: { low: scenarios.conservative, base: scenarios.base, high: scenarios.severe },
+      scenarios,
+      assumptions,
+      modelVersion: RISK_MODEL_VERSION,
+      confidence,
+    };
     sumEv += ev;
     if (f.severity === 'critical') critEv += ev;
     else if (f.severity === 'high') highEv += ev;
   }
-  return { total: findings.length, sumEv, critEv, highEv };
+  return { total: findings.length, sumEv, critEv, highEv, scenario: disclosure };
 }
 
 /**
@@ -172,4 +357,9 @@ export function fmtUsd(n) {
   return `$${n}`;
 }
 
-export const _internals = { FAMILY_BASE_PROB, IMPACT_USD, REACH_DISCOUNT, _baseProb, _impactFor, _reachDiscount };
+export const _internals = {
+  FAMILY_BASE_PROB, IMPACT_USD, REACH_DISCOUNT, ORG_SPECIFIC_DIMENSIONS,
+  REQUIRED_FOR_ORGANIZATION_SPECIFIC_LOSS, SCENARIO_MULTIPLIERS,
+  _baseProb, _impactFor, _impactTierOf, _reachDiscount, _reachTierOf,
+  _probSource, _loadConfig, _scenarioDisclosure,
+};

package/src/posture/sbom-diff.js

@@ -24,7 +24,8 @@ import * as fs from 'node:fs';
 import { statePath, stateWritesEnabled } from './state-dir.js';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 const HISTORY_DIR = 'sbom-history';
 
@@ -32,9 +33,21 @@ function _historyDir(scanRoot) {
   return statePath(scanRoot, HISTORY_DIR);
 }
 
+// `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 sweep (found missing here by a follow-up review that
+// grepped for `child_process` usage beyond just `execFileSync('git'` call
+// sites). `rev-parse HEAD` was VERIFIED not to itself trigger
+// `core.fsmonitor`/a hook (it touches neither the working tree nor the
+// index), so this is not a second live RCE — but leaving
+// `GIT_CONFIG_NOSYSTEM`/`GIT_TERMINAL_PROMPT`/`core.hooksPath` unset here
+// still violated this module's own "every git call routes through
+// hardenGitArgs/hardenGitEnv" contract, and `execSync` (a shell string) is
+// gratuitous risk this call never needed — `rev-parse HEAD` has no
+// caller-controlled input to interpolate at all.
 function _gitHead(scanRoot) {
   try {
-    return execSync('git rev-parse HEAD', { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return execFileSync('git', hardenGitArgs(['rev-parse', 'HEAD']), { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() }).trim();
   } catch { return null; }
 }