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)
│   └── 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.