stella CLI — Forensics Guide

Audience: incident responders and auditors who capture and verify tamper-evident evidence snapshots, including in air-gapped environments.

The stella forensic commands capture and validate evidence bundles without ever mutating the underlying evidence. Outputs are deterministic and verifiable, so a snapshot taken today can be re-verified byte-for-byte against pinned trust roots.

Commands

• stella forensic snapshot create --case <id> --output <path> — capture the current evidence snapshot; emits a manifest plus checksums.
• stella forensic verify --bundle <path> — validate checksums, DSSE signatures, and the timeline chain of custody.
• stella attest verify --file <attestation> — reuse Attestor flows for envelope verification (see the attest guide).

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. See Output and exit codes for the full contract.
• Verification output includes status, checksum, signature, subject, and 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

Related docs

• Attest guide — DSSE envelope creation and verification.
• Output and exit codes — exit-code contract.
• CLI command reference — the full stella verb tree.