@clear-capabilities/agentic-security-scanner 0.142.0 → 0.144.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,217 @@
+// 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)' },
+  { 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: '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,14 +27,18 @@
 // 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';
 
@@ -187,7 +191,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
@@ -291,12 +352,13 @@ 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.`);
+          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;
@@ -420,7 +482,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;
@@ -475,4 +537,4 @@ export function persistWalkthrough(scanRoot, fw, body) {
   return fp;
 }
 
-export const _internals = { _readJson };
+export const _internals = { _readJson, _resolveOpenFindingMinSeverity, SEVERITY_POLICY_FILE };

package/src/posture/calibration-feedback.js

@@ -0,0 +1,201 @@
+// FR-806 (assurance-hardening PRD): "Validate model calibration against
+// accepted and realized incidents where customers opt in | Calibration
+// reports are aggregated and privacy-preserving."
+//
+// SCOPE, stated explicitly because the PRD's own wording is terse: this
+// codebase has no SaaS control plane and takes no runtime cloud calls
+// (root CLAUDE.md's own "No runtime cloud calls" rule, and E10's own goal
+// of "consistent policy... without requiring a SaaS control plane") — so
+// "aggregated" here means aggregated WITHIN one installation, across every
+// feedback event an operator has recorded over time, never aggregated
+// ACROSS installations on some central server. An operator who wants a
+// cross-organization rollup can feed this module's own report output into
+// their own aggregation, the same way `fleet.js` composes many single-repo
+// scans without a hosted backend.
+//
+// TWO OUTCOMES, matching the PRD's own two named cases:
+//   'accepted-risk'    — an operator/customer reviewed a finding, accepted
+//                        the risk, and (later, of their own accord) reports
+//                        that no incident occurred. A well-calibrated model
+//                        should have predicted LOW confidence/risk for
+//                        these.
+//   'realized-incident' — an operator reports that a finding's
+//                        vulnerability WAS actually exploited or otherwise
+//                        caused a real incident. A well-calibrated model
+//                        should have predicted HIGH confidence/risk for
+//                        these — a realized incident on a LOW-predicted
+//                        finding is exactly the miscalibration this
+//                        requirement exists to surface.
+//
+// PRIVACY-PRESERVING AT THE SOURCE, not just at the report layer: a
+// feedback record snapshots only the model's OWN prediction signals
+// (confidence, severity, riskDollars.ev) plus the operator's outcome and
+// optional free-text note — never file path, line, vuln title, or code
+// snippet. This mirrors this codebase's existing privacy modules' own
+// discipline (dataflow/privacy-*.js) of never persisting more than a
+// report needs to answer its one question.
+//
+// OPT-IN, genuinely: nothing here is ever auto-populated by a scan. A
+// record exists only when an operator explicitly calls
+// `recordCalibrationFeedback` (via the CLI's `calibration-feedback record`
+// command) — the file simply does not exist for every project that never
+// opts in, and every read degrades to "no data" rather than throwing.
+
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import { statePath, stateDir, isSafeStateDir, stateWritesEnabled } from './state-dir.js';
+
+export const CALIBRATION_FEEDBACK_FILE = 'calibration-feedback.jsonl';
+export const OUTCOMES = Object.freeze(['accepted-risk', 'realized-incident']);
+
+// Below this many samples, a rate is an artifact of the sample, not a
+// property of the model — same precedent as fix-metrics.js's RELIABLE_N.
+const RELIABLE_N = 10;
+
+function _findFinding(scanRoot, findingId) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8'));
+    const findings = Array.isArray(raw.findings) ? raw.findings : [];
+    return findings.find(f => f && (f.id === findingId || f.stableId === findingId)) || null;
+  } catch { return null; }
+}
+
+// FR-806 privacy fix: the caller-supplied findingId is routinely a finding's
+// plain `.id` (e.g. "client-side:DANGEROUS_INNERHTML:src/billing/secret.js:142"),
+// which embeds the exact file path and line this module's own docstring
+// promises never to persist. Never write the caller's raw string to disk:
+// prefer the matched finding's own privacy-safe `.stableId` (a hash, by
+// construction elsewhere in this codebase), and otherwise hash the input
+// ourselves so a stale/removed finding's id can never leak path/line either.
+function _privacySafeFindingId(findingId, finding) {
+  if (finding && typeof finding.stableId === 'string' && finding.stableId) return finding.stableId;
+  return crypto.createHash('sha256').update(findingId).digest('hex').slice(0, 16);
+}
+
+/**
+ * Record one opt-in calibration-feedback event. Snapshots ONLY the
+ * model's own prediction signals for the named finding (if it is still
+ * present in the last scan — a finding fixed/removed since is still
+ * recordable, just without a fresh snapshot) plus the outcome and an
+ * optional note. Never throws; returns {ok, record} or {ok:false, reason}.
+ */
+export function recordCalibrationFeedback(scanRoot, { findingId, outcome, note } = {}) {
+  if (!findingId || typeof findingId !== 'string') return { ok: false, reason: '--finding-id is required' };
+  if (!OUTCOMES.includes(outcome)) return { ok: false, reason: `--outcome must be one of: ${OUTCOMES.join(', ')}` };
+  const finding = _findFinding(scanRoot, findingId);
+  const record = {
+    at: new Date().toISOString(),
+    findingId: _privacySafeFindingId(findingId, finding),
+    outcome,
+    predictedConfidence: finding && typeof finding.confidence === 'number' ? finding.confidence : null,
+    predictedConfidenceTier: finding?.confidenceTier || null,
+    predictedSeverity: finding?.severity || null,
+    predictedRiskEv: finding?.riskDollars && typeof finding.riskDollars.ev === 'number' ? finding.riskDollars.ev : null,
+    note: note ? String(note).slice(0, 280) : null,
+  };
+  // Append-only, same primitives as fix-metrics.js/triage-memory.js's own
+  // JSONL writers — a single fs.appendFileSync, never a read-modify-write
+  // of the whole file (which would also reintroduce a TOCTOU between an
+  // existence check and the write, the exact anti-pattern this codebase's
+  // own conventions forbid).
+  const dir = stateDir(scanRoot);
+  if (!isSafeStateDir(dir)) return { ok: false, reason: 'no safe state directory' };
+  if (!stateWritesEnabled()) return { ok: false, reason: 'state writes are disabled (--no-state)' };
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(statePath(scanRoot, CALIBRATION_FEEDBACK_FILE), JSON.stringify(record) + '\n', 'utf8');
+  } catch (e) { return { ok: false, reason: e.message }; }
+  return { ok: true, record };
+}
+
+/**
+ * Every well-formed feedback event ever recorded. A line that fails to
+ * parse or lacks a valid outcome is skipped, not fatal.
+ */
+export function loadCalibrationFeedback(scanRoot) {
+  let fp;
+  try { fp = statePath(scanRoot, CALIBRATION_FEEDBACK_FILE); } catch { return []; }
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (rec && OUTCOMES.includes(rec.outcome)) out.push(rec);
+    } catch { /* torn or hand-edited line — drop it, keep the rest */ }
+  }
+  return out;
+}
+
+function _avg(nums) {
+  const v = nums.filter(n => typeof n === 'number' && Number.isFinite(n));
+  return v.length ? v.reduce((a, b) => a + b, 0) / v.length : null;
+}
+
+function _summarizeOutcome(records) {
+  const withConfidence = records.map(r => r.predictedConfidence).filter(c => typeof c === 'number');
+  return {
+    n: records.length,
+    reliable: records.length >= RELIABLE_N,
+    avgPredictedConfidence: _avg(withConfidence),
+    withoutPrediction: records.length - withConfidence.length,
+  };
+}
+
+/**
+ * Aggregate ALL recorded feedback (this installation only — see the
+ * module header for why cross-installation aggregation is out of scope)
+ * into a privacy-preserving report: rates and averages only, never a
+ * per-finding breakdown, never file/line/vuln text (none of that was ever
+ * stored in the first place).
+ */
+export function buildCalibrationReport(scanRoot) {
+  const records = loadCalibrationFeedback(scanRoot);
+  const acceptedRisk = records.filter(r => r.outcome === 'accepted-risk');
+  const realizedIncident = records.filter(r => r.outcome === 'realized-incident');
+  return {
+    schema: 'agentic-security/calibration-report@1',
+    generatedAt: new Date().toISOString(),
+    totalEvents: records.length,
+    acceptedRisk: _summarizeOutcome(acceptedRisk),
+    realizedIncident: _summarizeOutcome(realizedIncident),
+    // The calibration question itself: accepted-risk events SHOULD skew
+    // toward low predicted confidence; realized-incident events SHOULD
+    // skew toward high. This flag is a coarse, disclosed-uncertainty
+    // signal, not a verdict — it only ever fires when BOTH buckets have
+    // enough samples to say anything at all (RELIABLE_N each).
+    possibleMiscalibration: (() => {
+      const a = _summarizeOutcome(acceptedRisk);
+      const r = _summarizeOutcome(realizedIncident);
+      if (!a.reliable || !r.reliable || a.avgPredictedConfidence == null || r.avgPredictedConfidence == null) return null;
+      return r.avgPredictedConfidence <= a.avgPredictedConfidence;
+    })(),
+  };
+}
+
+/**
+ * One block of human-readable summary, or null when nothing has ever been
+ * recorded — genuinely opt-in, so "nothing recorded" is the expected
+ * default state for almost every project, not an error.
+ */
+export function renderCalibrationReportSummary(report) {
+  if (!report || report.totalEvents === 0) return null;
+  const lines = [
+    'Calibration feedback (this installation, opt-in):',
+    `  accepted-risk:     n=${report.acceptedRisk.n}${report.acceptedRisk.reliable ? '' : ' (below reliable sample size)'}` +
+      (report.acceptedRisk.avgPredictedConfidence != null ? `  avg predicted confidence=${report.acceptedRisk.avgPredictedConfidence.toFixed(2)}` : ''),
+    `  realized-incident: n=${report.realizedIncident.n}${report.realizedIncident.reliable ? '' : ' (below reliable sample size)'}` +
+      (report.realizedIncident.avgPredictedConfidence != null ? `  avg predicted confidence=${report.realizedIncident.avgPredictedConfidence.toFixed(2)}` : ''),
+  ];
+  if (report.possibleMiscalibration === true) {
+    lines.push('  ⚠ realized incidents were NOT predicted with higher confidence than accepted risks — possible miscalibration.');
+  } else if (report.possibleMiscalibration === false) {
+    lines.push('  ✓ realized incidents were predicted with higher confidence than accepted risks, as expected.');
+  } else {
+    lines.push('  (not enough samples in both buckets yet to assess calibration — this is not a pass or fail.)');
+  }
+  return lines.join('\n');
+}
+
+export const _internals = { RELIABLE_N, _findFinding };

package/src/posture/calibration-seed.json

@@ -1,6 +1,8 @@
 {
   "_doc": "Seed calibration corpus for P1.3 / FR-UX-1. Each entry is (family, tp, fp) from running the engine against labeled benchmarks. The runtime merges this with the customer's .agentic-security/validator-metrics.json. Customer counts override when their n is higher.",
   "_source": "OWASP Benchmark v1.2 (Java) + Juliet Java + Juliet C/C++ + synthetic-bench fixtures + curated NodeGoat — counts as-of v0.48.0. ~30 samples per family minimum for calibrated emit.",
+  "_generatedAt": "2026-05-18T19:15:00-07:00",
+  "_generatedAtNote": "FR-207: the actual git commit timestamp of this file (git log -1 --format=%aI), recorded here as a machine-readable field so posture/calibration.js's calibrationFreshness() can compute a real age instead of inferring one from the '_source' version string. Update this value only when the family counts below actually change.",
   "_caveat": "This is a SEED corpus, not a held-out test set. The PRD G1 target (Brier ≤ 0.10) requires a separate held-out labeled set; that work is queued for Phase 5 finalization. Calibrated values shipped now are honest empirical TP rates from this seed, with their Wilson 95% CI and N visible so consumers can judge.",
   "families": {
     "sql-injection": { "tp": 41, "fp": 3 },

package/src/posture/calibration.js

@@ -102,6 +102,31 @@ function _readJsonMaybe(fp) {
 // Load history from .agentic-security/validator-metrics.json + the bundled
 // seed file. The bundled seed ships with this release; the customer file
 // overrides per-family when N is higher there.
+// FR-207: freshness of the seed calibration table itself. This is
+// maintainer-authored data (not a per-customer opt-in like
+// compliance-policy.js's `_staleness`), so the check is always-on against
+// one fixed threshold rather than an opt-in interval — there is no
+// owner/reviewer workflow for it to key off. `_generatedAt` missing (an
+// old seed file predating this field) is treated the same as this
+// codebase's other "never dated == already stale" cases, not a free pass.
+const CALIBRATION_MAX_AGE_MS = 180 * 24 * 60 * 60 * 1000;
+let _calibrationFreshnessCache = null;
+export function calibrationFreshness() {
+  if (_calibrationFreshnessCache) return _calibrationFreshnessCache;
+  const seedPath = new URL('./calibration-seed.json', import.meta.url);
+  let generatedAt = null;
+  try { generatedAt = JSON.parse(fs.readFileSync(seedPath, 'utf8'))._generatedAt || null; } catch { /* unreadable seed -> unknown, not fabricated */ }
+  const ts = generatedAt ? Date.parse(generatedAt) : NaN;
+  const baseline = Number.isFinite(ts) ? ts : 0;
+  const ageMs = Date.now() - baseline;
+  _calibrationFreshnessCache = {
+    generatedAt,
+    ageDays: Math.floor(ageMs / 86400000),
+    stale: ageMs > CALIBRATION_MAX_AGE_MS,
+  };
+  return _calibrationFreshnessCache;
+}
+
 export function loadCalibrationHistory(scanRoot) {
   const customer = _readJsonMaybe(statePath(scanRoot, 'validator-metrics.json')) || {};
   const seedPath = new URL('./calibration-seed.json', import.meta.url);