Quickstart Guide
Install and run HunterX in 5 minutes.
Prerequisites
- Python 3.11+
- pip or pipx
- (Optional) Docker
- (Optional for AI features) Ollama or OpenAI API key
Installation
pip (Recommended)
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
- Installation Guide — All install methods
- CLI Reference — All commands and arguments
- REST API — All endpoints and examples
- Security Skills Framework — 41 skills
- Docker Guide — Production deployment
- Plugin Development — Extend HunterX
- Contributing — How to contribute