Casefile

Track durable security cases during bug bounties, CTFs, and security audits.

Surface Support

• pi extension — registers tools and /casefile dashboard.
• Codex plugin — MCP server and Skill for autonomous work.

Tools (pi / MCP)

pi	MCP	Description
CaseAdd	casefile_add	Open a new hypothesis or investigation
CaseUpdate	casefile_update	Update fields (status, evidence, impact, etc.)
PromoteFinding	casefile_promote	PoC Runner: Verify PoC in Docker to confirm
CaseGet	casefile_get	Get full details of a single case
CaseList / Search	casefile_list / _search	Browse or search across fields
CaseLink / Unlink	casefile_link / _unlink	Connect primitives into exploit chains
CaseReport	casefile_report	Generate markdown report (confirmed/reported only)

PoC Runner (Docker / Local)

To promote a case from investigating to confirmed, you must use PromoteFinding with an on-disk PoC path.

• Sandbox (Docker): Default. Runs in a --network none container with read-only mounts. Uses python:3.12-slim (.py) or alpine (.sh).
• Local: Use local: true. Runs directly on the host (e.g. for network-dependent bugs).
• Verification: Only promotes to confirmed if the PoC returns exit code 0.
• Timeout: 30 second limit.

Offensive Security Workflow

1. Hypothesize: CaseAdd(status: hypothesis)
2. Investigate: CaseUpdate(status: investigating, evidence, confidence)
3. Confirm: PromoteFinding(id, poc_path, local?) -> Exit 0 verifies and confirms.
4. Chain: CaseLink primitives to escalations.
5. Report: CaseReport -> CaseUpdate(status: reported).
6. Kill: CaseUpdate(status: killed) for dead ends.

State Gates

• hypothesis → investigating requires evidence + confidence.
• investigating → confirmed requires a verified PoC run (exit 0) and poc, evidence, impact, severity.
• confirmed → reported requires CaseReport to have been generated.
• killed and reported are terminal.

Storage & Environment

Stored as JSONL at .casefile/casefile.jsonl (project) or ~/.casefile/casefile.jsonl (global).

• CASEFILE_PATH: Force exact ledger path.
• CASEFILE_SCOPE=project|global: Set storage scope.

---

Install: pi install npm:pi-casefile or codex plugin marketplace add x4cc3/casefile