7943cfb3af
Bundled pre-session doc + ops work: - docs/modules/**: sync across advisory-ai, airgap, cli, excititor, export-center, findings-ledger, notifier, notify, platform, router, sbom-service, ui, web (architectural + operational updates) - docs/features/**: updates to checked excititor vex pipeline, developer workspace, quick verify drawer - docs top-level: README, quickstart, API_CLI_REFERENCE, UI_GUIDE, code-of-conduct/TESTING_PRACTICES updates - docs/qa/feature-checks/: FLOW.md + excititor state update - docs/implplan/: remaining sprint updates + new Concelier source credentials sprint (SPRINT_20260422_003) - docs-archived/implplan/: 30 sprint archival moves (ElkSharp series, misc completed sprints) - devops/compose: .env + services compose + env example + router gateway config updates File-level granularity preserved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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 byStellaOps.Findings.Ledger.WebService. Contracts live underContracts/VulnExplorer/, adapter services underServices/VulnExplorerAdapters.cs. The standaloneStellaOps.VulnExplorer.Apicontainer (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.
signedScoreis emitted only when cached or historical scoring state exists for the resolved finding.proofSubjectIdis 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.WebServiceis 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.WebServicekeeps compatibility-only scoring state, webhook registration state, runtime traces/timeline state, and merged VulnExplorer write state isolated to explicitTestingharness wiring. In non-testing environments those retired write surfaces return truthful501 problem+jsonresponses instead of fabricating success.- Projection-backed read surfaces remain live and truthful:
GET /v1/vulns,GET /v1/vulns/{id},GET /v1/evidence-subgraph/{vulnId}, andGET /api/v2/security/vulnerabilities/{identifier}still resolve from persisted Findings projections. LedgerDataSourcenow applies UTC session defaults andsearch_path=findings,publicon 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