Stella Ops — Developer Guide: Deterministic Replay

Purpose

Deterministic Replay ensures any past scan can be re-executed byte-for-byte, producing identical SBOM, Findings, and VEX results, cryptographically verifiable for audits 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

Mongo collections (see ../data/replay_schema.md)
- 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_manifestHash_unique, runs_status_createdAt, bundles_type, bundles_location, subjects_layerDigest
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.

4.7 KiB Raw Blame History