Quickstart

Prerequisites

Requirement	Why
Python 3.12 or 3.13	silentwitness is a Python CLI
LLM API key	Investigator drives an LLM — Anthropic / OpenAI / Gemini / Ollama
uv or pipx	Installs the CLI globally in an isolated env

Install (pick one)

SIFT 2026 OVA — one command

git clone https://github.com/Blockchain-Oracle/silentwitness && cd silentwitness && ./install.sh
silentwitness --help    # global command, ready

install.sh installs uv, runs uv tool install so the CLI shim lands at ~/.local/bin/silentwitness, then provisions Hayabusa / Chainsaw / Sigma rules / Zeek / Suricata / dfVFS / spaCy NER. Every download SHA256-verified.

Generic — any OS

# uv tool
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "git+https://github.com/Blockchain-Oracle/silentwitness@main"

# pipx
pipx install "git+https://github.com/Blockchain-Oracle/silentwitness@main"

# npm (alias; delegates to uvx)
npm install -g silentwitness

Configure

export ANTHROPIC_API_KEY=...          # or OPENAI_API_KEY / GEMINI_API_KEY
export SILENTWITNESS_MODEL=anthropic:claude-sonnet-4-6
# Cost-safe OpenAI alternative: openai-chat:gpt-5-mini

Env var	Default	What
SILENTWITNESS_MODEL	anthropic:claude-sonnet-4-6	Investigator model. provider:model.
SILENTWITNESS_CRITIC_MODEL	anthropic:claude-haiku-4-5	Live critic model.
SILENTWITNESS_MAX_STEPS / SILENTWITNESS_MAX_ITERS	80	Hard cap on model requests.
SILENTWITNESS_MAX_TOKENS	6,000,000	Run-wide token cap.
SILENTWITNESS_CASES_DIR	./cases	Where investigations are written.

Investigate

# 1) Pick and download a starter case from the SilentWitness catalog.
silentwitness starter-cases catalog
silentwitness starter-cases catalog "Standard Forensic Case"
silentwitness starter-cases download "Standard Forensic Case" /evidence/rocba

# 2) Register, prepare, index, investigate, review, and export.
silentwitness init rocba --examiner "$USER"
silentwitness register-evidence rocba /evidence/rocba
silentwitness prepare rocba
silentwitness index rocba
silentwitness investigate rocba
silentwitness review rocba                  # list staged findings
silentwitness review rocba --finding-id F-001
silentwitness approve rocba F-001
silentwitness verify --audit-chain rocba    # tamper check
silentwitness export rocba --md

The starter-case download is idempotent and resumable. If you already mounted or copied evidence into /evidence, skip the starter-cases download line and pass that existing file or folder path to register-evidence.

Repeat review --finding-id ... and approve ... for each finding you accept. The approval password is a case signing password for the HMAC ledger, not your OS/root password.

What Each Command Does

Command	Meaning
starter-cases catalog/download	Lists the official starter-case catalog and downloads a selected case into /evidence with resumable, idempotent transfers.
init	Creates cases/<case-id>/, the empty report, audit directory, evidence registry, and case metadata.
register-evidence	Adds the evidence file or folder to the case, records its hash, classifies its type, and blocks unsafe writable evidence mounts.
prepare	Extracts the artifacts SilentWitness needs from the registered evidence without modifying the original image.
index	Parses those artifacts into a searchable SQLite/FTS evidence index.
investigate	Runs the agent: form hypotheses, search the index, record cited observations, pivot, and stage findings.
review	Lists staged findings and prints the next commands to inspect or approve them. Use --finding-id for the full evidence block.
approve	Promotes an accepted DRAFT finding into APPROVED report material and signs the case HMAC ledger.
verify --audit-chain	Rechecks the audit JSONL hash chains so tampering is visible.
export	Prints the final report.md path or renders --pdf. IOC sidecars run only when --ioc-format is requested.

That's the full workflow. The report drops at cases/rocba/report.md with inline [verify:audit_id] links resolving to JSONL audit entries.

After export, inspect:

cat cases/rocba/report.md
cat cases/rocba/findings.json | jq '.[] | select(.status == "APPROVED")'
ls cases/rocba/audit/*.jsonl

For GitHub-clickable report, findings JSON, audit JSONL, and ledger examples, open Demo artifacts. The current Mr. Evil VPS showcase bundle is also available directly on GitHub at docs/showcase_runs/mr_evil_openai_gpt_5_2_resume.