# Darknavysecurity Web3 Skills Web3 Skills > Exploit Investigator — Orchestration Guide - Skill: `tomevault-io/darknavysecurity-web3-skills-web3-skills` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/darknavysecurity-web3-skills-web3-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/darknavysecurity-web3-skills-web3-skills/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/darknavysecurity-web3-skills-web3-skills --- # 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: ```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 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. --- > Source: [DarkNavySecurity/web3-skills](https://github.com/DarkNavySecurity/web3-skills) — distributed by [TomeVault](https://tomevault.io).