git.stella-ops.org/docs/modules/findings-ledger

Findings Ledger

Immutable, append-only event ledger for tracking vulnerability findings, policy decisions, and workflow state changes across the StellaOps platform.

Purpose

• Audit trail: Every finding state change (open, triage, suppress, resolve) is recorded with cryptographic hashes and actor metadata.
• Deterministic replay: Events can be replayed to reconstruct finding states at any point in time.
• Merkle anchoring: Event chains are Merkle-linked for tamper-evident verification.
• Tenant isolation: All events are partitioned by tenant with cross-tenant access forbidden.

Consolidated modules (Sprint 207)

The src/Findings/ directory is the unified home for all findings-related services:

• Findings Ledger (StellaOps.Findings.Ledger, StellaOps.Findings.Ledger.WebService): Core append-only event ledger.
• RiskEngine (StellaOps.RiskEngine.Core, StellaOps.RiskEngine.WebService, StellaOps.RiskEngine.Worker): Computes risk scores using CVSS, EPSS, KEV, exploit maturity, fix-chain attestation, and VEX gates. Infrastructure lives under __Libraries/StellaOps.RiskEngine.Infrastructure.
• VulnExplorer (merged into Findings Ledger WebService, SPRINT_20260408_002): VulnExplorer endpoints (/v1/vulns, /v1/vex-decisions, /v1/evidence-subgraph, /v1/fix-verifications, /v1/audit-bundles) are now served by StellaOps.Findings.Ledger.WebService. Contracts live under Contracts/VulnExplorer/, adapter services under Services/VulnExplorerAdapters.cs. The standalone StellaOps.VulnExplorer.Api container (stellaops-api) has been decommissioned.

Previously archived docs for RiskEngine and VulnExplorer are in docs-archived/modules/risk-engine/ and docs-archived/modules/vuln-explorer/.

Quick links

• FL1–FL10 remediation tracker: gaps-FL1-FL10.md
• Implementation plan: implementation_plan.md
• Schema catalog (events/projections/exports): schema-catalog.md
• Merkle & external anchor policy: merkle-anchor-policy.md
• Tenant isolation & redaction manifest: tenant-isolation-redaction.md

Compatibility read-model surfaces

• GET /api/v2/security/vulnerabilities/{identifier} is the authoritative shipped vulnerability-detail route for the Web console.
• The route is backed by Findings Ledger projections plus optional scoring state. Unknown fields remain null or absent instead of being fabricated in the API or the web client.
• signedScore is emitted only when cached or historical scoring state exists for the resolved finding.
• proofSubjectId is surfaced only when the projection carries replay/proof identity, allowing the Web console to enable verification only when a real proof subject exists.

Runtime cutover status

• RiskEngine.WebService is PostgreSQL-backed in every non-testing environment. The previous live in-memory score-result path is no longer part of the production host composition root.
• Findings.Ledger.WebService keeps compatibility-only scoring state, webhook registration state, runtime traces/timeline state, and merged VulnExplorer write state isolated to Testing. In non-testing environments those retired write surfaces return truthful 501 problem+json responses instead of fabricating success.
• Projection-backed read surfaces remain live and truthful: GET /v1/vulns, GET /v1/vulns/{id}, GET /v1/evidence-subgraph/{vulnId}, and GET /api/v2/security/vulnerabilities/{identifier} still resolve from persisted Findings projections.
• LedgerDataSource now applies UTC session defaults and search_path=findings,public on every PostgreSQL connection so raw-SQL repositories resolve canonical Findings tables consistently after restart.

Implementation Status

Delivery Phases

• Phase 1 – Observability baselines: Instrument writer/projector with metrics, structured logs, OTLP exporters, Grafana dashboards + alert rules
• Phase 2 – Determinism harness: Finalize NDJSON fixtures for ≥5M findings/tenant, implement replay harness CLI, add CI pipeline jobs
• Phase 3 – Deployment & backup collateral: Integrate ledger service into Compose/Helm, automate PostgreSQL migrations, document backup cadence
• Phase 4 – Provenance & air-gap extensions: Ingest orchestrator run export metadata, extend ledger events for bundle provenance, store attestation pointers

Key Dependencies

• AdvisoryAI Sprint 110.A completion (raw findings parity)
• Observability schema approval to unblock Phase 1 instrumentation
• QA lab capacity for 5M replay checkpoint
• DevOps review of Compose/Helm overlays
• Orchestrator export schema freeze for provenance linkage

Acceptance Criteria

• Metrics/logging/tracing implementation merged with dashboards exported
• Harness CLI + fixtures + signed reports committed
• Compose/Helm overlays + backup/restore runbooks validated
• Air-gap provenance fields documented + implemented
• Sprint tracker and release notes updated after each phase