docs consolidation

2025-12-24 21:45:46 +02:00
parent 4231305fec
commit 43e2af88f6
76 changed files with 2887 additions and 796 deletions
--- a/docs/modules/cli/guides/commands/scan-replay.md
+++ b/docs/modules/cli/guides/commands/scan-replay.md
@@ -0,0 +1,162 @@
+# scan replay Command Reference
+
+The `stella scan replay` command performs deterministic verdict reproduction using explicit input hashes.
+
+## Synopsis
+
+```bash
+stella scan replay [options]
+```
+
+## Description
+
+Replays a scan with explicit hashes for **deterministic verdict reproduction**. This command enables:
+
+- **Reproducibility**: Re-execute a scan with the same inputs to verify identical results
+- **Audit compliance**: Prove historical decisions can be recreated
+- **Offline verification**: Replay verdicts in air-gapped environments
+
+Unlike `stella replay --manifest <file>` which uses a manifest file, `stella scan replay` accepts individual hash parameters directly, making it suitable for:
+
+- Commands copied from evidence bundles
+- CI/CD pipeline integration
+- Backend-generated replay commands
+
+## Options
+
+### Required Parameters
+
+| Option | Description |
+|--------|-------------|
+| `--artifact <digest>` | Artifact digest to replay (e.g., `sha256:abc123...`) |
+| `--manifest <hash>` | Run manifest hash for configuration |
+| `--feeds <hash>` | Feed snapshot hash at time of scan |
+| `--policy <hash>` | Policy ruleset hash |
+
+### Optional Parameters
+
+| Option | Description |
+|--------|-------------|
+| `--snapshot <id>` | Knowledge snapshot ID for offline replay |
+| `--offline` | Run in offline/air-gapped mode. Requires all inputs to be locally cached |
+| `--verify-inputs` | Verify all input hashes before starting replay |
+| `-o, --output <path>` | Output file path for verdict JSON (defaults to stdout) |
+| `--verbose` | Enable verbose output with hash confirmation |
+
+## Usage Examples
+
+### Basic Replay
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321...
+```
+
+### Replay with Knowledge Snapshot
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321... \
+    --snapshot KS-2025-01-15-001
+```
+
+### Offline Replay with Verification
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321... \
+    --offline \
+    --verify-inputs \
+    --verbose
+```
+
+### Save Output to File
+
+```bash
+stella scan replay \
+    --artifact sha256:a1b2c3d4e5f6... \
+    --manifest sha256:abc123def456... \
+    --feeds sha256:feed789feed... \
+    --policy sha256:policy321... \
+    --output replay-result.json
+```
+
+## Input Hash Verification
+
+When `--verify-inputs` is specified, the command validates:
+
+1. **Artifact digest format**: Must start with `sha256:` or `sha512:`
+2. **Hash lengths**: SHA256 = 64 hex characters, SHA512 = 128 hex characters
+3. **Local availability** (in offline mode): Verifies cached inputs exist
+
+## Offline Mode
+
+The `--offline` flag enables air-gapped replay:
+
+- All inputs must be pre-cached locally
+- No network calls are made
+- Use `stella offline prepare` to pre-fetch required data
+
+## Output Format
+
+```json
+{
+  "status": "success",
+  "artifactDigest": "sha256:a1b2c3d4e5f6...",
+  "manifestHash": "sha256:abc123def456...",
+  "feedSnapshotHash": "sha256:feed789feed...",
+  "policyHash": "sha256:policy321...",
+  "knowledgeSnapshotId": "KS-2025-01-15-001",
+  "offlineMode": false,
+  "startedAt": "2025-01-15T10:30:00Z",
+  "completedAt": "2025-01-15T10:30:45Z",
+  "verdict": {
+    "findingId": "f-abc123",
+    "status": "affected",
+    "confidence": 0.95
+  }
+}
+```
+
+## Integration with Evidence Bundles
+
+Evidence bundles generated by the `/v1/triage/findings/{id}/evidence/export` endpoint include ready-to-run replay scripts:
+
+- `replay.sh` - Bash script for Linux/macOS
+- `replay.ps1` - PowerShell script for Windows
+- `replay-command.txt` - Raw command for copy-paste
+
+Example from evidence bundle:
+
+```bash
+# From evidence bundle replay.sh
+stella scan replay \
+    --artifact "sha256:a1b2c3d4e5f6..." \
+    --manifest "sha256:abc123def456..." \
+    --feeds "sha256:feed789feed..." \
+    --policy "sha256:policy321..."
+```
+
+## Related Commands
+
+| Command | Description |
+|---------|-------------|
+| `stella replay --manifest <file>` | Replay using a manifest file |
+| `stella replay verify` | Verify determinism by replaying twice |
+| `stella replay snapshot` | Replay using knowledge snapshot ID |
+| `stella offline prepare` | Pre-fetch data for offline replay |
+
+## See Also
+
+- [Deterministic Replay Specification](../../replay/DETERMINISTIC_REPLAY.md)
+- [Offline Kit Documentation](../../24_OFFLINE_KIT.md)
+- [Evidence Bundle Format](./evidence-bundle-format.md)