up

docs/replay/DEVS_GUIDE_REPLAY.md

@@ -0,0 +1,113 @@
+# 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.
+
+---