stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
62d865080d0e632da334660fea433c2be533c9fd
git.stella-ops.org/docs/modules/findings-ledger
History
master 257e29355b fix(findings-ledger): make initial migration idempotent for replay 
Wraps ENUM type creation in findings.ledger schema with DO blocks that catch
duplicate_object so migration 001 can re-run on a partially-provisioned DB
without crashing. Minor corrections to 002 and 005 (syntax alignment).
Updates RLS contract + operations docs to reflect the replay-safe semantics.
WebService + persistence csproj get the Infrastructure.Postgres migration
reference needed for StartupMigrationHost wiring.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 21:57:31 +03:00
..
contracts
docs consolidation
2026-01-07 10:23:21 +02:00
openapi
save dev progress
2025-12-26 00:32:58 +02:00
operations
fix(findings-ledger): make initial migration idempotent for replay
2026-04-13 21:57:31 +03:00
airgap-provenance.md
Add PHP Analyzer Plugin and Composer Lock Data Handling
2025-11-22 14:02:49 +02:00
deployment.md
audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories
2026-01-07 18:50:11 +02:00
dsse-policy-linkage.md
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
export-http-surface.md
Add new features and tests for AirGap and Time modules
2025-11-20 23:29:54 +02:00
gaps-FL1-FL10.md
product advisories add change contiang folder
2026-01-08 09:06:03 +02:00
golden-checksums.json
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
implementation_plan.md
audit remarks work
2025-12-30 16:10:34 +02:00
merkle-anchor-policy.md
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
oas-baseline.md
Add new features and tests for AirGap and Time modules
2025-11-20 23:29:54 +02:00
observability.md
up
2025-12-09 00:20:52 +02:00
README.md
refactor(findings): merge VulnExplorer into Findings Ledger
2026-04-08 13:43:04 +03:00
redaction-manifest.json
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
redaction-manifest.yaml
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
replay-checksums.sample.json
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
replay-harness.md
Implement ledger metrics for observability and add tests for Ruby packages endpoints
2025-11-13 09:29:09 +02:00
schema-catalog.md
new advisories work and features gaps work
2026-01-14 18:39:19 +02:00
schema.md
Refactor compare-view component to use observables for data loading, enhancing performance and responsiveness. Update compare service interfaces and methods for improved delta computation. Modify audit log component to handle optional event properties gracefully. Optimize Monaco editor worker loading to reduce bundle size. Introduce shared SCSS mixins for consistent styling across components. Add Gitea test instance setup and NuGet package publishing test scripts for CI/CD validation. Update documentation paths and ensure all references are accurate.
2025-12-26 21:39:36 +02:00
tenant-isolation-redaction.md
feat: Add VEX compact fixture and implement offline verifier for Findings Ledger exports
2025-12-02 21:08:01 +02:00
workflow-inference.md
Add SBOM, symbols, traces, and VEX files for CVE-2022-21661 SQLi case
2025-11-08 20:53:45 +02:00

README.md

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