117 lines
4.7 KiB
Markdown
117 lines
4.7 KiB
Markdown
# 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
|
|
|
|
1. `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[]`.
|
|
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** (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.
|
|
|
|
---
|
|
|
|
## References
|
|
See also:
|
|
- `DETERMINISTIC_REPLAY.md` — detailed manifest schema & CLI examples.
|
|
- `../docs/CRYPTO_SOVEREIGN_READY.md` — RootPack and dual-signature handling.
|
|
|
|
---
|