Files

master 6b15d9827d refactor(findings): merge VulnExplorer into Findings Ledger

- Move VulnExplorer DTOs into Ledger WebService Contracts/VulnExplorer/
  (VulnModels, VexDecisionModels, TriageWorkflowModels, AttestationModels,
   FixVerificationModels, EvidenceSubgraphContracts)
- Create VulnExplorerEndpoints.cs mounting all 10 original endpoints
  (/v1/vulns, /v1/vex-decisions, /v1/evidence-subgraph,
   /v1/fix-verifications, /v1/audit-bundles)
- Create adapter services (VulnExplorerAdapters.cs) that delegate to
  existing Ledger services (FindingSummaryService, VulnerabilityDetailService,
  EvidenceGraphBuilder, VexConsensusService)
- Wire VulnExplorer authorization policies and service registrations
  in Ledger Program.cs
- Comment out api (VulnExplorer) container in docker-compose.stella-ops.yml
- Add vulnexplorer.stella-ops.local as network alias on findings-ledger-web
- Update gateway route: /api/vuln-explorer(..) -> findings.stella-ops.local
- Update STELLAOPS_VULNEXPLORER_URL -> findings.stella-ops.local
- Comment out VulnExplorer in services-matrix.env and hosts file
- Update docs: port-registry, component-map, module-matrix, webservice-catalog,
  findings-ledger README
- Eliminates 1 container (stellaops-api)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-08 13:43:04 +03:00

3.9 KiB

Raw Blame History

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.

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

3.9 KiB Raw Blame History Unescape Escape