OpenHunt

Agentic offensive security for Claude Code.

Point OpenHunt at any target you're authorised to test, and it runs the whole engagement autonomously: recon, deep testing, evidence-verified findings, and a written report.

Under the hood, a strategic hunt-director orchestrates a fleet of 35 agents and 138 methodology skill libraries.

📖 Read the deep-dive: OpenHunt, agentic offensive security →

⚠️ Authorised testing only

Use OpenHunt only against systems you own or are explicitly authorised to test, and you are responsible for following each target's rules of engagement and the law.

🚀 Quickstart

Clone, expose the CLI, install optional tools, configure once, add a program, launch:

git clone https://github.com/larsencyber/openhunt && cd openhunt
source openhunt/cli/openhunt.sh          # exposes `openhunt` in THIS shell
openhunt install-cli                     # 1. symlink `openhunt` onto your PATH (~/.local/bin)
openhunt setup-tools                     # 2. print each optional tool + its install command (--run for the easy ones)
openhunt config ~/openhunt               # 3. one-time global setup (proxy · Discord · API keys) + health check
openhunt new --root ~/openhunt           # 4. add a program (scope · brief · research header)
openhunt run acme --root ~/openhunt      # 5. launch: tmux with Caido + jxscout + Claude hunt-director

Want the full walkthrough (prerequisites, configuration, launch)? → Detailed Setup Instructions.

📑 Table of contents

• About OpenHunt
• Features
• Architecture
• Hunt Lifecycle
• Custom Caido Workflows & HTTPQL Presets
• Offensive Recon Data Model (ORDM)
• Hunt Workspace
• Detailed Setup Instructions
  • 1. Prerequisites
  • 2. Configuration
  • 3. Launch Hunt
• License

📖 About OpenHunt

Offensive security is mostly orchestration: enumerate scope, decide where the expected value is highest, drive the right technique deep, prove impact, and write it up.

OpenHunt encodes that loop as a reactive director + specialist agents running inside Claude Code, so effort goes to high-value surface instead of shallow fan-out.

• The director never tests directly. It ranks in-scope clusters by expected value, locks the top one, and briefs specialist subagents.
• Specialists are focused experts. One agent per vulnerability domain (access control, injection, auth, SSRF, cloud, client-side, …), preloaded with the relevant skills.
• Findings are earned, not asserted. Every candidate is independently re-verified by bug-triage and gated for evidence integrity before handoff.
• Passive and active in one loop. 97 Caido workflows tag attack surface in live traffic while specialists test actively; both streams feed the director's ranking.

✨ Features

🏗️ Architecture

A deterministic recon plane feeds an agentic hunt plane through a shared data model and an HTTP proxy (Caido), with a human review gate before submission.

🔄 Hunt Lifecycle

The hunt-director orchestrates 35 agents across the phases below: recon/intel, auth, access/logic, injection, web/client, and platform/infra specialists, plus bug-triage, report-writer, exploit-chainer, and council.

It never tests directly. Each phase it ranks in-scope clusters by expected value, locks the highest, and briefs the specialist matched to the evidence on the attack surface.

Caido mode adds a passive engine: the director also polls Caido detections from the bundled workflows. Under none it runs active-only; the passive poll is skipped, not broken.

Full phase logic, the EV_tokens ranking, dispatch decisions, and compliance Hard Stops: docs/hunt-director-methodology.md.

🧪 Custom Caido Workflows & HTTPQL Presets

OpenHunt ships a passive detection layer for Caido: 97 custom workflows and 531 HTTPQL filter presets, imported once during setup.

• 97 hunt workflows. Passive detectors (hunt-*) that watch live proxy traffic and tag attack surface per vulnerability class: IDOR and mass-assignment surface, JWT/OAuth/SAML auth flows, SSRF and GraphQL surface, cache poisoning, CORS, file upload, and more. Each writes a signal (reporter: openhunt-detect), never a confirmed finding, so the director triages them like any other lead.
• 531 HTTPQL presets. Pre-built Caido queries that slice HTTP history into high-signal views, grouped by intent (attack-surface, vulnerability-indicator, exploitability-signal, workflow-prefilter, interesting-traffic, active-testing). Each preset is keyed to the skill it supports.

The passive engine runs only under Caido egress; its workflow signals feed the hunt-director's ranking loop. The one-time import is covered in Detailed Setup Instructions.

📡 Offensive Recon Data Model (ORDM)

Agents read an ORDM campaign file (newline-delimited JSON) at <workspace>/campaign.ndjson. Bring your own recon with the bundled httpx/ffuf/bbot → ORDM converters, or leave it empty and the director's P1a_unauth_recon phase runs them for you.

Schema, converters, inspection, and the optional ax fleet: docs/ORDM.md.

📂 Hunt Workspace

Everything a hunt reads and writes lives in your workspace. A single root directory holds the install and shared secrets; each program is its own directory beneath it, fully isolated from the others.

~/openhunt/                      # your hunt root
├── .claude/                     # the install: agents/skills/hooks (symlinked) + settings.json + secrets
└── acme/                        # one directory per program
    ├── program-details.md       # your authorised-program brief
    ├── campaign.ndjson          # the ORDM recon store
    ├── hunt-ledger.md           # chronology of the hunt
    ├── config/                  # scope-targets · compliance-headers · program policy
    ├── findings/                # by lifecycle stage (pending-validation · confirmed · reports)
    ├── dossiers/                # one folder per locked cluster
    ├── state/                   # current phase marker + frozen intelligence ranking
    └── lessons/                 # what the hunt learned mid-run

Nothing important is stored in two places. That single-source-of-truth property is what keeps a long multi-agent run from quietly disagreeing with itself.

🔧 Detailed Setup Instructions

1. Prerequisites

Required

Optional. A missing tool logs <TOOL>_UNAVAILABLE and never blocks a hunt. openhunt doctor shows what's live vs gated; openhunt setup-tools prints each install command.

2. Configuration

Run once, top to bottom (then launch with openhunt run, below):

source openhunt/cli/openhunt.sh          # expose `openhunt` in this shell
openhunt install-cli                     # symlink `openhunt` + `ccurl` onto PATH (survives new shells)
openhunt setup-tools                     # list the optional external tools + how to install each
openhunt setup-tools --run               # best-effort install those tools (may prompt for sudo)
openhunt config ~/openhunt               # one-time global setup: writes <root>/.claude/ + secrets, health-check
openhunt new --root ~/openhunt           # add a program: scope, brief, research header -> <root>/<program>/

Manual wiring. A few pieces can't be scripted and are yours to do once by hand; each degrades gracefully if skipped. See docs/manual-setup.md.

3. Launch Hunt

openhunt run [PROGRAM] [--root DIR] is the runtime launcher. It brings up tmux window 1 (Caido → scope → Claude hunt-director) and window 2 (jxscout scoped to your in-scope globs).

openhunt run acme --root ~/openhunt        # PROGRAM optional if the root holds one program
#   --proxy <mode> --proxy-url <url>        # override openhunt.conf
#   --permission-mode <mode>                # default: --dangerously-skip-permissions
#   --no-tmux                               # one-terminal fallback (setupOpenHunt.sh)
#   --no-caido --no-jxscout --no-browser --no-claude   # skip a stage

Every stage except the Claude launch is failure-isolated (warn + continue).

Chrome ↔ chrome-devtools-mcp must match. Leave the mcp on its bundled Chrome (the default); a drifting stable Chrome can hang the CDP pipe and degrade XSS/SSRF steps. The browser canary is the authority; if it reports degraded, fix the pair and re-run.

Full CLI reference (every subcommand and flag): docs/OpenHunt-CLI.md.

📄 License

OpenHunt is dual-licensed; see LICENSE (AGPL-3.0), LICENSE-COMMERCIAL, and the Contributor License Agreement.

Tip: for long autonomous hunts, consider running the caveman plugin alongside OpenHunt to compress agent communication; see its repo.