An AI-powered multi-agent pipeline for investigating on-chain attack transactions. Produces comprehensive incident reports with root-cause analysis, structured exploit classification, self-correcting Analyst-Validator debate, and optional Foundry PoC exploits — in minutes.
Built for:
- Security researchers who want fast root-cause analysis before a manual deep-dive
- Protocol teams investigating their own incidents
- CTF competitors working through DeFi exploit challenges
- Anyone learning how on-chain attacks actually work
Usage
# Analyze a transaction (chain: eth | bnb | arb | polygon | opt | avax | base)
/exploit-investigator 0x<tx_hash> <chain>
# Analyze with extra hints (suspected contract, attack type, etc.)
/exploit-investigator 0x<tx_hash> eth "suspected price manipulation on FooPair"
# Analyze from a pre-written brief file
/exploit-investigator briefs/incident.md
# Generate a Foundry PoC for an already-analyzed incident
/exploit-investigator poc 0x<tx_hash>
Pipeline
1. Parse input → tx_hash, chain, hints
2. Setup → analysis_0x{hash}/incident_brief.md
3. Planner → analysis_plan.json, call trace
4. Data Collector → manifest.json, contract sources
5. Manifest Check → auto-corrects manifest
6–7. Debate Loop → Analyst writes report; Validator challenges; repeat ≤2×
8. Cleanup → reports/{incident}/ + artifacts/analysis_0x{hash}/
8.5 Report → paths and validation summary
9. PoC [optional] → artifacts/analysis_0x{hash}/poc/test/Exploit.t.sol
The Analyst-Validator debate loop is the core quality mechanism: the Validator challenges every factual claim against on-chain RPC data, and the Analyst must accept corrections or rebut with evidence. Reports pass only when no critical issues remain.
Output
All output lands in your working directory:
reports/{incident}/report.md ← final incident report
reports/{incident}/validation.json ← final validation result
artifacts/analysis_0x{hash}/manifest.json ← analysis metadata + exploit classification
artifacts/analysis_0x{hash}/poc/test/Exploit.t.sol ← PoC (if requested)
The final report covers:
- Executive summary — what happened, in plain language
- Root cause — vulnerable contract, function, and code snippet
- Attack execution — step-by-step call trace walkthrough
- Financial impact — attacker profit in tokens and USD
- Exploit classification —
manifest.jsonandvalidation.jsonincludeincident_type,is_exploit, andpublishable_reportfor downstream local automation.
Setup
In the setup snippets below, replace {SKILL_DIR} with the absolute installation path for this skill on your host. Examples include ~/.claude/skills/exploit-investigator on Claude Code and ~/.codex/skills/exploit-investigator on Codex.
1. Install the skill
Follow the root install instructions, which installs all skills including this one.
2. Set up Python environment
cd {SKILL_DIR}
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
3. Configure API keys
cp .env.example .env
# Edit .env and fill in at minimum ALCHEMY_API_KEY
ALCHEMY_API_KEY is required for all RPC calls. ETHERSCAN_API_KEY is optional but recommended — without it, source fetching falls back to Etherscan’s public rate limit.
4. Start Gigahorse TAC server (optional, for unverified contracts)
The Decompiler agent uses disassembly + LLM reasoning by default. If you also want Gigahorse TAC for higher-quality control-flow analysis on unverified contracts, see references/gigahorse-tac-server.md.
5. Install Foundry (optional, for PoC generation)
curl -L https://foundry.paradigm.xyz | bash
foundryup
cast is used for selector resolution; forge is needed only to compile and run PoC tests.
Configuration
| Variable | Required | Description |
|---|---|---|
ALCHEMY_API_KEY | Yes | Alchemy API key for RPC access |
ETHERSCAN_API_KEY | No | Etherscan API key for contract source fetching |
Supported Chains
| Alias | Chain | Chain ID |
|---|---|---|
eth | Ethereum | 1 |
bnb | BNB Chain | 56 |
arb | Arbitrum One | 42161 |
polygon | Polygon | 137 |
opt | Optimism | 10 |
avax | Avalanche | 43114 |
base | Base | 8453 |
Architecture
The pipeline uses five specialized agents, each with a focused role:
| Agent | Role |
|---|---|
| Planner | Fetch call trace, identify contracts, decide fetch strategy |
| Data Collector | Fetch tx data, contract sources, decode calls |
| Analyst | Write the incident report |
| Validator | Challenge every claim; block pipeline on critical errors |
| PoC Generator | Write and iterate on a Foundry exploit test |
Agents communicate exclusively through files — no state is passed directly between them. This makes each step auditable and resumable.
Python Scripts
The scripts/ directory contains data-fetching utilities used by the pipeline:
| Script | Purpose |
|---|---|
fetch_sourcecode.py | Fetch verified contract source from Etherscan v2 |
fetch_tac.py | Fetch Gigahorse TAC decompilation; optionally recover to Solidity via LLM |
funds_flow.py | Parse receipt + trace → funds_flow.json with token flows and attacker profit |
check_manifest.py | Validate and auto-correct manifest.json |
decode_calldata.py | Decode call trace using ABI files and cast 4byte fallback |
Known Limitations
Unverified contracts. The pipeline degrades gracefully when source code is not available on Etherscan. TAC decompilation fills the gap, but LLM-recovered Solidity is approximate — treat it as a hypothesis, not ground truth.
Multi-transaction attacks. Provide all related tx hashes in a brief file, annotated with roles (setup, exploit). The pipeline names directories after the primary exploit tx.
RPC coverage. debug_traceTransaction is required. Not all public RPC endpoints support it — Alchemy’s Growth plan and above do.
PoC accuracy. Generated PoC tests are starting points, not guaranteed-working exploits. The PoC Generator iterates up to three times and classifies results as PASS, PASS_WITH_WARNINGS, or FAIL.