Replay

Deterministic replay engine for reproducing Stella Ops vulnerability verdicts.

Purpose

Replay lets auditors and operators reproduce a vulnerability verdict exactly. Given identical inputs (SBOM, policy, feeds, toolchain), Stella Ops MUST produce identical outputs — and Replay provides the infrastructure to capture, store, and verify these deterministic execution chains, so any past decision can be re-derived and proven byte-for-byte.

Quick Links

• Architecture - Technical design and implementation details
• API Reference - Endpoint summary
• OpenAPI Spec - Machine-readable API definition
• Guides - Replay verification guides
• Schemas - Replay manifest and proof schemas
• Replay Proof Schema - Detailed proof format

Status

Key Features

• Replay Tokens: SHA-256 replay tokens cryptographically bound to input digests (feed manifests, rules/lattice policy versions and hashes, input/evidence hashes, scoring config) and to the caller’s tenant
• Verdict Replay: Execute a captured audit bundle in an isolated, offline context and compare the replayed verdict/decision against the original, reporting input drift and divergence
• Point-in-Time Advisory Queries: Resolve an advisory’s state at a given timestamp, across providers, with timeline and diff views
• Feed Snapshots: Immutable, content-addressed (digest-keyed) point-in-time snapshots of vulnerability feeds, with integrity verification and bundling
• Determinism Verification: Canonical-JSON verdict digesting with a determinism score and difference report

API Surface

All routes are versioned under /v1. The service authenticates via the StellaOps resource-server bearer scheme. Read and deterministic verification endpoints use the replay.token.read policy, which requires replay:read; explicit token, bundle, and snapshot production uses replay.token.write, which requires replay:write. Endpoint policies own this split, so the resource server has no global required scope that would be ANDed with both policies.

Replay tokens

• POST /v1/replay/tokens - Generate a replay token (write)
• POST /v1/replay/tokens/verify - Verify a replay token (read)
• GET /v1/replay/tokens/{tokenCanonical} - Parse token details (read)

Verdict replay

• POST /v1/replay/verdict - Execute a verdict replay from an audit bundle (read)
• POST /v1/replay/verdict/verify - Check replay eligibility (read)
• POST /v1/replay/verdict/compare - Compare two replay executions (read)
• GET /v1/replay/verdict/{manifestId}/status - Replay status (read) — currently returns 501 Not Implemented (no durable replay-execution history is configured)

Point-in-time advisory & feed snapshots

• GET /v1/pit/advisory/{cveId} - Advisory state at a point in time (read)
• POST /v1/pit/advisory/cross-provider - Advisory across multiple providers (read)
• GET /v1/pit/advisory/{cveId}/timeline - Advisory timeline (read)
• POST /v1/pit/advisory/diff - Compare advisory between two timestamps (read)
• POST /v1/pit/snapshots - Capture a feed snapshot (write, audited)
• GET /v1/pit/snapshots/{digest} - Get a snapshot by digest (write)
• GET /v1/pit/snapshots/{digest}/verify - Verify snapshot integrity (write)
• POST /v1/pit/snapshots/bundle - Create a snapshot bundle (write)

Operational

• GET /healthz - Health check
• GET /.well-known/openapi - Inline OpenAPI 3.1 document (tokens API subset)

Persistence & Configuration

• Schema: PostgreSQL schema replay; table replay.feed_snapshot_index keyed on (provider_id, captured_at, digest). Migrations auto-apply on startup via AddStartupMigrations (embedded SQL: Migrations/001_initial_schema.sql).
• Storage driver (Replay:Storage:Driver, default postgres): postgres for live runtime; inmemory is permitted only in the Testing environment.
• Blob store (Replay:Storage:ObjectStore:Driver, default seed-fs): seed-fs (filesystem, default root data/replay/snapshots). The rustfs driver is explicitly unsupported in the current runtime contract.
• Config: section Replay, environment-variable prefix REPLAY_, optional etc/replay.yaml. Authority binding under Replay:Authority (issuer, audiences, required scopes).

Dependencies

Replay deliberately avoids direct project references on upstream domain libraries (and their transitive Postgres/Redis/DSSE graphs). Instead it defines digest-addressed upstream ports in StellaOps.Replay.Core/Providers/UpstreamPorts.cs that production wiring adapts to the real modules.

Upstream (this module reads from, via ports)

• Concelier - Digest-addressed feed snapshot reads (IConcelierFeedSnapshotReader); production wiring binds this to the Replay-internal FeedSnapshotService
• Excititor / VexLens - Digest-addressed raw VEX document reads (IExcititorVexRawReader)
• Policy - Digest-addressed policy bundle reads (IPolicyBundleReader / IPolicyBundleVerifier). Note: as of SPRINT_20260502_014 this port is BLOCKED / not production-wired because Policy does not yet expose a public digest-addressed bundle reader.

Downstream (modules that depend on this)

• Attestor - Consumes/stores replay proofs (claimed; not verifiable from src/Replay — see flagged)
• ExportCenter - Includes replay tokens in exports (claimed; not verifiable from src/Replay — see flagged)

Notes

• Replay does not make vulnerability decisions; it captures inputs and outputs
• Feed snapshots are stored content-addressed by digest, not by mutable feed contents; the index records only (provider_id, digest, captured_at, epoch_timestamp)
• All timestamps are UTC DateTimeOffset values sourced from an injected TimeProvider (never DateTimeOffset.UtcNow) so two runs over identical input produce byte-identical records
• Verdict-digest comparison uses canonical JSON + SHA-256; the ReplayId/JobId correlation handles are operational labels and are deliberately excluded from the content-addressed audit state (see the Determinism Analyzer notes in src/Replay/AGENTS.md)

Related Documentation

• Determinism Specification