Stella Ops — Developer Guide: Deterministic Replay

Audience: Stella Ops module developers implementing or maintaining replay capture and verification. Scope: What to freeze, how the pieces fit together, and the per-module responsibilities for making a scan reproducible.

For the authoritative manifest schema and CLI reference, see Deterministic Replay Specification. For the manifest export/verify workflow and CI integration, see the Replay Manifest Guide.

Purpose

Deterministic Replay ensures any past scan can be re-executed byte-for-byte, producing identical SBOM, Findings, and VEX results that are cryptographically verifiable for audit or compliance.

Replay is the foundation for:

Audit proofs (exact past state reproduction)
Diff analysis (feeds, policies, tool versions)
Cross-region verification (same outputs on different hosts)
Long-term cryptographic trust (re-sign with new crypto profiles)

Core Concepts

Term	Description
Replay Manifest	Immutable JSON describing all inputs, tools, env, and outputs of a scan.
InputBundle	Snapshot of feeds, rules, policies, and toolchain binaries used.
OutputBundle	SBOM, Findings, VEX, and logs from a completed scan.
Layer Merkle	Per-layer hash tree for precise deduplication and drift detection.
DSSE Envelope	Digital signature wrapper for each attestation (SBOM, Findings, Manifest, etc.).

What to Freeze

Category	Example Contents	Required in Manifest
Subject	OCI image digest, per-layer Merkle roots	✅
Outputs	SBOM, Findings, VEX, logs (content hashes)	✅
Toolchain	Sbomer, Scanner, Vexer binaries + versions + SHA256	✅
Feeds/VEX sources	Full or pruned snapshot with Merkle proofs	✅
Policy Bundle	Lattice rules, mutes, trust profiles, thresholds	✅
Environment	OS, arch, locale, TZ, deterministic seed, runtime flags	✅
Reachability Evidence	Callgraphs (`graphs[]`), runtime traces (`runtimeTraces[]`), analyzer/version hashes	✅
Crypto Profile	Algorithm suites (FIPS, GOST, SM, eIDAS)	✅

Replay Modes

Mode	Purpose	Input Variation	Expected Output
Strict Replay	Audit proof	None	Bit-for-bit identical
What-If Replay	Change impact analysis	One dimension (feeds/tools/policy)	Deterministic diff

Example:

stella replay manifest.json --strict
stella replay manifest.json --what-if --vary=feeds

Developer Responsibilities

Module	Role
Scanner.WebService	Capture full input set and produce Replay Manifest + DSSE sigs.
Sbomer	Generate deterministic SBOM; normalize ordering and JSON formatting.
Vexer/Excititor	Apply lattice and mutes from policy bundle; record gating logic.
Feedser/Concelier	Freeze and export feed snapshots or Merkle proofs.
Authority	Manage signer keys and crypto profiles; issue DSSE envelopes.
CLI	Provide `scan --record`, `replay`, `verify`, `diff` commands.

Workflow

stella scan image:tag --record out/
- Generates Replay Manifest, InputBundle, OutputBundle, DSSE sigs.
- Captures reachability graphs/traces (if enabled) and references them via reachability.graphs[] + runtimeTraces[].
stella verify manifest.json
- Validates hashes, signatures, and completeness.
stella replay manifest.json --strict
- Re-executes in sealed mode; expect byte-identical results.
stella replay manifest.json --what-if --vary=feeds
- Runs with new feeds; diff is attributed to feeds only.
stella diff manifestA manifestB
- Attribute differences by hash comparison.

Storage

PostgreSQL tables (see the database specification for schema details)
- replay.runs: manifest hash, status, signatures, outputs
- replay.bundles: digest, type, CAS location, size
- replay.subjects: OCI digests + per-layer Merkle roots
Indexes (canonical names): runs_manifest_hash_unique, runs_status_created_at, bundles_type, bundles_location, subjects_layer_digest
File store
- Bundles stored as <sha256>.tar.zst in CAS (cas://replay/<shard>/<digest>.tar.zst); shard = first two hex chars

Developer Checklist

[ ] All inputs (feeds, policies, tools, env) hashed and recorded.
[ ] JSON normalization: key order, number format, newline mode.
[ ] Random seed = H(scan.id || MerkleRootAllLayers).
[ ] Clock fixed to scan.time unless policy requires “now”.
[ ] DSSE multi-sig supported (FIPS + regional).
[ ] Manifest signed + optionally anchored to Rekor ledger.
[ ] Replay comparison mode tested across x64/arm64.

References

Deterministic Replay Specification — detailed manifest schema and CLI examples.
Replay Manifest Guide — export, verify, and CI integration.
Test Strategy — how replayability is validated.
Cryptography module — multi-profile (FIPS/GOST/SM/eIDAS) and dual-signature handling.