# 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
```