work

docs/modules/cli/guides/forensics.md

@@ -0,0 +1,32 @@
+# stella CLI — Forensics Guide
+
+## Commands
+- `stella forensic snapshot create --case <id> --output <path>`: capture current evidence snapshot; emits manifest + checksums.
+- `stella forensic verify --bundle <path>`: validate checksums, DSSE signatures, and timeline chain-of-custody.
+- `stella attest verify --file <attestation>`: reuse attestor flows for envelope verification (see `guides/commands/attest.md`).
+
+## Flags
+- `--offline`: prohibit network access; use local bundles only (exit code 5 if remote call would occur).
+- `--output json|table` (default json) for verification results.
+- `--trust-roots <file>`: PEM/TUF/DSSE trust roots for verification.
+
+## Outputs & exit codes
+- Success → 0; verification failure → 3; missing bundle → 4; offline violation → 5.
+- Verification output includes `status`, `checksum`, `signature`, `subject`, `rationale` fields; ordering is deterministic.
+
+## Determinism rules
+- Snapshots record UTC timestamps and stable file ordering; hashes are lowercase hex.
+- CLI never mutates evidence; it only validates and reports.
+
+## Offline/air-gap notes
+- Always supply trust roots from sealed media when in air-gap mode; no remote key fetch is allowed.
+- Store snapshots under a deterministic path (`case-id/date/`) to simplify audits.
+
+## Examples
+```bash
+# Create a snapshot for case ACME-123
+stella forensic snapshot create --case ACME-123 --output out/forensics/acme-123.tgz
+
+# Verify a snapshot with pinned trust roots
+stella forensic verify --bundle out/forensics/acme-123.tgz --trust-roots trust/roots.pem --output table
+```