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

package/src/posture/adversary-agent.js

@@ -25,6 +25,7 @@
 // `unverified-no-llm-endpoint` and the transcript records only the seed input.
 
 import * as crypto from 'node:crypto';
+import { evaluateEgress } from '../egress/policy.js';
 
 const MAX_CALLS_DEFAULT = 50;
 const MAX_WALL_MS_DEFAULT = 15 * 60 * 1000;
@@ -170,12 +171,23 @@ export async function runAgent(finding, opts = {}) {
   const transcript = startTranscript(finding, opts.target);
   const budget = { maxCalls: opts.maxCalls, maxWallMs: opts.maxWallMs };
 
-  const llmInvoke = opts.llmInvoke || (process.env.AGENTIC_SECURITY_LLM_ENDPOINT ? defaultLlmInvoke : null);
+  // FR-601: evaluated before defaultLlmInvoke is even selected, so a denial
+  // means its transcript-to-prompt construction (inside defaultLlmInvoke,
+  // called later in the loop below) never runs at all.
+  let egressDecision = null;
+  let llmInvoke = opts.llmInvoke || null;
+  if (!llmInvoke && process.env.AGENTIC_SECURITY_LLM_ENDPOINT) {
+    egressDecision = evaluateEgress({ scanRoot: opts.scanRoot, purpose: 'adversary-agent', endpoint: process.env.AGENTIC_SECURITY_LLM_ENDPOINT });
+    if (egressDecision.allowed) llmInvoke = defaultLlmInvoke;
+  }
   const executeTool = opts.executeTool || (transcript.target ? (call) => defaultExecuteTool(call, transcript) : null);
 
   if (typeof llmInvoke !== 'function' || typeof executeTool !== 'function') {
-    appendEntry(transcript, { phase: 'init', reason: 'no llmInvoke/executeTool supplied and AGENTIC_SECURITY_LLM_ENDPOINT not set' });
-    return { transcript, outcome: 'unverified-no-llm-endpoint' };
+    const reason = (egressDecision && !egressDecision.allowed)
+      ? `egress policy denied this call: ${egressDecision.reason}`
+      : 'no llmInvoke/executeTool supplied and AGENTIC_SECURITY_LLM_ENDPOINT not set';
+    appendEntry(transcript, { phase: 'init', reason, egressDecision: egressDecision || undefined });
+    return { transcript, outcome: 'unverified-no-llm-endpoint', egressDecision };
   }
 
   let outcome = null;

package/src/posture/artifact-registry.js

@@ -0,0 +1,241 @@
+// State artifact registry (assurance-hardening PRD, Milestone 0/1, FR-701/FR-703).
+//
+// `bin/agentic-security.js`'s `cmdReset` used to delete from two hardcoded
+// Sets (WIPE / WIPE_DIRS) — an enumeration that had drifted badly behind the
+// state artifacts this codebase actually writes under `.agentic-security/`.
+// This module is the registry FR-701 asks for: every known artifact, with an
+// explicit classification, built by auditing every `statePath(...)` call
+// site in `src/` and `bin/` (not guessed from filenames — several looked
+// like generated output by name but turned out, on reading their actual
+// read/write call sites, to be operator- or agent-authored INPUT).
+//
+// Two classifications:
+//   - 'generated': written by the scanner itself, safe to delete — the next
+//     scan/command regenerates it. `cmdReset` removes these by default.
+//   - 'operator-config': hand-authored (or agent-authored, for
+//     logic-claims.json) input the scanner only reads. Deleting it on reset
+//     would be data loss, not cleanup — `cmdReset` always preserves these.
+//
+// Corrections this audit made to the assurance-hardening PRD's own evidence
+// table (A-10), which had assumed these were straightforwardly "missing from
+// the wipe list, therefore should be added": `logic-claims.json` is read-only
+// from engine.js (an external reviewing agent authors it); `current-intent.md`
+// has no writer anywhere in src/ or bin/ (developer-authored);
+// `exploit-history.jsonl`'s own header comment calls it an "operator-curated
+// record"; `cve-alerts.json`'s own header comment calls it "Configuration...
+// read from"; `network-policy.json` is documented as an Inputs-section
+// artifact in network-policy-import.js. All five are classified
+// 'operator-config' here — the registry closes the reset-completeness gap
+// without introducing a NEW data-loss bug in the process.
+//
+// This module implements FR-701 (this registry) and FR-703 (registry-driven
+// reset). FR-702 (TTL by artifact class) is implemented here too, as an
+// additive `retentionClass` field: 'cache' | 'scan' | 'evidence' | 'ticket'
+// | 'backup' | undefined, matching the acceptance criterion's own named
+// list verbatim ("expired caches, scans, evidence, tickets, and backups").
+// DELIBERATELY CONSERVATIVE: only entries that unambiguously fit one of
+// those five categories carry a class. Ongoing accumulated state whose
+// deletion would be a real loss rather than cleanup — calibration data
+// (validator-metrics.json, triage-feedback.json), the continual-learning
+// memory file (AGENTS.md), daemon dedup state (cve-alerts-state.json), the
+// gamification streak counter, an operator-set regression baseline
+// (baseline.json, set via --set-baseline — functionally closer to
+// operator intent than scanner output even though it is written by the
+// scanner) — are left with NO retention class rather than forced into the
+// nearest-sounding bucket. A class-less 'generated' artifact is completely
+// unaffected by FR-702's enforcement; it is still deleted unconditionally
+// by an ordinary `reset` (FR-703's own behavior, unchanged).
+//
+// See retention-policy.js for the default/max TTL values per class, the
+// optional operator-override file, and the actual expiry check — kept in
+// a separate module rather than grown into this one, the same "registry
+// vs. policy" separation this session's egress/policy.js and
+// compliance-policy.js already establish.
+//
+// FR-706 (export/deletion manifests) is implemented in
+// posture/state-lifecycle-report.js, consuming this registry directly (an
+// export walks the FULL registry, not just the 'generated' half `reset`
+// acts on — see that module's header).
+//
+// FR-705 (encryption of confidential state classes): an additive
+// `confidential: true` field, enforced by posture/encryption-provider.js.
+// DELIBERATELY CONSERVATIVE, Phase 1 of a staged rollout (see that
+// module's own header for the full rationale): only `compliance-
+// evidence.json`/`.md` are marked in this pass — both have exactly one,
+// well-isolated writer function (compliance-policy.js's emitEvidenceJsonLd/
+// emitEvidenceMarkdown) and zero other production readers besides that
+// same module and the verify-attestation CLI path, both already updated to
+// transparently decrypt. Candidates explicitly DEFERRED, with reasons:
+// `mcp-audit.log`/`egress-audit.log` (hash-CHAINED NDJSON — each entry's
+// hash covers the previous entry, so per-write whole-file encryption would
+// need the chain to be computed over plaintext before encrypting, a real
+// design question left for its own pass), `dpia.md`/`ropa.md`/`data-
+// inventory.json` (written via engine.js's own internal helper, a larger
+// blast radius to verify safely), `last-scan.json`/`findings.json` (read
+// directly as plain JSON by dozens of commands — encrypting these needs a
+// decrypt-on-read hook at every one of those call sites, a much larger,
+// separate migration in the same spirit as E2's own deferred scope).
+
+export const ARTIFACT_REGISTRY = [
+  // ── Generated: scan output, caches, and system-maintained ledgers ──────
+  { name: 'validator-metrics.json', kind: 'file', classification: 'generated' },
+  { name: 'triage-feedback.json', kind: 'file', classification: 'generated' },
+  { name: 'scan-history.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'last-scan.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'last-scan.json.sig', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'shadow-findings.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'mcp-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence' },
+  { name: 'egress-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence', note: "FR-604 per-call egress audit log — hash-chained NDJSON written by egress/audit.js's recordEgressCall, never read as config" },
+  { name: 'hook-throttle.json', kind: 'file', classification: 'generated', retentionClass: 'cache' },
+  { name: 'tickets.json', kind: 'file', classification: 'generated', retentionClass: 'ticket' },
+  { name: 'streak.json', kind: 'file', classification: 'generated' },
+  { name: 'findings.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'findings.sarif', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'findings.csv', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'llm-cache', kind: 'dir', classification: 'generated', retentionClass: 'cache' },
+  { name: 'fix-history', kind: 'dir', classification: 'generated', retentionClass: 'backup' },
+  { name: 'fix-plans', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
+  // The following were confirmed missing from the old hardcoded WIPE/
+  // WIPE_DIRS sets (A-10) and confirmed GENERATED by reading their write
+  // call sites (engine.js, or the module named in `source`).
+  { name: 'dpia.md', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'engine.js (_safeWriteState)' },
+  { name: 'ropa.md', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'engine.js (_safeWriteState) — FR-407 RoPA scaffold, dataflow/privacy-governance.js' },
+  { name: 'data-inventory.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'engine.js (_safeWriteState) — FR-406 code-derived data inventory, dataflow/privacy-inventory.js' },
+  { name: 'data-flow-graph.md', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'engine.js (_safeWriteState) — FR-406 mermaid flow graph, dataflow/privacy-inventory.js' },
+  { name: 'privacy-framework.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/privacy-framework.js' },
+  { name: 'privacy-framework.md', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/privacy-framework.js' },
+  { name: 'ifds-summaries.json', kind: 'file', classification: 'generated', retentionClass: 'cache', source: 'dataflow/ifds-precise.js (cache)' },
+  { name: 'exploit-bundles.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'engine.js (_safeWriteState)' },
+  { name: 'cve-alerts-state.json', kind: 'file', classification: 'generated', source: 'posture/cve-alert-daemon.js' },
+  { name: 'compliance-evidence.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'posture/compliance-policy.js' },
+  { name: 'compliance-evidence.md', kind: 'file', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'posture/compliance-policy.js' },
+  { name: 'ATTRIBUTIONS.md', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'posture/license-attributions.js' },
+  { name: 'NOTICE', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'posture/license-attributions.js' },
+  { name: 'accepted.json', kind: 'file', classification: 'generated', source: 'posture/suppressions.js (soft-accept save path)', note: 'already self-managing per-entry expiry (FR-1004-adjacent) — no additional class-level TTL' },
+  { name: 'triage.json', kind: 'file', classification: 'generated', source: 'posture/triage.js (_save)' },
+  { name: 'pqc-migration-plan.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'posture/pqc-migration-plan.js' },
+  { name: 'pqc-migration-plan.md', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'posture/pqc-migration-plan.js' },
+  // controls.json lives under compliance/<framework>/ — registering the
+  // parent directory covers it and any other per-framework artifact.
+  { name: 'compliance', kind: 'dir', classification: 'generated', retentionClass: 'evidence', source: 'posture/auditor-walkthrough.js' },
+  { name: 'attestations', kind: 'dir', classification: 'generated', retentionClass: 'evidence', source: 'posture/evidence-bundle.js' },
+  { name: 'auditor-walkthroughs', kind: 'dir', classification: 'generated', retentionClass: 'evidence' },
+  { name: 'incremental', kind: 'dir', classification: 'generated', retentionClass: 'cache', source: 'dataflow/incremental.js (cache)' },
+  { name: 'model-rescan', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
+  { name: 'sca-upgrade-history', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
+  { name: 'scan-baselines', kind: 'dir', classification: 'generated', retentionClass: 'scan', source: 'posture/pr-augment.js' },
+  { name: 'agent-scratchpad', kind: 'dir', classification: 'generated', retentionClass: 'cache', source: 'mcp/tools.js (append_scratchpad)' },
+  // Finding Provenance (M0/M1, split per PRD Section 8 retention task). Used
+  // to be one directory with two writers sharing it, which meant they could
+  // not get different retention treatment — `cmdReset`/`findExpiredArtifacts`
+  // only ever operate on exact TOP-LEVEL `.agentic-security/` directory
+  // names, never on a `/`-qualified sub-path. Now physically split:
+  //   - posture/provenance/cache.js writes provenance-cache/<hash>.json — a
+  //     pure HEAD-keyed memo of resolved origins, safely regenerable, no
+  //     correctness dependency on being preserved. Gets retentionClass:
+  //     'cache' (7-day default / 30-day max TTL, RETENTION_DEFAULTS.cache).
+  //   - posture/provenance/lifecycle.js writes provenance/lifecycle.json +
+  //     .lock — the introduce/remediate/reintroduce ledger. Deliberately NO
+  //     retentionClass: this is permanent history, not a cache; auto-expiring
+  //     it would silently lose lifecycle events a report may already have
+  //     cited. `reset` (without `--expired`) still clears it, which is
+  //     explicit operator action, unlike TTL-driven auto-expiry.
+  // Old-location cache files (`provenance/cache/*.json`, written before this
+  // split) are DELIBERATELY NOT migrated — see cache.js's own comment and the
+  // commit that introduced this split. They are simply orphaned: invisible to
+  // this registry, un-swept by reset/retention, silently ignored by the new
+  // code, and harmless to leave until a human deletes them by hand.
+  { name: 'provenance-cache', kind: 'dir', classification: 'generated', retentionClass: 'cache', source: 'posture/provenance/cache.js -- pure HEAD-keyed memo, safely regenerable, no correctness dependency on being preserved' },
+  { name: 'provenance', kind: 'dir', classification: 'generated', source: 'posture/provenance/lifecycle.js -- the introduce/remediate/reintroduce ledger. Deliberately NO retentionClass: this is permanent history, not a cache; auto-expiring it would silently lose lifecycle events a report may already have cited.' },
+  { name: 'AGENTS.md', kind: 'file', classification: 'generated', source: 'posture/agents-memory.js' },
+  { name: 'AGENTS.md.archive', kind: 'file', classification: 'generated', source: 'posture/agents-memory.js' },
+  { name: 'baseline.json', kind: 'file', classification: 'generated', source: 'bin/agentic-security.js (--set-baseline)', note: 'operator-set intent, functionally closer to operator-config than scan output — no auto-expiry' },
+  // These two were found by the completeness guard (test/artifact-registry-
+  // completeness.test.js) to have a read call site (leaderboard.js,
+  // posture/findings-memory.js respectively) but NO writer anywhere in src/
+  // or bin/ — likely dead/aspirational read paths from a scan-history
+  // storage scheme that was refactored away. Registered as 'generated'
+  // rather than left unclassified: nothing about a per-scan history log/
+  // directory suggests hand-authored config, so if a future change starts
+  // writing either, the safe default (delete on reset, like scan-history.json)
+  // is already in place rather than accidentally falling to operator-config.
+  { name: 'scan-history.jsonl', kind: 'file', classification: 'generated', retentionClass: 'scan', note: 'no current writer found — see completeness-guard test comment' },
+  { name: 'scan-history', kind: 'dir', classification: 'generated', retentionClass: 'scan', note: 'no current writer found — see completeness-guard test comment' },
+
+  // FR-706: the last-action proof artifacts `reset` and `export` write —
+  // see posture/state-lifecycle-report.js's header for why each is a single
+  // overwritten "last action" file rather than an ever-growing log.
+  { name: 'deletion-report.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/state-lifecycle-report.js (via bin/agentic-security.js cmdReset)' },
+  { name: 'export-report.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/state-lifecycle-report.js (via bin/agentic-security.js cmdExport)' },
+
+  // ── Operator-config: hand-authored (or agent-authored) input, never wiped ──
+  { name: 'rules.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'rules', kind: 'dir', classification: 'operator-config' },
+  { name: 'rules-proposed', kind: 'dir', classification: 'operator-config', note: 'proposed rules awaiting human review — not yet approved config, but not scanner-regenerable either' },
+  { name: 'license-policy.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'trusted-keys.json', kind: 'file', classification: 'operator-config' },
+  { name: 'ruleset-version.json', kind: 'file', classification: 'operator-config', note: 'pinning intent, hand-set' },
+  { name: 'risk-config.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'egress-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-601 egress policy (mode: allow/deny/local-only, allowedProviders/deniedProviders) — read by egress/policy.js, never written by the scanner' },
+  { name: 'integrations.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'profile.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'sca-policy.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'suppressions.yml', kind: 'file', classification: 'operator-config', note: 'audit-tier suppression config; only ever loaded, never saved, by posture/suppressions.js' },
+  { name: 'network-policy.json', kind: 'file', classification: 'operator-config', note: 'documented as an Inputs-section artifact in posture/network-policy-import.js, not a scanner-written digest' },
+  { name: 'privacy-taxonomy.json', kind: 'file', classification: 'operator-config', note: 'FR-402 privacy data-classification taxonomy overrides/additions — read by dataflow/privacy-taxonomy.js, never written by the scanner' },
+  { name: 'privacy-policy.json', kind: 'file', classification: 'operator-config', note: 'FR-404 privacy sink policy (which class-to-sink flows are explicitly permitted) — read by dataflow/privacy-sink-policy.js, never written by the scanner' },
+  { name: 'privacy-governance.json', kind: 'file', classification: 'operator-config', note: 'FR-407 DPIA/RoPA governance field overrides (purpose, lawful basis, retention, etc.) — read by dataflow/privacy-governance.js, never written by the scanner' },
+  { name: 'compliance-severity-policy.json', kind: 'file', classification: 'operator-config', note: 'FR-502 per-framework/default open-finding severity threshold override — read by posture/auditor-walkthrough.js, never written by the scanner' },
+  { name: 'authorized-approvers.json', kind: 'file', classification: 'operator-config', note: 'FR-1002 identity/role registry for high-impact fix approvals — read by fix/approver-registry.js, never written by the scanner' },
+  { name: 'policy-bundles', kind: 'dir', classification: 'operator-config', note: 'FR-1001 signed organization/repository/environment policy bundles (organization.json/repository.json/environment.json) — distributed by an org and placed by the operator, read by posture/policy-bundle.js, never written by the scanner' },
+  { name: 'policy-bundle-public-key.pem', kind: 'file', classification: 'operator-config', note: 'FR-1001 public key an operator installs to verify org-distributed policy bundles — read by posture/policy-bundle.js, never written by the scanner' },
+  { name: 'retention-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-702 per-retention-class TTL overrides (clamped to a built-in per-class maximum) — read by posture/retention-policy.js, never written by the scanner' },
+  { name: 'legal-holds.json', kind: 'file', classification: 'operator-config', note: 'FR-707 legal holds ({artifact, owner, reason, expires_at}) — read by posture/retention-policy.js and bin/agentic-security.js cmdReset; WRITTEN by the CLI (legal-hold add/remove), but classified operator-config (not generated) deliberately: a plain `reset` must never be able to delete the very record protecting other artifacts from deletion' },
+  { name: 'calibration-feedback.jsonl', kind: 'file', classification: 'operator-config', note: 'FR-806 opt-in calibration ground truth ({at, findingId, outcome: accept-risk|realized-incident, predicted*, note}) — WRITTEN by the CLI (calibration-feedback record), but classified operator-config like exploit-history.jsonl: real, hard-to-recreate customer-reported ground truth, never scanner-regenerable, so a routine reset must never delete it' },
+  { name: 'encryption-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-705 encryption provider/required opt-in policy ({provider: local-key, required: true|false}) — read by posture/encryption-provider.js, never written by the scanner' },
+  { name: 'provenance-providers.yml', kind: 'file', classification: 'operator-config', note: 'Finding Provenance M3 §3.4 GitHub/GitLab provider enrichment opt-in ({token} or provider-scoped tokens) — read by posture/provenance/providers/config.js, never written by the scanner; env vars (AGENTIC_SECURITY_GITHUB_TOKEN/AGENTIC_SECURITY_GITLAB_TOKEN) take precedence when set' },
+  { name: 'repo-lineage.json', kind: 'file', classification: 'operator-config', note: 'Finding Provenance M4 §4.2 cross-repository lineage declaration ({linkedFrom: {path, atCommit}}) — read by posture/provenance/repo-lineage.js, never written by the scanner; the linked path is verified as a real local git repo before use, no remote fetch' },
+  { name: 'logic-claims.json', kind: 'file', classification: 'operator-config', note: 'authored by an external reviewing agent; engine.js only ever reads it (fs.readFileSync, never written)' },
+  { name: 'current-intent.md', kind: 'file', classification: 'operator-config', note: 'developer-authored; no writer exists anywhere in src/ or bin/' },
+  { name: 'exploit-history.jsonl', kind: 'file', classification: 'operator-config', note: 'own header comment: "operator-curated record of past confirmed exploits"' },
+  { name: 'cve-alerts.json', kind: 'file', classification: 'operator-config', note: 'own header comment: "Configuration is read from"; state lives in the separate cve-alerts-state.json, which IS generated' },
+];
+
+export function listGeneratedArtifacts() {
+  return ARTIFACT_REGISTRY.filter(a => a.classification === 'generated');
+}
+
+export function listOperatorConfigArtifacts() {
+  return ARTIFACT_REGISTRY.filter(a => a.classification === 'operator-config');
+}
+
+export function isRegisteredArtifact(name) {
+  return ARTIFACT_REGISTRY.some(a => a.name === name);
+}
+
+export function classificationOf(name) {
+  return ARTIFACT_REGISTRY.find(a => a.name === name)?.classification ?? null;
+}
+
+// FR-705: is this artifact marked as containing sensitive content an
+// operator may want encrypted at rest? Deliberately a SEPARATE flag from
+// classification/retentionClass — confidentiality is about content
+// sensitivity, not about who writes it or how long it lives. See
+// encryption-provider.js for the enforcement side (the fail-closed gate
+// this flag feeds) and its own header for which artifacts are marked here
+// in this first, deliberately conservative pass, and why others are not.
+export function confidentialOf(name) {
+  return ARTIFACT_REGISTRY.find(a => a.name === name)?.confidential === true;
+}
+
+// FR-702: which retention class (if any) governs this artifact's TTL. Only
+// 'generated' artifacts can carry one — an 'operator-config' entry is never
+// auto-expired regardless of what this returns (retention-policy.js's own
+// caller enforces that ordering, not this function).
+export function retentionClassOf(name) {
+  return ARTIFACT_REGISTRY.find(a => a.name === name)?.retentionClass ?? null;
+}
+
+export function listArtifactsWithRetentionClass() {
+  return ARTIFACT_REGISTRY.filter(a => a.classification === 'generated' && a.retentionClass);
+}

package/src/posture/auditor-walkthrough.js

@@ -27,19 +27,95 @@
 // User supplies their own control mapping in the same shape as the
 // bundled ones. The auditor-walkthrough renders evidence against it.
 //
-// Disclaimer: this module organizes scanner evidence into a narrative.
-// It does not certify compliance. A licensed assessor (CPA / auditor /
-// DPO) is responsible for the final attestation.
+// Disclaimer: this module organizes scanner evidence into a narrative. It
+// does not certify compliance. See evidence-grade-wording.js for why the
+// emitted disclaimer names all three assurance tiers explicitly (this
+// module's own is one of the ones that used to get the terminology
+// backwards — "a licensed assessor is responsible for the final
+// attestation" describes independent certification, not attestation).
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { statePath, stateWritesEnabled } from './state-dir.js';
+import { EVIDENCE_GRADE_DISCLAIMER_SHORT } from './evidence-grade-wording.js';
 import { COMPLIANCE_FAMILY_ALIAS, resolveFamilyKeys } from './family-resolve.js';
 import { strengthOfControl as _strengthOfControl } from './coverage-strength.js';
+// FR-PROV-026: earliestOrigin.authorName below is untrusted git commit
+// metadata. renderWalkthrough()'s output is console.log'd verbatim by
+// bin/agentic-security.js's `compliance --walkthrough` — the ONLY live
+// consumer today (persistWalkthrough below is exported and tested but has
+// zero callers anywhere in the CLI/command surface; no code in this repo
+// ever runs this text through a real Markdown renderer). sanitizeForTerminal
+// is therefore the correct sanitizer here, not a Markdown-escaping one — a
+// backslash-escaping sibling was tried and reverted (see schema.js's header
+// comment): printed raw or read as plain text, `Jean-Luc Picard` rendering
+// as `Jean\-Luc Picard` and `dependabot[bot]` as `dependabot\[bot\]` is a
+// visible regression on common real-world author names, not a fix.
+import { sanitizeForTerminal, pseudonymizeAuthor, PROVENANCE_COMPLIANCE_DISCLAIMER } from './provenance/schema.js';
+
+// Fix-round item 4b: this renderer had `sanitizeForTerminal` (injection
+// safety) but never honoured `--pseudonymize-authors` at all — an operator
+// who set that policy still saw a raw committer name in walkthrough output,
+// the one boundary that gap missed. Reads the SAME env var
+// `report/index.js`'s `_normalizedProvenance` and `mcp/tools.js`'s
+// `providerEnrichment`-aware call read back
+// (AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS=1 / --pseudonymize-authors). Keyed
+// on name only, not email: `deriveComplianceProvenance`'s `earliestOrigin`
+// deliberately never carries `authorEmail` (see its own comment — that
+// object bypasses the `redactFindingProvenance` sweep entirely), so the
+// pseudonym here is stable across repeated runs for the same author name but
+// not necessarily identical to the email-keyed pseudonym shown at other
+// output boundaries for the same person.
+function _maybePseudonymizeName(name) {
+  if (!name) return name;
+  return process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS === '1' ? pseudonymizeAuthor(name, null) : name;
+}
 
 // Re-exported so existing callers/tests keep importing these from here.
 export { COMPLIANCE_FAMILY_ALIAS, resolveFamilyKeys };
+
+// FR-PROV-016 (M2): "earliest proven open condition" among a control's
+// contributing findings. Prefers a finding whose findingProvenance resolved
+// findingOrigin.status:'complete' (the OLDEST such authorDate wins); falls
+// back to 'partial' entries with a resolved findingOrigin.authorDate when no
+// complete one exists. Never fabricates an origin — zero usable entries is
+// reported as null/'unknown', not the repo's first commit or "now".
+export function deriveComplianceProvenance(findings) {
+  const list = Array.isArray(findings) ? findings.filter(Boolean) : [];
+  const withOrigin = list
+    .map((f) => ({ f, fp: f && f.findingProvenance }))
+    .filter((x) => x.fp && x.fp.findingOrigin && x.fp.findingOrigin.authorDate);
+  const complete = withOrigin.filter((x) => x.fp.status === 'complete');
+  const partial = withOrigin.filter((x) => x.fp.status === 'partial');
+  // authorDate is git's `%aI` (strict ISO-8601, author's LOCAL UTC offset —
+  // see git-evidence.js's commitMeta), never normalized to Z. Two commits
+  // authored in different timezones near a day boundary can lexically sort
+  // in the wrong chronological order, so compare actual instants via
+  // Date.parse, never the raw strings.
+  const pickEarliest = (arr) => arr.reduce(
+    (min, x) => (!min || Date.parse(x.fp.findingOrigin.authorDate) < Date.parse(min.fp.findingOrigin.authorDate)) ? x : min,
+    null,
+  );
+  const best = complete.length ? pickEarliest(complete) : (partial.length ? pickEarliest(partial) : null);
+  return {
+    derivedFrom: [...new Set(list.map((f) => f && f.id).filter(Boolean))],
+    // Only commit/authorDate/authorName are ever read from findingOrigin
+    // here — this object is a SIBLING field to findingProvenance (not
+    // nested inside it), so it bypasses the redactFindingProvenance sweep
+    // that runs at report/mcp output boundaries. authorEmail must never be
+    // added to this shape without first routing it through
+    // redactFindingProvenance.
+    earliestOrigin: best ? {
+      commit: best.fp.findingOrigin.commit || null,
+      authorDate: best.fp.findingOrigin.authorDate,
+      authorName: best.fp.findingOrigin.authorName || null,
+    } : null,
+    confidence: complete.length ? 'high' : (partial.length ? 'low' : 'unknown'),
+    limitations: best ? [] : ['no contributing finding resolved a verified origin'],
+  };
+}
+
 const BUNDLED_DIR = path.join(path.dirname(new URL(import.meta.url).pathname), 'compliance-frameworks');
 function _readJson(fp) {
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
@@ -187,7 +263,64 @@ export const COMPLIANCE_FAMILY_GAPS = {
   // works, which is the mirror image of the bug this prevents.
 };
 
+// FR-501/FR-502 (assurance-hardening PRD, A-07): a `family:` mapping used to
+// only count 'critical'/'high' findings as "open" — a control with 50 open
+// MEDIUM findings on its mapped family rendered as
+// "✓ no open critical/high findings", identical to a genuinely clean
+// control. posture/privacy-framework.js already solved the analogous problem
+// for its own four-bucket model (its header calls this out directly: a
+// vacuous pass is "the same false assurance... arriving by a different
+// route"); this raises the floor here to match rather than leaving two
+// different standards for what counts as "open" across compliance surfaces.
+// A named, ordered rank (not a hardcoded pair of string literals) so a
+// future per-framework/per-policy threshold (FR-502's fuller scope) is a
+// one-line change here rather than another hunt through the evaluator.
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+const OPEN_FINDING_MIN_SEVERITY = 'medium';
+
+// FR-502's fuller scope, delivered: "policy-specific rather than globally
+// high/critical." An operator can lower (or raise) the open-finding floor
+// per framework via .agentic-security/compliance-severity-policy.json:
+//   { "default": "medium", "byFramework": { "gdpr": "low" } }
+// `default` overrides OPEN_FINDING_MIN_SEVERITY for every framework that
+// has no more specific `byFramework` entry; a framework entry wins over
+// `default`. Never inferred — an operator decision, same as
+// dataflow/privacy-taxonomy.js's (FR-402) taxonomy customization and
+// egress/policy.js's (FR-602) config-file precedent. A missing file, a
+// malformed one, or a value that is not one of SEVERITY_RANK's five known
+// keys all degrade to the built-in 'medium' floor — falling back to a rank
+// of `undefined` would make the `>=` comparison always false, silently
+// treating EVERY finding as "not open" (the exact vacuous-pass bug this
+// threshold exists to prevent), so an invalid override must never reach
+// the comparison at all.
+const SEVERITY_POLICY_FILE = 'compliance-severity-policy.json';
+
+function _resolveOpenFindingMinSeverity(scanRoot, frameworkId) {
+  if (!scanRoot) return OPEN_FINDING_MIN_SEVERITY;
+  let raw;
+  try {
+    raw = fs.readFileSync(statePath(scanRoot, SEVERITY_POLICY_FILE), 'utf8');
+  } catch {
+    return OPEN_FINDING_MIN_SEVERITY; // ENOENT (the common case) or any other read failure
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    return OPEN_FINDING_MIN_SEVERITY; // malformed config — never throws, never blocks evaluation
+  }
+  if (!doc || typeof doc !== 'object') return OPEN_FINDING_MIN_SEVERITY;
+  const byFramework = (doc.byFramework && typeof doc.byFramework === 'object') ? doc.byFramework : {};
+  const candidate = (frameworkId && typeof byFramework[frameworkId] === 'string')
+    ? byFramework[frameworkId]
+    : (typeof doc.default === 'string' ? doc.default : null);
+  return (candidate && Object.prototype.hasOwnProperty.call(SEVERITY_RANK, candidate))
+    ? candidate
+    : OPEN_FINDING_MIN_SEVERITY;
+}
+
 export function evaluateFramework(scanRoot, fw, scan) {
+  const minSeverity = _resolveOpenFindingMinSeverity(scanRoot, fw && fw.id);
   // CMP-2: last-scan.json (what this is actually handed in production) carries
   // findings across four separate channels — SAST (`findings`), secrets,
   // business-logic, and SCA (`supplyChain`) — because report/index.js's
@@ -214,24 +347,30 @@ export function evaluateFramework(scanRoot, fw, scan) {
   const results = [];
   for (const c of fw.controls || []) {
     const obs = [];
+    // FR-PROV-016: findings that contributed an OPEN condition to this
+    // control's `family:` mapping(s) — the exact objects `open` below
+    // filters to, not just their ids, so deriveComplianceProvenance can read
+    // .findingProvenance off them. Naturally empty for a control that ends
+    // up 'present' (present requires zero open findings across every
+    // mapping) or 'manual' (no family: mapping ever populates it) — so a
+    // consumer can treat a non-empty controlRefs as "this control has an
+    // attributable gap" without re-deriving the bucket classification.
+    const contributingFindings = [];
     let status = 'manual';
     const maps = Array.isArray(c.mapsTo) ? c.mapsTo : [];
 
     if (maps.length === 0) {
       obs.push('No automated mapping — requires manual evidence collection.');
-      // PRD F10.2: carry the MEASURED strength of the backing detector, so a
-    // control mapped to a detector that finds 3 of 18 independent advisories
-    // cannot read the same as one backed by a detector that finds nearly
-    // everything. Import is lazy so the evaluator keeps working if the bench
-    // artifacts are absent (they degrade to `unmeasured`, never to a default).
-    let evidence = null;
-    try { evidence = _strengthOfControl(c); } catch { /* strength is additive; never block evaluation */ }
-    results.push({
-      control: c,
-      status,
-      observations: obs,
-      ...(evidence ? { evidence, partiallyEvidenced: evidence.tier === 'weak' || evidence.tier === 'unmeasured' } : {}),
-    });
+      let evidence = null;
+      try { evidence = _strengthOfControl(c); } catch { /* strength is additive; never block evaluation */ }
+      results.push({
+        control: c,
+        status,
+        observations: obs,
+        controlRefs: [],
+        derivedProvenance: deriveComplianceProvenance([]),
+        ...(evidence ? { evidence, partiallyEvidenced: evidence.tier === 'weak' || evidence.tier === 'unmeasured' } : {}),
+      });
       continue;
     }
 
@@ -291,12 +430,14 @@ export function evaluateFramework(scanRoot, fw, scan) {
         const candidates = resolveFamilyKeys(fam, families.keys())
           .flatMap(k => families.get(k) || []);
         const scoped = subfam ? candidates.filter(f => !f.subfamily || f.subfamily === subfam) : candidates;
-        const open = scoped.filter(f => !f.intentSuppressed && !f.pastDecision && (f.severity === 'critical' || f.severity === 'high'));
+        const minRank = SEVERITY_RANK[minSeverity];
+        const open = scoped.filter(f => !f.intentSuppressed && !f.pastDecision && (SEVERITY_RANK[f.severity] ?? 0) >= minRank);
         if (open.length) {
           allCleared = false;
-          obs.push(`${open.length} open ${fam} finding(s) at high/critical.`);
+          contributingFindings.push(...open);
+          obs.push(`${open.length} open ${fam} finding(s) at ${minSeverity}+.`);
         } else {
-          obs.push(`✓ ${fam}: no open critical/high findings.`);
+          obs.push(`✓ ${fam}: no open ${minSeverity}+ findings.`);
           anyCleared = true;
         }
         anySignal = true;
@@ -399,10 +540,13 @@ export function evaluateFramework(scanRoot, fw, scan) {
     // artifacts are absent (they degrade to `unmeasured`, never to a default).
     let evidence = null;
     try { evidence = _strengthOfControl(c); } catch { /* strength is additive; never block evaluation */ }
+    const dedupedRefs = [...new Set(contributingFindings.map((f) => f.id).filter(Boolean))];
     results.push({
       control: c,
       status,
       observations: obs,
+      controlRefs: dedupedRefs,
+      derivedProvenance: deriveComplianceProvenance(contributingFindings),
       ...(evidence ? { evidence, partiallyEvidenced: evidence.tier === 'weak' || evidence.tier === 'unmeasured' } : {}),
     });
   }
@@ -420,7 +564,7 @@ export function renderWalkthrough(fw, evaluation, opts = {}) {
   lines.push(`> License: ${fw.license}`);
   if (fw.url) lines.push(`> Source: ${fw.url}`);
   lines.push('');
-  lines.push('> **This walkthrough organizes scanner evidence into a narrative for an external auditor.** It does NOT certify compliance. A licensed assessor is responsible for the final attestation.');
+  lines.push(`> **This walkthrough organizes scanner evidence into a narrative for an external auditor.** ${EVIDENCE_GRADE_DISCLAIMER_SHORT}`);
   lines.push('');
 
   const present  = evaluation.filter(e => e.status === 'present').length;
@@ -457,6 +601,27 @@ export function renderWalkthrough(fw, evaluation, opts = {}) {
     if (ev.status === 'absent' || ev.status === 'partial') {
       lines.push(`**Remediation:** address the bullet(s) above, then re-run \`/compliance --walkthrough ${fw.id}\` to update this report.`);
       lines.push('');
+      if (Array.isArray(ev.controlRefs) && ev.controlRefs.length) {
+        lines.push(`**Contributing findings:** ${ev.controlRefs.join(', ')}`);
+        const dp = ev.derivedProvenance;
+        if (dp && dp.earliestOrigin) {
+          const short = String(dp.earliestOrigin.commit || '').slice(0, 7) || 'unknown';
+          const day = String(dp.earliestOrigin.authorDate || '').slice(0, 10);
+          // Only commit/authorDate/authorName are ever read here — same
+          // caveat as deriveComplianceProvenance's earliestOrigin: this
+          // object bypasses redactFindingProvenance, so authorEmail must
+          // never be surfaced from it without routing through that function
+          // first.
+          lines.push(`**Earliest proven origin:** ${short} — ${day} — ${sanitizeForTerminal(_maybePseudonymizeName(dp.earliestOrigin.authorName)) || 'unknown'} (confidence: ${dp.confidence})`);
+          // PRD Section 8 REQUIRED DISCLAIMER, alongside the claim it
+          // qualifies (not just once at the top of the document) — a reader
+          // who skips straight to a control's evidence must still see it.
+          lines.push(`_${PROVENANCE_COMPLIANCE_DISCLAIMER}_`);
+        } else if (dp) {
+          lines.push(`**Earliest proven origin:** unresolved (confidence: ${dp.confidence})`);
+        }
+        lines.push('');
+      }
     }
   }
 
@@ -475,4 +640,4 @@ export function persistWalkthrough(scanRoot, fw, body) {
   return fp;
 }
 
-export const _internals = { _readJson };
+export const _internals = { _readJson, _resolveOpenFindingMinSeverity, SEVERITY_POLICY_FILE };