fdf95e0f46
- API_CLI_REFERENCE.md, INSTALL_GUIDE.md, quickstart.md, architecture/integrations.md, dev/DEV_ENVIRONMENT_SETUP.md, integrations/LOCAL_SERVICES.md: reflect real-service wiring. - docs/modules/**: module dossier updates across the modules touched by SPRINT_20260415_001..007 + SPRINT_20260416_003..017 + SPRINT_20260417_018..024 + SPRINT_20260418_025 + SPRINT_20260419_026. - docs/features/checked/web/**: update feature notes where UI changed. - docs/qa/feature-checks/runs/web/evidence-presentation-ux/: QA evidence artifacts. - docs/setup/**, docs/technical/**: align with setup wizard contracts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
64 lines
4.8 KiB
Markdown
64 lines
4.8 KiB
Markdown
# 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
|