Exploit Investigator

---
name: exploit-investigator
description: >
  Use when the user provides a transaction hash (0x...) with a chain name,
  asks to investigate an on-chain incident or exploit, or points to an incident brief file.
---

# Exploit Investigator — Orchestration Guide

You are the **orchestrator**. You parse user input, spawn specialized agents via the host's subagent facility, check outputs after each step, and report progress. Agents communicate exclusively through files; you never pass findings directly between agents.

Read `references/pipeline.md` for the full step-by-step pipeline before starting. This file contains the exact prompts to pass to each agent, error handling rules, and the debate loop logic.

This public skill is analysis-only. It stops at validated exploit classification plus `report.md`, `manifest.json`, and `validation.json` outputs. Social copy, homepage metadata, git publishing, and notifications belong in local automation outside this skill.

## Skill Directory

Resolve `{SKILL_DIR}` to the absolute installation path for this skill on the current host. Examples include `~/.claude/skills/exploit-investigator` on Claude Code and `~/.codex/skills/exploit-investigator` on Codex. All file references below use `{SKILL_DIR}` as shorthand for this path.

```
{SKILL_DIR}/
├── references/
│   ├── pipeline.md          ← full orchestration instructions (read this first)
│   ├── report-template.md   ← confirmed-exploit report structure
│   ├── report-template-non-exploit.md
│   └── prompts/
│       ├── planner.md       ← Planner agent instructions
│       ├── data_collector.md
│       ├── decompiler.md    ← Decompiler subagent instructions
│       ├── analyst.md
│       ├── validator.md
│       └── poc_generator.md
├── foundry_template/        ← Foundry project template for PoC generation
│   ├── foundry.toml
│   ├── src/
│   └── test/BaseExploit.t.sol
└── scripts/                 ← Python data-fetching utilities
    ├── check_manifest.py
    ├── check_public_report.py
    ├── fetch_sourcecode.py
    ├── fetch_tac.py
    ├── funds_flow.py
    ├── decode_calldata.py
    └── tac_server.py       ← copy to gigahorse-toolchain root to run TAC server
```

**When spawning agents**, pass them the absolute path to the prompt file. Example:
> Read `{SKILL_DIR}/references/prompts/planner.md`, then execute the instructions with: ...

## Version Check

Before starting the pipeline, run these two checks in parallel if the host supports parallel reads/commands: (a) read `{SKILL_DIR}/VERSION`, (b) run `curl -sf https://raw.githubusercontent.com/DarkNavySecurity/web3-skills/main/exploit-investigator/VERSION`. If the remote fetch succeeds and the versions differ, print:

> ⚠️ You are not using the latest version. Please upgrade for best security coverage.

Skip silently on failure. Then continue with the pipeline.

## Working Directory

Operate from the user's **current working directory** (wherever they invoked the skill). During pipeline execution, all output goes to `analysis_0x{hash}/`. After validation passes, the skill reorganizes analysis outputs:
- Reports are copied to `reports/{incident_name}/`
- Artifacts are moved to `artifacts/analysis_0x{hash}/`
- Ephemeral files (analysis_plan.json, incident_brief.md, issues.json, etc.) are cleaned up

## Python Environment

All Python scripts and the virtual environment are located under the skill installation directory — **always look here first**:

- Scripts: `{SKILL_DIR}/scripts/`
- venv: `{SKILL_DIR}/.venv/`

Run scripts with the skill-local venv:

```bash
source {SKILL_DIR}/.venv/bin/activate
python3 {SKILL_DIR}/scripts/check_manifest.py ...
```

The venv is set up once during installation (`pip install -r requirements.txt`). If `{SKILL_DIR}/.venv/` does not exist, tell the user to run the setup steps from the README.

## Agent Team

Model selection is host-managed. Do not hard-code provider-specific model names in agent spawns. Use the current platform's default compatible subagent model unless the caller explicitly overrides it.

| Agent | Model Strategy | Prompt File | Key Output |
|-------|----------------|-------------|------------|
| Planner | Platform default compatible subagent model | `{SKILL_DIR}/references/prompts/planner.md` | `analysis_plan.json`, `trace_callTracer.json` |
| Data Collector | Platform default compatible subagent model | `{SKILL_DIR}/references/prompts/data_collector.md` | `manifest.json`, contract dirs |
| Decompiler | Platform default compatible subagent model | `{SKILL_DIR}/references/prompts/decompiler.md` | `recovered.sol`, `selector_map.json`, `decompile_meta.json` |
| Analyst | Platform default compatible subagent model | `{SKILL_DIR}/references/prompts/analyst.md` | `report.md`, updates `manifest.json` |
| Validator | Platform default compatible subagent model | `{SKILL_DIR}/references/prompts/validator.md` | `validation.json` |
| PoC Generator | Platform default compatible subagent model | `{SKILL_DIR}/references/prompts/poc_generator.md` | `poc/test/Exploit.t.sol` |

Note: Decompiler is not a standalone pipeline stage — it is spawned by Data Collector on demand for unverified contracts (max 5 concurrent).

## Chain Config

RPC URL pattern: `https://{chain}-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`
(Read `ALCHEMY_API_KEY` from the env or `.env` in the working directory.)

| Chain | Chain ID |
|-------|----------|
| eth | 1 |
| bnb | 56 |
| arb | 42161 |
| polygon | 137 |
| opt | 10 |
| avax | 43114 |
| base | 8453 |

## Pipeline Overview

```
1. Parse input        → tx_hash, chain, hints
2. Setup directory    → analysis_0x{hash}/incident_brief.md
3. Planner Agent      → analysis_plan.json, trace_callTracer.json  [REQUIRED]
4. Data Collector     → manifest.json, contract dirs  [REQUIRED]
5. Manifest check     → python3 {SKILL_DIR}/scripts/check_manifest.py --write-fixes
6-7. Analyst-Validator Debate Loop (max 2 rounds)
   6a. Analyst        → report.md, updates manifest.json using the classification-selected template
   6b. Public report structure check → checker reads `report.is_exploit` from manifest
   6c. Manifest check with `--write-fixes`
   6d. Validator      → validation.json
   6e. If no CRITICAL → done
   6f. If CRITICAL + round < 2 → revise
   6g. If CRITICAL + round == 2 → FAIL
8. Cleanup and organize validated analysis outputs → reports/{name}/, artifacts/analysis_0x{hash}/
8.5. Report results to user
9. PoC Generator      → only if user explicitly requests; run against `artifacts/analysis_0x{hash}/`
```

**See `references/pipeline.md` for complete instructions on each step**, including exact agent prompts, file existence checks, issues.json monitoring, and debate loop revision guidance.

## Key Rules

- **Never auto-run PoC generation.** Only spawn PoC Generator when the user explicitly asks.
- **Stop on missing required outputs.** If `analysis_plan.json` or `manifest.json` is absent after their respective agent runs, report the error and stop.
- **Warn, don't stop, on optional files.** `funds_flow.json`, `decoded_calls.json`, `selectors.json` are optional — warn but continue.
- **Check `issues.json` after every step.** Critical issues require user confirmation before proceeding.
- **Manifest writes are explicit.** Pipeline calls to `check_manifest.py` must use `--write-fixes`; without it the checker is read-only and exits 1 when fixes are required.
- **Manifest check failures are warnings.** Exit code 1 from `check_manifest.py` → warn user and continue.
- **Public report style failures are blocking.** Exit code 1 from `check_public_report.py` means the Analyst must rewrite the report using the template selected by `manifest.report.is_exploit`. Format-only retries do not consume an Analyst-Validator debate round.
- **Multi-tx attacks**: Brief may list multiple tx hashes with roles. Pass all to Planner. Name the analysis dir after the PRIMARY (exploit) tx.
- **Validated analysis contract.** The skill must write enough structured fields into `manifest.json` and `validation.json` for downstream local automation to decide whether the incident is a real exploit and whether derivative artifacts should be generated.