GitHub - Matador-og/huntbot: AI offensive security harness for bug bounty, pentesting, red teaming.

Multi-model offensive security harness for bug bounty, pentesting, red teaming, and LLM Security research.
Runs recon, maps the app, tests for vulns, validates findings, writes reports.

Why huntbot?

Most security tools find things. Huntbot understands things.

Accumulates context — Run 5 knows everything Runs 1-4 discovered. 211KB+ of knowledge per target.
Knows when to stop — Efficiency tracking (bytes/sec) detects when a stage is exhausted vs productive.
Tests like a human — Registers accounts, fills forms, clicks through SPAs with a real browser.
Shares live browser sessions — huntbot crawl share -s <name> opens a tokenized CDP screencast page for human intervention, scrolling, clicking, and typing.
Runs multiple model providers — Claude Code by default; Codex is opt-in with --codex.
Loads methodology by stage — Recon stays focused, mapping gets app/API guidance, and attack stages get deeper validation workflows.
Validates before reporting — 4-gate triage kills false positives so you don't waste program time.
Writes the report — Submission-ready markdown with title, severity, steps to reproduce, impact.
You can steer it — huntbot chat queues guidance; huntbot chat --force interrupts the active run and continues with new direction.

Install

curl -fsSL https://matador.indiesecurity.com/huntbot/install.sh | sh
huntbot setup

View the install script source before running.

Requires at least one model provider: Claude Code for the default path, or Codex CLI for --codex runs. Each run consumes model tokens.

Alternative install methods

Direct download:

Download the binary for your platform from Releases, make it executable, and move to your PATH.

Custom location:

curl -fsSL https://matador.indiesecurity.com/huntbot/install.sh | HUNTBOT_INSTALL_DIR=/usr/local/bin sh

Quick Start

With Claude Code (recommended)

Install the plugin, then talk:

/plugin marketplace add Matador-og/huntbot
/plugin install huntbot@huntbot

> Set up PayPal's bug bounty and start hunting
> Run recon on *.staging.company.com
> What findings do we have?
> Focus on the payment API
> Write up finding-001 for submission

CLI

# Create target
huntbot init paypal --scope "PayPal bug bounty"
vim ~/.huntbot/programs/paypal/scope.md

# Hunt
huntbot auto paypal --max-runs 5 --timeout 7200 -v

# Hunt with Codex instead of Claude
huntbot run paypal --stage 0 --codex
huntbot run paypal --stage 2 --codex --model <model>

# Monitor
huntbot monitor

# Steer mid-run
huntbot chat paypal "focus on IDOR in /api/users/{id}"
huntbot chat --force paypal "pause and switch to auth bypass testing"

# Share a live browser session for manual intervention
huntbot crawl session start paypal
huntbot crawl navigate https://www.paypal.com/ --session paypal
huntbot crawl share -s paypal --host 0.0.0.0 --port 7777
huntbot crawl share -s paypal --close

# Check results
cat ~/.huntbot/programs/paypal/findings.md

How It Works

S0 Recon          Runs subfinder, httpx, katana, gau. Crawls JS bundles.
                  Maps the full attack surface with recon-focused skills.

S1 App Mapping    Registers accounts, logs in, clicks through every feature
                  with a real browser. Captures all HTTP traffic. Feeds
                  everything into the attack surface graph.

S2 Attack Testing Queries the graph for IDOR candidates, auth gaps, hidden
                  endpoints. Loads attack skills only at this point. Every
                  finding passes validation before being written.

S3 Triage         Re-validates every finding. Reproduces 3/3 times. Kills
                  false positives. Writes submission-ready reports.

S4 Final Review   Senior reviewer. Destroys anything that doesn't hold up.
                  Last gate before you submit.

Each stage runs multiple passes. Each pass reads what previous passes found and looks for what they missed. When a pass finds nothing new, the stage advances automatically.

Monitor

Program              Stage  Runs     ctx    find  rpt      eff     status signal
───────────────────────────────────────────────────────────────────────────────────
target-1                S2     8    145K     12K    3  24.5b/s       IDLE  PRODUCTIVE
target-2                S1     3     67K      0K    0   8.2b/s    RUNNING  OK
target-3                S2     5     89K      4K    1   1.1b/s      STALE  LOW EFF

Auto-detects diminishing returns and stops wasting compute.

Built-in Tools

Tool	What it does
`huntbot crawl`	Playwright browser — persistent sessions, CDP screencast sharing, navigation, form actions, capture, JS evaluation
`huntbot ingestor`	Neo4j attack surface graph — IDOR detection, auth-gap analysis, endpoint classification
`huntbot matador`	Android testing — ADB, Frida SSL bypass, mitmproxy capture

Plus recon tools: subfinder, httpx, katana, gau (installed by huntbot setup).

Commands

Command	Description
`huntbot init <slug>`	Create target workspace
`huntbot auto <slug>`	Run full pipeline (S0-S4)
`huntbot run <slug> --stage N`	Run one stage
`huntbot monitor [slug]`	Health dashboard
`huntbot chat <slug> "msg"`	Queue guidance for the next agent run
`huntbot chat --force <slug> "msg"`	Interrupt the active run and continue with queued guidance
`huntbot status <slug>`	Target info
`huntbot update`	Self-update
`huntbot setup`	Install dependencies

Flag	Default	Recommended
`--max-runs`	3	5+ for complex apps
`--timeout`	1800	7200 (2 hours)
`--codex`	off	Use Codex instead of Claude for a run or pipeline
`--model`	provider default	Override the selected provider model
`-v`	off	Always on
`--max-stage`	4	1 for recon-only

Docs

Workspace structure — what lives in ~/.huntbot/programs/
Configuration — config, flags, environment variables
Tools reference — crawl, ingestor, matador full command list
Monitor & signals — dashboard, health signals, efficiency tracking
Skills — auto-loaded methodology per target type

Publisher

Huntbot is published by indieSecurity SARL.

License

BSD 3-Clause. See LICENSE.