Findings Ledger Implementation Plan

Purpose

Define the delivery plan for the Findings Ledger service, replay harness, observability, and air-gap provenance so audits can verify deterministic state reconstruction.

Active work

• Runtime fake-removal work for Findings/RiskEngine was completed under docs/implplan/SPRINT_20260415_006_DOCS_policy_findings_signer_real_backend_cutover.md.
• Runtime fake-removal follow-up for remaining Findings/RiskEngine null source defaults is tracked under docs/implplan/SPRINT_20260424_021_Findings_runtime_inmemory_cleanup.md.
• Graph Asset Registry v1 visibility in Findings is implemented under docs/implplan/SPRINT_20260430_070_Graph_asset_node_schema.md by projecting the Graph append-only asset event source into findings.asset_registry_events.
• Use docs/modules/findings-ledger/gaps-FL1-FL10.md for the remaining product-capability remediation backlog.

Current host posture

• RiskEngine.WebService now runs against PostgreSQL outside Testing; in-memory result stores are test-only.
• RiskEngine.WebService non-testing hosts no longer use null CVSS/KEV/EPSS sources. If no real source is configured, source-backed scoring fails closed with unsupported/configuration errors; inline scoring signals remain supported for explicit simulations/jobs.
• Findings.Ledger.WebService non-testing hosts no longer fabricate scoring/webhook/runtime/VulnExplorer write state, nor do evidence-content, reachability mini-map, backport evidence, or risk-explanation lookups silently return empty null results. Retired/unimplemented surfaces fail with truthful 501 problem+json, while explicit Testing harnesses inject the local compatibility stores needed by focused integration tests.
• Alert evidence bundle download now emits a deterministic application/gzip tar archive containing manifest.json, alert.json, and evidence.json. Bundle creation and verification resolve the tenant from the authenticated request context before alert lookup; they do not trust the tenant prefix embedded in a caller-supplied composite alert ID. /v1/alerts/{alertId}/bundle/verify regenerates the archive and validates the caller-supplied SHA-256 hash for simple alert IDs; composite alert IDs containing image path slashes use /v1/alerts/summary?alert_id=..., /v1/alerts/decisions?alert_id=..., /v1/alerts/audit?alert_id=..., /v1/alerts/bundle?alert_id=..., and /v1/alerts/bundle/verify?alert_id=... so the identifier is not truncated by route segmentation. When a signature value is supplied, Findings treats it as DSSE envelope JSON, requires the DSSE payload to bind to the regenerated bundle SHA-256, and verifies the signature against findings:ledger:evidenceBundles:dsseVerification PEM trust roots. Missing trust roots, malformed envelopes, signature mismatches, and payload mismatches fail closed.
• The standalone StellaOps.VulnExplorer.Api host remains retired; no separate fake backend was reintroduced for legacy write flows.

Near-term deliverables

• Observability baselines: metrics, logs, traces, dashboards, and alert rules per docs/modules/findings-ledger/observability.md.
• Determinism harness: replay CLI, fixtures, and signed reports per docs/modules/findings-ledger/replay-harness.md.
• Deployment collateral: Compose/Helm overlays, migrations, and backup/restore runbooks per docs/modules/findings-ledger/deployment.md.
• Provenance extensions: air-gap bundle metadata, staleness enforcement, and sealed-mode timeline entries per docs/modules/findings-ledger/airgap-provenance.md.

Dependencies

• Observability schema approval for metrics and dashboards.
• Orchestrator export schema freeze for provenance linkage.
• QA lab capacity for >=5M findings/tenant replay harness.
• DevOps review of Compose/Helm overlays and offline kit packaging.

Evidence of completion

• src/Findings/StellaOps.Findings.Ledger and src/Findings/tools/LedgerReplayHarness updated with deterministic behavior and tests.
• Replay harness reports (harness-report.json + DSSE) stored under approved offline kit locations.
• Dashboard JSON and alert rules committed under offline/telemetry/dashboards/ledger or ops/devops/findings-ledger/**.
• Deployment and backup guidance validated against docs/modules/findings-ledger/deployment.md.

Reference docs

• docs/modules/findings-ledger/schema.md
• docs/modules/findings-ledger/replay-harness.md
• docs/modules/findings-ledger/observability.md
• docs/modules/findings-ledger/deployment.md
• docs/modules/findings-ledger/airgap-provenance.md
• docs/modules/findings-ledger/workflow-inference.md