git.stella-ops.org/docs/modules/cli/guides/forensics.md

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

# 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