git.stella-ops.org/docs/replay/DEVS_GUIDE_REPLAY.md

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	✅
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

1. stella scan image:tag --record out/
   • Generates Replay Manifest, InputBundle, OutputBundle, DSSE sigs.
2. stella verify manifest.json
   • Validates hashes, signatures, and completeness.
3. stella replay manifest.json --strict
   • Re-executes in sealed mode; expect byte-identical results.
4. stella replay manifest.json --what-if --vary=feeds
   • Runs with new feeds; diff is attributed to feeds only.
5. stella diff manifestA manifestB
   • Attribute differences by hash comparison.

---

Storage

• Mongo collections
  • replay_runs: manifest + DSSE envelopes + status
  • bundles: content-addressed (input/output/rootpack)
  • subjects: OCI digests, Merkle roots per layer
• File store
  • Bundles stored as <sha256>.tar.zst

---

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

See also:

• DETERMINISTIC_REPLAY.md — detailed manifest schema & CLI examples.
• ../docs/CRYPTO_SOVEREIGN_READY.md — RootPack and dual-signature handling.

---