greyhatcc

greyhatcc

Autonomous offensive security toolkit for Claude Code. 33 skills, 32 commands, 8 agents, 4 MCP servers (Shodan 18 tools, Security Tools 14 tools, HackerOne API 15 tools, Web Tools 24 tools), and 13 hooks for credential guarding, scope validation, finding tracking, hunt state persistence, and context compaction.

v7.0.0 — Complete hunt architecture redesign: event-driven priority-queue engine replaces the waterfall pipeline. Continuous intelligence feedback loop with signal amplification, gadget chaining (provides/requires directed graph), 5-gate validation, dynamic model routing (haiku/sonnet/opus) with automatic escalation, and persistent hunt-state/ directory that survives context compaction and session restarts. Agent count consolidated from 31 to 8 purpose-built workers. Full HackerOne API integration, 4 MCP servers (71 tools), and adaptive WAF evasion.

Prerequisites

• Claude Code CLI installed
• Node.js 20+
• Optional external tools: nmap, subfinder, httpx, nuclei, katana, whois, dig
• Chromium (auto-installed via npx playwright-core install chromium on first use)

Installation

Option A: Add marketplace + install (recommended)

# Add the greyhatcc marketplace
claude plugin marketplace add /path/to/greyhatcc

# Install the plugin
claude plugin install greyhatcc@greyhatcc

Option B: From GitHub

claude plugin marketplace add https://github.com/overtimepog/greyhatcc.git
claude plugin install greyhatcc@greyhatcc

Verify installation

claude plugin list

You should see greyhatcc@local or greyhatcc@greyhatcc with status enabled.

Configuration

Shodan API Key

export SHODAN_API_KEY="your_key_here"

HackerOne API (recommended)

export H1_API_TOKEN="your_token_here"
export H1_USERNAME="your_h1_username"

Get your API token from HackerOne API Settings.

Web Tools (optional, auto-configured)

# Custom Chromium path (optional — auto-detected if installed via playwright-core)
export CHROMIUM_PATH="/path/to/chromium"

# Run browsers with visible UI instead of headless (default: headless)
export WEB_TOOLS_HEADLESS="false"

NVD API Key (optional, higher rate limits)

export NVD_API_KEY="your_key_here"

External AI (optional, enhances hunt mode)

# Perplexity — real-time CVE intel, program research, dupe checks
# Configure via MCP: mcp__perplexity-ask__perplexity_ask

# OpenRouter — large-context analysis via minimax/minimax-m2.5
# Configure via MCP: mcp__openrouter__openrouter_chat

# Context7 — live documentation for detected tech stacks
# Configure via MCP: mcp__Context7__resolve-library-id + query-docs

Hunt Mode — Event-Driven Priority Queue Engine

Hunt mode is the flagship feature — an elite autonomous bug bounty operator inspired by XBOW, PentestGPT, and Big Sleep. It uses an event-driven priority queue that continuously dispatches, evaluates, and reprioritizes work items from zero to validated H1-ready reports.

/greyhatcc:hunt <program>
# Resume a previous hunt:
/greyhatcc:hunt --resume
# Focus on specific areas:
/greyhatcc:hunt <program> --focus ssrf,idor

Architecture

HUNT ORCHESTRATOR (opus) — event loop
│
├── SEED: H1 API research → enqueue initial recon work items
│
├── HUNT LOOP (repeats until queue empty or budget exhausted):
│   ├── dequeue() → highest priority queued WorkItem
│   ├── Route to worker by type:
│   │   ├── recon-worker (haiku) — 9 subtypes
│   │   ├── test-worker (sonnet) — 15 subtypes + WAF evasion
│   │   ├── exploit-worker (opus) — PoC dev + chain execution
│   │   ├── validate-worker (sonnet/opus) — 5-gate pipeline
│   │   └── report-worker (sonnet) — H1-ready reports
│   ├── Process result → update surfaces, signals, gadgets, findings
│   ├── Auto-enqueue new_work_items from result
│   └── Every 5 items: intel-worker analyzes + reprioritizes queue
│
├── FINALIZE: coverage report + remaining queue summary
│
└── STATE: hunt-state/ directory (persists across compaction + restarts)
    ├── hunt.json, queue.json, findings.json, surfaces.json
    ├── gadgets.json, signals.json, coverage.json, intel-log.json
    └── reports/, evidence/

Intelligence Systems