⚔️ HunterX

AI-Assisted Offensive Security Framework — Observe · Hypothesize · Probe · Verify

HunterX is an AI-assisted offensive security framework that combines intelligent reconnaissance, adaptive vulnerability discovery, payload orchestration, and explainable security reasoning into a single modular platform.

# One-shot scan
hunterx target.com

# AI-assisted full scan
hunterx scan https://target.com --ai --ai-model llama3.2

# List modules, run diagnostics, view reports
hunterx module list
hunterx doctor
hunterx report

# Start the REST API server
hunterx api --port 8443

Install · Why HunterX? · Quick Start · CLI Reference · Comparison · Documentation · Contributing

Traditional vulnerability scanners rely on brute-force payload matching against known signatures. HunterX approaches security assessment differently — it reasons about what vulnerabilities might exist before probing, then verifies with evidence.

Who should use HunterX?

Red team operators, penetration testers, bug bounty hunters, security researchers, and DevOps engineers who need an automated, context-aware security assessment platform with safety-by-design guardrails.

How it works:

flowchart LR
    CLI[CLI / API] --> RE[Recon Engine]
    RE --> AE[AI Engine]
    RE --> SK[41 Security Skills]
    AE --> PL[Payload Engine]
    SK --> PL
    PL --> PK[Payload Knowledge Base]
    PL --> RZ[Reasoning Engine]
    PK --> PATT["PayloadsAllTheThings (community-maintained)"]
    RZ --> RP[Reporting]
    RP --> OUT[JSON / SARIF / HTML / Graph]

Key advantages:

• Reasoning-driven pipeline — Observe, Hypothesize, Probe, Verify. HunterX builds a target baseline, forms hypotheses, executes targeted tests, and validates findings with confidence scoring.
• AI-native integration — The reasoning engine, skill planner, report generator, and detection pipeline all consume structured AI output. LLM analysis is optional but deeply integrated.
• 41 built-in security skills — Covering web, API, cloud, network, authentication, and infrastructure security. Each skill carries MITRE ATT&CK, OWASP, CWE, and CAPEC metadata.
• Multi-agent platform — 10 specialized agents collaborate through event-driven communication with DAG-based workflows, checkpoint/resume, and isolated memory.
• Payload Intelligence Platform — SQLite + FTS5-indexed payload repository sourced from the community-maintained PayloadsAllTheThings knowledge base, with 5-level safety policy, 10-family mutation engine, provenance tracking, and context-aware selection.
• Enterprise reporting — JSON, Markdown, SARIF 2.1 (VS Code / GitHub CodeQL), HTML, attack graphs, purple team detection rules, and ZIP evidence packages.
• REST API — FastAPI server with 40+ endpoints covering scanning, payload management, agent coordination, reasoning, skills, and system health.
• Safety-by-design — Non-bypassable destructive payload blocklist, WAF detection with auto-abort, configurable rate limiting, and policy-driven execution controls.
• Single codebase, zero dependencies on external scanners — Pure Python monorepo. No juggling separate tools or piping output between them.

HunterX complements existing security tools rather than replacing them. It fills the gap between signature-based scanners and manual penetration testing.

When to use HunterX: Depth-oriented assessments where you need reasoning, context-aware payload selection, and explainable findings — not just a list of matched signatures.

HunterX leverages the community-maintained PayloadsAllTheThings knowledge base as its primary source of payload data. This is a community project, not a partnership or endorsement — HunterX simply integrates it and gives full credit.

• Sync — hunterx payload sync (or hunterx update --payloads) fetches the latest PayloadsAllTheThings content via a shallow git clone or the latest GitHub release archive.
• Index — hunterx payload index builds a local SQLite + FTS5 full-text index over the synced payload files for fast, context-aware search.
• Provenance — every indexed payload records its origin: source repository, commit hash, release tag, and checksum, so payload history is auditable.
• Selection — payloads are ranked by target technology, framework, language, and WAF presence rather than applied blindly.

hunterx payload sync    # Sync the PayloadsAllTheThings knowledge base
hunterx payload index   # Build the local search index
hunterx payload search sqli   # Search indexed payloads

# System-wide (requires root)
curl -sSL https://raw.githubusercontent.com/nullc0d30/HunterX/main/install.sh | sudo bash

# User-local (no root)
curl -sSL https://raw.githubusercontent.com/nullc0d30/HunterX/main/install.sh | bash -s -- --user

The installer auto-detects your distribution, installs system dependencies, creates a Python virtual environment, and makes the hunterx command available globally with case-variant symlinks.

pip install hunterx
pipx install hunterx           # Isolated environment
pip install hunterx[all]       # With all optional extras

docker pull nullc0d30/hunterx:latest
docker run --rm nullc0d30/hunterx:latest scan target.com
docker run --rm -p 8443:8443 nullc0d30/hunterx:latest api --port 8443

git clone https://github.com/nullc0d30/HunterX.git
cd HunterX
pip install .

# Scan a target with default settings
hunterx example.com

# Explicit scan with options
hunterx scan https://target.com --profile bounty --preset full

# List scan modules
hunterx module list

# Run diagnostics
hunterx doctor

# View reports
hunterx report

# Start API server
hunterx api --port 8443

# Show version
hunterx --version

hunterx scan target.com --profile internal   # Comprehensive
hunterx scan target.com --profile bounty     # Bug-bounty balanced
hunterx scan target.com --profile gov        # Strict compliance
hunterx scan target.com --preset quick       # Common vectors
hunterx scan target.com --preset full        # All skills
hunterx scan target.com --preset stealth     # Low noise

hunterx scan target.com --auth basic --username admin --password secret
hunterx scan target.com --auth bearer --token eyJhbGciOiJIUzI1NiIs...
hunterx scan target.com --auth cookie --cookie-file cookies.json
hunterx scan target.com --auth form --username admin --login-url https://target.com/login

hunterx scan target.com --ai --ai-model llama3.2   # Local Ollama
hunterx scan target.com --ai --ai-model gpt-4       # OpenAI

hunterx [--help] [--version] [-v] [-q] <command> [options]

hunterx module list              # All modules
hunterx module info <id>         # Module details
hunterx module search <query>    # Search modules

hunterx report                   # Overview
hunterx report -o <dir>          # Custom directory
hunterx report --json            # Raw JSON

hunterx config --show            # Current config

hunterx update                   # Everything
hunterx update --force           # Re-download
hunterx update --release         # Release archive
hunterx update --payloads        # Payloads only

hunterx payload sync             # Download payloads
hunterx payload index            # Build search index
hunterx payload search <query>   # Search payloads
hunterx payload info <id>        # Payload reasoning
hunterx payload stats            # Index statistics
hunterx payload top              # Top performers
hunterx payload feedback         # Feedback stats
hunterx payload policy           # Safety policy
hunterx payload provenance <q>   # Provenance history

hunterx agents list              # All agents
hunterx agents status            # Agent health
hunterx agents enable <id>       # Enable agent
hunterx agents disable <id>      # Disable agent

hunterx workflow run <id>        # Execute workflow
hunterx workflow inspect <id>    # Inspect workflow
hunterx workflow graph <id>      # Dependency graph

hunterx reasoning inspect <goal_id>   # Inspect result
hunterx reasoning validate            # Validate output

hunterx skills list              # All skills
hunterx skills info <id>         # Skill details
hunterx skills search <query>    # Search skills
hunterx skills install <path>    # Install skill
hunterx skills uninstall <id>    # Remove skill
hunterx skills enable <id>       # Enable skill
hunterx skills disable <id>      # Disable skill
hunterx skills verify <id>       # Verify integrity
hunterx skills doctor            # Diagnostics
hunterx skills export <id>       # Export package
hunterx skills stats             # Telemetry

hunterx ai providers             # List providers
hunterx ai health                # Check health
hunterx ai config                # View config
hunterx ai cache                 # Cache stats
hunterx ai metrics               # Usage metrics
hunterx ai test                  # Test provider
hunterx ai models                # List models

hunterx api --port 8443                 # Port 8443
hunterx api --host 0.0.0.0 --port 8080  # Custom

hunterx scan target.com --passive-only       # Recon only
hunterx scan target.com --stealth high --threads 2  # Stealth
hunterx scan target.com --dry-run            # Logic check

hunterx scan https://target.com --profile internal --preset full \
    --auth bearer --token $TOKEN --oob
hunterx scan target.com --profile bounty --preset quick \
    --category injection,authentication
hunterx scan api.target.com --category api,cloud --evidence-level high --sarif

hunterx scan target.com --ai --ai-model llama3.2
hunterx scan target.com --ai --ai-model gpt-4 --ai-endpoint https://my-proxy.example.com
hunterx scan target.com --ai --explain

hunterx scan target.com --sarif                # SARIF for CodeQL
hunterx scan target.com --attack-graph          # Attack graph
hunterx scan target.com --threat-model          # Threat model
hunterx scan target.com --purple                # Purple team rules
hunterx scan target.com --graph                 # Knowledge graph

HunterX reads hunterx.yaml from the current directory by default.

Override: hunterx scan target.com -c /path/to/config.yaml

hunterx update                      # Payloads + modules
hunterx update --force              # Full re-download
pip install --upgrade hunterx       # Package itself

# pip / pipx
pip uninstall hunterx
pipx uninstall hunterx

# install.sh (system)
curl -sSL https://raw.githubusercontent.com/nullc0d30/HunterX/main/install.sh | sudo bash -s -- --uninstall

hunterx/
├── cli.py              # CLI entry point (13 command groups)
├── api/                 # FastAPI REST server
├── engines/             # Scan orchestration engine
├── core/                # Core subsystems
│   ├── agents/          # 10-agent platform
│   ├── ai/              # AI provider abstraction
│   ├── reasoning/       # Reasoning engine (18 goal types)
│   ├── skills/          # 41 security skills framework
│   ├── auth/            # Authentication providers
│   └── protocols/       # WebSocket, GraphQL testers
├── modules/             # Pluggable modules
│   ├── intelligence/    # Knowledge graph, threat modeling
│   └── payloads/        # Payload Intelligence Platform
├── reporting/           # Report generation
├── plugins/             # User-extensible plugins
├── utils/               # Logging, plugin loader
└── config/              # Configuration

export PATH="$PATH:/usr/local/bin"      # system install
export PATH="$PATH:$HOME/.local/bin"    # user install

python3 -m pip install --upgrade pip
python3 -m venv venv && source venv/bin/activate && pip install hunterx

hunterx ai health          # Check connectivity
hunterx ai providers       # List configured providers
hunterx ai test            # Send test prompt

See ROADMAP.md for the full development roadmap.

• v6.x — Community skill repository, Anthropic/Gemini/Bedrock providers, provider failover
• v7.x — CI/CD integrations (GitHub Actions, GitLab CI, Jenkins), SIEM connectors, collaborative scanning
• Long-term — Skill marketplace, enterprise features (RBAC, SSO), package managers (Homebrew, apt)

See CHANGELOG.md for the full release history.

HunterX is Apache 2.0 licensed and welcomes contributions.

git clone https://github.com/YOUR_USERNAME/HunterX.git
cd HunterX
python -m venv venv && source venv/bin/activate
pip install -e ".[all]"
git checkout -b feat/your-feature
pytest tests/ -v              # Run tests
ruff check .                  # Check style
git commit -s -m "feat(area): description"
git push origin feat/your-feature

See CONTRIBUTING.md for the full guide.

HunterX is community-driven and Apache 2.0 licensed. Join the project, follow development, and explore the open-source resources it builds on.

• GitHub — Source code, issues, and discussions
• Documentation Site — Full documentation, tutorials, and API reference
• PayloadsAllTheThings — Community-maintained payload knowledge base used by HunterX's Payload Intelligence Platform

HunterX is built on the shoulders of the security community. Payload data is sourced from public security research repositories, including PayloadsAllTheThings and similar community projects, used in accordance with their respective licenses. See NOTICE and RELEASE_NOTES_v6.0.0.md for full attribution.

• Documentation Site — Full documentation, tutorials, and API reference
• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions, ideas, and community support
• Security Policy — Responsible disclosure and reporting process

Copyright 2026 Ahmed Awad (NullC0d3)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

If HunterX helps your security assessments, consider giving the project a GitHub Star. It helps improve visibility and supports continued development.