contract-hunter

Contract Hunter Plugin for Hermes

Scout-powered EVM contract vulnerability hunting. Bring the full bounty-hunting pipeline (radar → surface → prove → report) into Hermes as native tools, hooks, and slash commands.

Installation

hermes plugins install NathanOyewole/hermes-contract-hunter

Setup

Scout is auto-detected from common paths (~/.cargo/bin/scout, /usr/local/bin/scout). No SCOUT_PATH needed. Or install Scout at the pinned, reviewed commit:

cargo install --git https://github.com/NathanOyewole/scout --rev e2889e0

Usage

Slash Command

/hunt setup               # Verify Scout is installed
/hunt demo                # Quick demo radar pull
/hunt radar immunefi 5    # Pull 5 new bounty targets
/hunt surface 42          # Surface target #42
/hunt prove 42 "reentrancy in withdraw"  # Prove hypothesis
/hunt report 42           # Generate vulnerability report
/hunt serve 9090          # Start the local dashboard (localhost only)
/hunt status              # Check hunting status

Web Dashboard

Scout includes a local web dashboard. It binds 127.0.0.1 only and requires a token:

scout serve --port 8080
# scout prints a token; open http://127.0.0.1:8080/?token=<token>
# or set your own: scout serve --port 8080 --token <token>

/hunt serve [port] [token] starts it detached from the plugin.

Tools (for agent use)

scout_radar — Pull bounty targets from Immunefi/Sourcify/DexScreener
scout_surface — Fetch contract source, ABI, metadata
scout_prove — Prove vulnerability on local Anvil fork
scout_report — Generate professional vulnerability report
scout_status — Check hunting status

Hooks

on_session_start — Optionally checks for new Immunefi targets (off by default; controlled by auto_pull_immunefi setting)

How It Works

Radar — Pulls bounty programs from Immunefi, Sourcify, and DexScreener
Surface — Fetches contract source code, ABI, and metadata
Prove — Tests vulnerability hypotheses on a local Anvil fork
Report — Generates professional vulnerability reports ready for submission

Disclosures

This plugin wraps the external scout CLI (source: https://github.com/NathanOyewole/scout). When tools are invoked:

Network calls: radar contacts Immunefi, Sourcify, and/or DexScreener (depending on source).
Local Anvil fork: prove executes exploit transactions against a local Anvil fork. The fork RPC is determined by Scout (typically a public Ethereum mainnet endpoint or the one configured in Scout).
Session-start pull: An optional Immunefi radar pull can run on session start. It is off by default and controlled by the auto_pull_immunefi plugin setting. When enabled it blocks briefly and makes a network call.

The Scout binary itself must be installed separately and is the component that performs the actual network and fork work. Review the Scout source before use.

License

MIT

README from the reviewed commit e662662; it updates when the author re-pins.

About