| 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)
│ └── 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
├── 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:
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
6-7. Analyst-Validator Debate Loop (max 2 rounds)
6a. Analyst → report.md, updates manifest.json
6b. Manifest check
6c. Validator → validation.json
6d. If no CRITICAL → done
6e. If CRITICAL + round < 2 → revise
6f. 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 check failures are warnings. Exit code 1 from
check_manifest.py → warn user and continue.
- 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.
