Quickstart Guide

Install and run HunterX in 5 minutes.


Prerequisites


Installation

pip install hunterx

Docker

docker pull nullc0d30/hunterx:latest
docker run --rm nullc0d30/hunterx:latest --help

See the full Installation Guide for all methods (pipx, install.sh, source).


Your First Scan

# One-shot scan
hunterx target.com

# Explicit scan command
hunterx scan https://example.com

This runs a standard scan with all 41 security skills, response differential analysis, and WAF detection.

Scan Presets

# Quick preset (common vectors only)
hunterx scan https://example.com --preset quick

# Full preset (all skills, maximum coverage)
hunterx scan https://example.com --preset full --threads 10

# Stealth preset (low noise, production-safe)
hunterx scan https://example.com --preset stealth

Profiles

# Bounty profile — balanced, bug-bounty-oriented skills
hunterx scan https://example.com --profile bounty

# Internal profile — comprehensive, all skills
hunterx scan https://example.com --profile internal

# Government profile — strict compliance, detailed reporting
hunterx scan https://example.com --profile gov

Authentication Scanning

# Basic authentication
hunterx scan https://example.com --auth basic --username admin --password secret

# Bearer token
hunterx scan https://example.com --auth bearer --token eyJhbGciOiJIUzI1NiIs...

# Cookie-based session
hunterx scan https://example.com --auth cookie --cookie-file cookies.json

# Form login
hunterx scan https://example.com --auth form --username admin \
    --login-url https://example.com/login


AI-Assisted Scanning

# Local model with Ollama
hunterx scan https://example.com --ai --ai-model llama3.2

# OpenAI
hunterx scan https://example.com --ai --ai-model gpt-4

# Custom AI settings
hunterx scan https://example.com --ai --ai-model gpt-4 --ai-endpoint https://my-proxy.example.com

Multi-Target Scanning

for url in target1.com target2.com target3.com; do hunterx scan "$url"; done

# Dry run (logic check only, no requests sent)
hunterx scan target.com --dry-run

API Server Mode

# Start the API server
hunterx api --port 8443

Submit scan jobs via REST API:

curl -X POST http://localhost:8443/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "profile": "bounty"}'

See the REST API reference for all 40+ endpoints.


Docker Usage

# Basic scan with reports volume
docker run --rm \
  -v $(pwd)/reports:/data \
  nullc0d30/hunterx:latest \
  scan target.com -o /data

# AI-assisted scan
docker run --rm \
  -v $(pwd)/reports:/data \
  -e OPENAI_API_KEY=sk-... \
  nullc0d30/hunterx:latest \
  scan target.com --ai --ai-model gpt-4 -o /data

# API server
docker run --rm -p 8443:8443 nullc0d30/hunterx:latest api --port 8443

See the Docker Guide for production deployment.


Output

Reports are generated in the output directory:

Format Use Case
Markdown Human-readable summary
JSON Machine-parsable findings
SARIF 2.1 VS Code / GitHub CodeQL
HTML Interactive dashboard
Attack Graph Visual path analysis
ZIP Evidence package

What’s Next