Findings Ledger

The Findings Ledger is the immutable, append-only event store that records vulnerability findings, policy decisions, and workflow state changes across the Stella Ops platform. It gives operators and auditors a tamper-evident, replayable history of how every finding reached its current state.

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.
• Findings.Security (StellaOps.Findings.Security.WebService): the Console exposure read model (/api/v2/security*); owns the findings_security schema. See security-read-model.md.
• Findings.VulnCorrelation (StellaOps.Findings.VulnCorrelation.WebService): the analytics-ingestion + vulnerability-correlation worker; owns the analytics.* schema (relocated from Platform by PAC-5). See vuln-correlation.md.

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

Quick links

• Findings.VulnCorrelation — analytics ingestion, analytics.* schema ownership
• FL1–FL10 remediation tracker
• Implementation plan
• Schema catalog (events/projections/exports)
• Merkle & external-anchor policy
• Tenant isolation & redaction manifest
• Architecture — runtime instrumentation overview (architecture, endpoints, ADRs)
• Runtime-instrumentation algorithms (privacy filter, aggregation, score formula)
• Runtime-instrumentation API reference
• Enabling runtime instrumentation (1-page guide)
• Runtime-instrumentation ADRs:
  • ADR-013 — Findings Runtime Disabled Mode
  • ADR-014 — Findings Runtime Persistence
  • ADR-015 — Findings Runtime Privacy Filter
  • ADR-016 — Findings Runtime Score Formula

Core API surface (selected)

The Findings Ledger WebService (StellaOps.Findings.Ledger.WebService) hosts the ledger write/read surface plus the merged VulnExplorer, scoring, and runtime endpoints. Routes and authorization are grounded in Program.cs and the Endpoints/ handlers.

The ledger.* and scoring.* policies are bound to whatever findings:ledger:Authority:RequiredScopes resolves to (they do not pin a fixed scope constant); when that list is empty the service falls back to vuln:operate (StellaOpsScopes.VulnOperate). Only the runtime (findings.runtime.*) and VulnExplorer (VulnExplorer.*) policies pin specific scope constants. Tenant resolution uses X-StellaOps-TenantId / X-StellaOps-Tenant headers or the stellaops:tenant claim via StellaOpsTenantResolver. vuln:read is deprecated in favour of vuln:view.

Persistence (schema findings, owned tables in migrations/001_initial.sql and later): ledger_events (append-only, LIST-partitioned by tenant_id, hash-chained via event_hash/previous_hash/merkle_leaf_hash), ledger_merkle_roots, findings_projection, finding_history, and triage_actions. The ledger event-type enum (finding.created, finding.status_changed, …, finding.closed, plus airgap.*, orchestrator.export_recorded, attestation.pointer_linked, and the nis2.*/cra.* incident families) is defined in Domain/LedgerEventConstants.cs. The write path returns a LedgerWriteStatus of Success (201), Idempotent (200), ValidationFailed (400), or Conflict (409).

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.
• RiskEngine.WebService no longer registers null CVSS/KEV/EPSS data sources in non-testing hosts. Source-backed CVSS/KEV/EPSS and exploit-maturity calls fail closed with truthful unsupported/configuration errors unless a real EPSS bundle/snapshot is configured or callers provide explicit inline scoring signals.
• Findings.Ledger.WebService keeps compatibility-only scoring state, webhook registration state, runtime traces/timeline state, evidence-content lookup, reachability mini-map lookup, backport evidence lookup, and merged VulnExplorer write state isolated to explicit Testing harness wiring. In non-testing environments those retired or unimplemented surfaces return truthful 501 problem+json responses instead of fabricating success or returning silent empty data.
• Rekor transparency-log verification is disabled by default. Evidence graph signature checks resolve an unavailable/unverified state until operators explicitly set findings:ledger:rekor:enabled=true and findings:ledger:rekor:baseUrl to a local mirror or approved external Rekor endpoint.
• The merged VulnExplorer VEX override attestor uses TestVexOverrideAttestorAdapter only under the explicit testing harness. Non-testing hosts resolve UnsupportedVexOverrideAttestorAdapter, preserving the fail-closed runtime boundary.
• 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.
• Graph Asset Registry v1 lifecycle events are visible in Findings through the findings.asset_registry_events projection. The Findings worker reads graph.asset_registry_events read-only, preserves Graph payload/event/Merkle hashes unchanged, and checkpoints Graph append order for deterministic catch-up.

Implementation Status

Historical roadmap (largely delivered). The four delivery phases below were the original build-out plan. The code now reflects substantial completion of all four; the phase list is retained for traceability, with the current grounding noted inline. For the live, source-accurate surface, see architecture.mdand the Runtime cutover status section above.

Delivery Phases

• Phase 1 – Observability baselines: Instrument writer/projector with metrics, structured logs, OTLP exporters, Grafana dashboards + alert rules. Delivered: StellaOps.Findings.Ledger.WebService/Program.cs registers AddStellaOpsTelemetry with meter StellaOps.Findings.Ledger (plus the RuntimeInstrumentationMetrics meter) and the RuntimeInstrumentationActivity trace source; activity source StellaOps.Findings.Ledger is declared in Observability/LedgerTelemetry.cs. See observability.md.
• Phase 2 – Determinism harness: Finalize NDJSON fixtures, implement replay harness CLI, add CI pipeline jobs. Delivered: tools/LedgerReplayHarness plus __Tests/StellaOps.Findings.Ledger.ReplayHarness.Tests and StellaOps.Findings.Tools.LedgerReplayHarness.Tests; the replay/diff HTTP surface (POST /v1/ledger/replay, POST /v1/ledger/diff) is live in Program.cs. See replay-harness.md.
• Phase 3 – Deployment & backup collateral: Integrate ledger service into Compose/Helm, automate PostgreSQL migrations, document backup cadence. Delivered: startup auto-migration is wired via AddStartupMigrations<LedgerServiceOptions>(schemaName: "findings", moduleName: "FindingsLedger", …) in Program.cs; 21 embedded SQL migrations (001_initial.sql … 021_vex_override_envelopes.sql) live under StellaOps.Findings.Ledger/migrations/. See deployment.md.
• Phase 4 – Provenance & air-gap extensions: Ingest orchestrator run export metadata, extend ledger events for bundle provenance, store attestation pointers. Delivered: POST /internal/ledger/orchestrator-export, POST /internal/ledger/airgap-import, and the /v1/ledger/attestation-pointers* routes in Program.cs; backing event types (orchestrator.export_recorded, airgap.bundle_imported, attestation.pointer_linked) in Domain/LedgerEventConstants.cs. See airgap-provenance.md.

Key Dependencies (historical)

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

Acceptance Criteria (historical)

• 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