Findings Ledger — Architecture

The Findings Ledger is the append-only, content-addressed system of record for every vulnerability finding, VEX decision, and risk score the Stella Ops release control plane produces. This page is the architecture-level view of the consolidated Findings module (src/Findings/): the append-only Findings Ledger event spine, the RiskEngine scoring service, the merged VulnExplorer read/write surface, and the runtime instrumentation subsystem that landed across sprints SPRINT_20260429_011..015. It is written for engineers integrating with the ledger and for operators reasoning about its runtime, persistence, and determinism guarantees.

Companion pages. For module overview and runtime-cutover status see README.md. For low-level algorithm semantics see runtime-instrumentation.md. For the on-disk schema see schema.mdand schema-catalog.md. The Console exposure/aggregate contract owned by the dedicated Findings.Security host is documented in security-read-model.md. The Findings.VulnCorrelation worker — owner of the analytics.* schema and of the SBOM/attestation/advisory ingestion lanes — has its own dossier: vuln-correlation.md.

Module composition (Sprint 207 consolidation)

src/Findings/ is the unified home for all findings-related services. Four deployable hosts (three HTTP, one worker) plus their shared libraries live side by side. Each schema-owning host auto-migrates its own schema on startup (AGENTS.md §2.7): findings (Ledger), findings_security (Security), riskengine (RiskEngine), analytics (VulnCorrelation).

The Findings Security host also owns the bounded query-specific GET /api/v2/security/findings/cve-exposure read. It computes exact tenant/CVE and optional region/environment/artifact counts inside PostgreSQL over the owned materialized projection, then returns at most 50 deterministic reachable finding rows. Its verdict is exposed, not_exposed, or unknown; only an all-not-present exact match set proves not_exposed. The projection does not store digest, service, or owner identity, so the endpoint accepts no digest query and reports service/owner as not_recorded rather than inferring them. See security-read-model.mdfor the full contract and successor boundary.

Findings Ledger core surface

The ledger is the append-only event spine. The WebService exposes (non-exhaustive):

• Ledger writes/exports: POST /vuln/ledger/events (scope ledger.events.write), GET /ledger/export/{findings,vex,advisories,sboms} and GET /v1/ledger/attestations (scope ledger.export.read).
• Chain integrity / snapshots / time-travel: MapLedgerChainVerifyEndpoints, POST|GET|DELETE /v1/ledger/snapshots[/{id}], GET /v1/ledger/time-travel/{findings,vex,advisories}, POST /v1/ledger/replay, POST /v1/ledger/diff, GET /v1/ledger/changelog/{entityType}/{entityId}, GET /v1/ledger/staleness, GET /v1/ledger/current-point.
• Attestation pointers: POST|GET /v1/ledger/attestation-pointers[...], per-finding pointer/summary reads, POST /v1/ledger/attestation-pointers/search, PUT /v1/ledger/attestation-pointers/{id}/verification.
• Air-gap / orchestrator provenance: POST /internal/ledger/orchestrator-export, GET /internal/ledger/orchestrator-export/{artifactHash}, POST /internal/ledger/airgap-import.
• Alerts / decisions / evidence: GET /v1/alerts[...], POST /v1/alerts/{alertId}/decisions, GET /v1/alerts/{alertId}/{audit,bundle}, plus VEX consensus (POST /v1/vex-consensus/compute[-batch], projection + issuer reads).
• Finding summary, evidence graph, reachability map, backport, security-vulnerability, scoring, webhook endpoint groups (mapped at the tail of Program.cs).
• Compatibility read-model (dead-routed): findings-ledger still maps GET /api/v2/security/vulnerabilities/{identifier} over the ledger projection set, but the gateway routes ^/api/v2/security(.*) to findings-security, so the live vulnerability-detail route the Web console reaches is served by StellaOps.Findings.Security.WebService(advisory metadata from vuln.advisory_canonical, CVSS from vuln.advisory_cvss, joined to the tenant-scoped findings_security.security_finding_projection; see security-read-model.md → “Per-CVE vulnerability detail”). This ledger handler is retained for its in-process tests but is not gateway-reachable; a CVE id is resolved by an exact tenant-scoped projection-identity query, newest projection wins, no match returns a disclosure-safe 404.

The compatibility EvidenceSubgraphAdapter maps a Ledger EvidenceGraphResponse into the VulnExplorer tree contract without discarding evidence. It uses graph.VulnerabilityId, builds children from inbound edges starting at RootNodeId, orders IDs ordinally, handles cycles, attaches any disconnected nodes deterministically, maps Ledger node types explicitly, and emits only edges whose endpoints resolve in the returned tree. This repairs the backend adapter only. The current Web request route/identifier still does not match the Findings endpoint contract and is not claimed as an end-to-end UI flow.

Background hosted services: LedgerMerkleAnchorWorker, LedgerProjectionWorker, AssetRegistryLedgerProjectionWorker, RuntimeTraceRetentionWorker. The findings schema auto-migrates on startup via AddStartupMigrations("findings", "FindingsLedger", …).

Runtime cutover (truthful fail-closed posture). In non-Testing hosts the WebService deliberately registers Unsupported* services for retired or unimplemented surfaces (evidence content, reachability map, backport evidence, risk-explanation store, score-history store, webhook store/delivery, VulnExplorer VEX-override attestor). Those return 501 problem+json instead of fabricating success. Rekor verification is disabled unless findings:ledger:rekor:enabled=true + a configured baseUrl. See README.md“Runtime cutover status” for the full list.

RiskEngine

RiskEngine.WebService (service name riskengine, riskengine Postgres schema) computes risk scores from registered providers and assesses exploit maturity.

Providers registered in Program.cs: DefaultTransformsProvider, CvssKevProvider, EpssProvider, CvssKevEpssProvider, VexGateProvider, FixExposureProvider (plus FixChainRiskProvider in Core/Providers/FixChain/, which is not registered in the WebService provider registry). The result store is selected by the Storage:Driver config key (default postgres): postgres → PostgresRiskScoreResultStore (requires a connection string and runs the riskengine startup migration), inmemory → InMemoryRiskScoreResultStore which throws unless the host is Testing. CVSS/KEV/EPSS sources fail closed (Unsupported* → 501 risk_sources_unavailable) unless a real EPSS bundle/snapshot/directory is configured under RiskEngine:Sources:Epss:* or the caller supplies explicit inline scoring signals. risk-engine:read and risk-engine:operate are the JWT scopes (StellaOpsScopes.RiskEngineRead / RiskEngineOperate); RiskEnginePolicies.Read/Operate are the policy names.

VulnExplorer (merged)

The standalone StellaOps.VulnExplorer.Api container has been decommissioned (SPRINT_20260408_002). Its endpoints are served by the Ledger WebService (Endpoints/VulnExplorerEndpoints.cs) under vuln:* scopes:

vuln:investigate (VulnExplorer.Investigate) is also registered as a policy. VEX decisions persist in findings.vex_decisions (migration 010); the store is Postgres-backed with an honest empty 200 when a tenant has no decisions.

Findings.VulnCorrelation (analytics ingestion + correlation)

StellaOps.Findings.VulnCorrelation.WebService is a worker — no gateway route, no read-model endpoints, only worker health probes — that owns and auto-migrates the whole analytics.* schema (11 tables, 4 materialized views, the sp_* / compute_daily_rollups / refresh_all_views functions) and runs three hosted consumers:

It was relocated out of platform-web by SPRINT_20260703_001 PAC-5, keeping the Platform:AnalyticsIngestion config section names and the CAS stream checkpoint so ingestion resumed without a gap. Platform retains the read surface (GET /api/analytics/*, scope analytics.read) and the daily-rollup / materialized-view-refresh maintenance lane — the ownership split, the schema, the config keys, and the tenancy constraint (analytics.* has no tenant column) are all documented in vuln-correlation.md.

Runtime instrumentation

What this is for

The runtime instrumentation subsystem turns ad-hoc eBPF / syscall / APM probe observations into a per-finding evidence stream. Operators use the resulting runtime score (0–100) to triage which of N otherwise-equivalent vulnerabilities are actually exercised in production. The feature is gated by findings:ledger:runtime:enabled; operators opt in per the enable guide.

Default-value note (verify before relying on it). The toggle is read in two places with different defaults: RuntimePersistenceExtensions.AddFindingsLedgerRuntimePersistence reads it with defaultValue: true (Postgres repositories wired unless explicitly set to false), while RuntimeCapabilitiesEndpoints reads it with defaultValue: false. The operational intent (ADR-013, enable guide) is opt-in, but the persistence layer wires the Postgres repositories by default. Set the key explicitly in any environment where the posture matters.

Pipeline

flowchart LR
    A[Agent / probe] -->|HTTP POST| B[Ingest endpoint]
    B --> C[Privacy filter
RuntimeSymbolRedactor]
    C --> D[Aggregator
RuntimeTraceAggregator]
    D --> E[(Postgres
findings.runtime_traces
findings.runtime_trace_aggregates
findings.runtime_scores
findings.runtime_timeline_events)]
    E --> F[Score calculator
RuntimeScoreCalculator]
    F --> E
    E --> G[Query API
/runtime/traces
/runtime/score
/runtime-timeline]
    G --> H[CLI / Web console / SDK]

ASCII fallback (for environments where Mermaid does not render):

agent → ingest → privacy filter → aggregator → persistence ─┐
                                                             ├→ score calculator → persistence
                                                             │
                                  query / timeline ←─────────┘
                                          ↓
                                  CLI / UI / SDK

Components

Data model

Four Postgres tables under the findings schema:

• findings.runtime_traces — raw frame stream (frames JSONB), one row per ingested trace observation, keyed by a deterministic id (UUID). Trail evidence; retained per the retention policy. release_id was added in migration 018 for the release-bound unified observation ingest.
• findings.runtime_trace_aggregates — denormalized per-function aggregates, primary key (tenant_id, finding_id, artifact_digest, vulnerable_function). Carries hit_count, first_seen, last_seen, container_count; the entry-point flag was added in migration 013.
• findings.runtime_scores — the most recent computed score per (tenant_id, finding_id) as NUMERIC(5,2) (0–100, CHECK-constrained), the derivation_window_s, and the per-component values stored as a components JSONB object (hits, entryPoint, coverage, recency).
• findings.runtime_timeline_events — append-only timeline events (event_id, kind, occurred_at, optional correlation_id, payload JSONB) backing the runtime-timeline query.

The doc previously described “three tables” and named the aggregate table runtime_aggregates; the shipped schema has four runtime tables and the aggregate table is runtime_trace_aggregates.

See schema.mdand the SQL migrations under src/Findings/StellaOps.Findings.Ledger/migrations/ (files 011–014, 018) for column-level detail.

HTTP surface (summary)

Scope clarification. findings.runtime.read / findings.runtime.write are the authorization-policy names, not the scope strings. In Program.cs the read policy requires the JWT scope findings:read (StellaOpsScopes.FindingsRead) and the write policy requires findings:write. A read-only token is rejected with 403 by the write policy.

Ingest always returns 202 Accepted. When the feature is disabled the Null repositories no-op writes (still 202) and return empty reads, which surface as 404. Empty-result reads return 404 NotFound (not 200 OK + empty array) — this is contract-tested. Clients MUST distinguish the two states.

Full details: runtime-instrumentation-api.md. OpenAPI: docs/modules/findings-ledger/openapi/.

Operational view

• Disabled by default. Operators flip findings:ledger:runtime:enabled to true after reviewing disk and ingest-rate expectations. See enabling-runtime-instrumentation.md.
• Auto-migration. All four runtime tables are created via AddStartupMigrations("findings", "FindingsLedger", …) per CODE_OF_CONDUCT §2.7 — no manual psql step is required on upgrade.
• Observability + retention. Metrics, dashboards, and the retention worker are documented in the runbook (sprint 014): runtime-instrumentation-operations.md (sibling page).
• Disabled-mode contract. When the toggle is off, ingest endpoints return 202 Accepted (no-op acknowledgement) and read endpoints return 404 NotFound. See ADR-013 Findings Runtime Disabled Mode.

Privacy posture

Per-process address tokens (@0x[hex]+ suffixes) are stripped from symbol names and file paths before any persistence path executes. The aggregator’s bucket key is the redacted symbol, so two traces of SSL_write@0xAA… and SSL_write@0xBB… collapse into a single aggregate. The 1-byte loss of fidelity is an explicit design trade-off: the addresses are per-process-image artifacts with no cross-process correlation value. Hit counts and container counts are counts, not identifiers — they cannot de-anonymize which specific pod / process / request produced a trace.

Full rationale, alternatives considered, and per-field redaction rules: ADR-015 Findings Runtime Privacy Filterand runtime-instrumentation.md§1.

Architecture decision records

Determinism contract

Sprint SPRINT_20260501_043 (Group J determinism sweep, builds on Sprints 040 and 041).

The Findings ledger is content-addressed and append-only. Every row identity that participates in the chain hash, the Merkle anchor, or any persisted audit state is derived from canonical content via SHA-256 — there are no Guid.NewGuid() calls on the production path inside src/Findings/StellaOps.Findings.Ledger/. Two replays of the same input produce byte-identical rows.

The single source of truth for the key shapes is LedgerDeterministicIds. Each helper is unit-tested with a stability assertion, a distinctness assertion, and (for one site) a frozen-anchor literal in LedgerDeterministicIdsTests.

Bumping the v1 suffix in any of these keys invalidates existing rows. Pre-prod tolerates a wipe; do not change a key shape on a production ledger without a coordinated re-write.

Time provider injection

Every chain-write site that previously read the wall clock now flows through the constructor-injected TimeProvider. Tests use Microsoft.Extensions.Time.Testing.FakeTimeProvider (MIT, vendored as a package dependency) to fix the recorded time. recorded_at participates in some payload bodies, so freezing the clock is a prerequisite for the byte-identical replay invariant.

A small number of DateTimeOffset.UtcNow reads remain in the ledger project (12 STELLA0112 sites at the close of sprint 043). All of them are either purely observability (for example SnapshotService.ReplayEventsAsync’s ObservedAt metric tag) or operational policy timestamps that do not participate in the chain hash or in any persisted audit state (for example ExpireOldSnapshotsAsync’s sweep cutoff and PostgresSnapshotRepository’s updated_at columns). These will be addressed in a follow-up sprint that injects TimeProvider into the unTimeProvider’d services; they are tracked there.

Decision row contract change (Option A)

DecisionEvent.Id is now string? (nullable) and carries no default. Callers may either supply a content-derived id explicitly or leave it null and let DecisionService.RecordAsync derive one via LedgerDeterministicIds.DecisionIdFromContent(...). The WebService API path takes the latter route; the response and the audit-timeline read path use the populated id from the persisted record.

Signed VEX override anchoring

In non-Testing hosts the WebService wires RealVexOverrideAttestorAdapter, which signs VEX override decisions with a DSSE vex-override@v1 envelope (ES256; key source is PrivateKeyPem, else a stable seed-derived P-256 key from KeySeed) and stores the compact envelope in findings.vex_override_envelopes. When no key source is configured (Enabled=false, or both PEM and seed empty) the adapter degrades honestly to the UNSIGNED interim (PendingVexOverrideAttestorAdapter) rather than fabricating a signature. In Testing hosts a TestVexOverrideAttestorAdapter is used instead.

When a caller requests anchorToRekor=true, Findings calls Attestor’s transparency submission API (POST /api/v1/rekor/entries via the configured findings:ledger:VexOverrideAttestation:AttestorBaseUrl, which defaults to the internal http://attestor.stella-ops.local) instead of talking directly to public Rekor. Attestor’s primary transparency backend is local/offline and air-gap safe. The returned rekorEntryId (RekorEntryId) and rekorLogIndex (RekorLogIndex) DTO fields are compatibility names for the local transparency UUID and monotonic local log index returned by Attestor.

If the transparency submission path is unavailable, Findings fails the create request closed: the /v1/vex-decisions endpoint returns 503 problem+json with title: "local_transparency_unavailable" and a code extension carrying the underlying adapter error (local_transparency_submitter_unavailable when no submitter is configured, local_transparency_submit_failed on a non-2xx Attestor response, or local_transparency_receipt_missing when the receipt has no UUID/log index). A signed-but-unanchored override is not persisted for a request that explicitly required anchoring. The DSSE vex-override@v1 predicate type is https://stellaops.dev/predicates/vex-override@v1 (VexOverrideAttestationOptions.PredicateType); the compact envelope is stored in findings.vex_override_envelopes (migration 021), and the decision row carries the envelope digest and storage reference through signed_override, attestation_ref_id, attestation_ref_digest, and attestation_ref_storage (migration 010).

Cross-links

• API reference: runtime-instrumentation-api.md
• Algorithms (filter / aggregate / score): runtime-instrumentation.md
• Enable guide: enabling-runtime-instrumentation.md
• UI integration requirements: runtime-instrumentation-ui-requirements.md
• CLI reference: ../../cli/findings-runtime.md
• Sample SDK consumer: docs/samples/findings-runtime-sdk/