Skip to main content
plugin CX Codex

casefile — Claude Code plugin: what it does, how to install

casefile tracks persistent security findings for bug bounties and CTFs with isolated Docker PoC validation.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install casefile@awesome-codex-plugins
Open on GitHub

What casefile does

The plugin supplies MCP tools including casefile_add, casefile_update, casefile_promote, and casefile_report. It stores the investigation ledger as JSONL at .casefile/casefile.jsonl inside the project directory or globally at ~/.casefile/casefile.jsonl. Scope and exact file paths configure via CASEFILE_SCOPE and CASEFILE_PATH environment variables.

Status changes follow strict state gates. Promoting a case from investigating to confirmed requires a successful PoC execution returning exit code 0. By default, the PoC runner launches inside a Docker container without network access (--network none) using python:3.12-slim or alpine images under a 30-second timeout. For network-dependent vulnerabilities, passing local: true runs the code directly on the host.

Offensive workflows support chaining primitives into full exploits using casefile_link. Once findings are verified, casefile_report outputs a structured Markdown summary covering confirmed items, while dead-end leads are moved to the terminal killed state.

What it helps with

  • track vulnerability hypotheses and findings across long security audits
  • validate proof-of-concept scripts inside a containerized sandbox
  • connect isolated primitives into multi-step exploit chains
  • export confirmed security issues into clean Markdown reports

Example prompts for the agent

  • Log a new SSRF finding hypothesis using casefile_add
  • Validate the local exploit script poc.py for case 3 with casefile_promote
  • Link finding 2 to escalation step 5 using casefile_link

How to install casefile

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install casefile@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about casefile

How do I install casefile in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins to register the marketplace, then install the package with /plugin install casefile@awesome-codex-plugins.

How does the PoC verification runner work?

It executes your script in a read-only Docker container with --network none and requires exit code 0 within 30 seconds before confirming the case.

Where does casefile save finding records?

Data is stored as a JSONL ledger at .casefile/casefile.jsonl inside your project or at ~/.casefile/casefile.jsonl in your user directory.

Source text

casefile · MIT
# Casefile — Offensive Security Case Tracker

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`

© x4cc3 · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Security →

From the same set391

The whole set →
claude-code-harness claude-code-harness turns a vague agent idea into a runtime blueprint: request assembly, the turn loop, tool permissions, memory and recovery. CX Codex ★ 1,596repo stars cc cc runs Claude Code reviews, architecture checks, and rescue tasks directly from Codex sessions with tracked background jobs. CX Codex ★ 1,596repo stars claude-code A local MCP bridge connects Codex to an authenticated Claude Code CLI. Use it to check account status, sign in, or run workspace prompts in safe modes. CX Codex ★ 1,596repo stars chatgpt-agent chatgpt-agent is a Claude Code and Codex plugin that brings ChatGPT into review, planning, editing, and implementation tasks. It uses ZIP, MCP, or GitHub access. CX Codex ★ 1,596repo stars bringyour-migration-auditor bringyour-migration-auditor runs a read-only check on a project that just moved from Claude to Claude: rule files, hooks, MCP config, skills, secret references. Use it before the agent edits code. CX Codex ★ 1,596repo stars boss boss chains nine specialist roles from requirements to deployment in Claude Code and Codex. Enforces strict quality contracts and writes disk artifacts. CX Codex ★ 1,596repo stars bindry Compiles Bindry Binders into task-loaded skills, either as pinned snapshots or through live MCP lookups. Useful when instructions should stay out of every prompt. CX Codex ★ 1,596repo stars bgs-modding-superpowers bgs-modding-superpowers — a plugin for Bethesda modpack curation: two MCP servers, an xEdit conflict audit, and agent control over your MO2 install. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open