HunterX
Offensive Security Platform & Intelligent Vulnerability Assessment Framework
Observe → Hypothesize → Probe → Verify
Project Overview
HunterX is an open-source, AI-assisted offensive security platform and intelligent vulnerability assessment framework. Unlike traditional scanners that rely solely on payload execution or signature matching, HunterX follows a reasoning-driven workflow — Observe → Hypothesize → Probe → Verify — enabling context-aware security analysis, evidence-driven decision making, and intelligent vulnerability verification with explainable AI outputs.
AI-Assisted Reasoning Engine — Goals flow through a reasoning engine that plans, prompts, validates, and reaches consensus before returning results. Agents never talk directly to AI providers.
Security Skills Framework (41 skills) — Plugin-based skills covering web, API, cloud, network, and infrastructure security. Each skill carries MITRE ATT&CK, OWASP, CWE, and CAPEC metadata.
Knowledge Graph — Graph-based storage for security relationships, findings, attack paths, and contextual data across scan targets. Enables cross-scan correlation and attack path inference.
Threat Modeling & Attack Chains — Automated threat modeling with STRIDE/LINDDUN categorization, attack chain decomposition, trust boundary mapping, and automated chain inference from scan findings.
Payload Intelligence — SQLite-indexed payload repository with FTS5 full-text search, 5-level execution policy, mutation engine (10 technique families), provenance tracking, user feedback loop, graph-based payload relationships, and context-aware selection.
Explainable AI — Every AI-driven decision produces a structured result with confidence scores, evidence citations, consensus data, decision traces, and provider metadata.
Architecture Overview
Layered architecture where each component has clear responsibilities and communicates through defined interfaces.
+---------------------------+
| CLI / API / Docker |
+-------------+-------------+
|
+-------------+-------------+
| Orchestration Engine |
| (Observe -> Hypothesize -> |
| Probe -> Verify) |
+--+--------+--------+------+
| | |
+--------+ +----+----+ +--------+
| Agents | Reasoning | Skills |
| Platform | Engine | Registry |
| 10 agents| 18 goals | 41 skills|
| Event/Msg| Planner | Executor |
| Bus | Validator | Policy |
| Workflow | Consensus | Cache |
| Scheduler| Confidence| Telemetry|
+----+-----+-----+----+-----+----+
| | |
+----+-----+-----+----+-----+----+
| Payload | Knowledge | Threat |
| Intel | Graph | Modeling |
| FTS5 idx | Neo4j-like| STRIDE |
| Mutation | Relations | Attack |
| Feedback | Paths | Chains |
| Prov. | Context | Trust |
+----+-----+-----------+----------+
|
+----+------+
| AI Provider|
| OpenAI |
| Ollama |
| Sessions |
| Config |
| Caching |
| Metrics |
+----+------+
|
+----+------+
| Reporter |
| JSON |
| Markdown |
| SARIF |
| HTML |
| Graph |
+-----------+Orchestration Engine
Drives the 4-stage execution loop: Observe (collect context), Hypothesize (form hypotheses), Probe (execute tests), Verify (validate findings)
Multi-Agent Platform
10 specialized agents communicate through concurrent event and message buses; supports DAG-based workflows with state persistence, checkpoint, and resume
Reasoning Engine
Accepts goals, creates plans, generates AI prompts, validates responses, and reaches consensus across multiple AI calls; supports 18 goal types
Security Skills Framework
Registry of 41 skills; executor with policy, caching, and telemetry; independent skill installation and version management
Payload Intelligence
SQLite with FTS5; 5-level execution policy; 10 mutation families; feedback loop for payload effectiveness tracking; provenance tracking
Knowledge Graph
Entity-relationship store for findings, targets, and contextual data; supports cross-scan correlation and path analysis
AI Provider Layer
Provider abstraction with session management, caching (SHA256 + TTL + LRU), metrics, middleware, retry (exponential backoff), and circuit breaker
Reporter
Multi-format output with evidence collection, attack graphs, and evidence packages
Security Capabilities
Comprehensive coverage across web, API, cloud, authentication, and network security domains.
Web Security
API Security
Cloud Security
Authentication
Network Security
Reconnaissance
Security Skills Framework (41 Skills)
Plugin-based skills covering web, API, cloud, network, and infrastructure security. Each skill carries MITRE ATT&CK, OWASP, CWE, and CAPEC metadata.
Web (16 skills)
API (5 skills)
Cloud (7 skills)
Network (5 skills)
Authentication (6 skills)
Utility (4 skills)
Multi-Agent Architecture
10 specialized agents coordinate through concurrent event and message buses, executing DAG-based workflows with state persistence, checkpoint, and resume capabilities.
Scan Agent
Executes target scanning and coordinates test execution
Analysis Agent
Analyzes raw findings and produces structured results
Risk Agent
Performs risk assessment and priority scoring
Exploit Agent
Verifies exploitability of identified vulnerabilities
Report Agent
Formats and assembles reports
Monitor Agent
Monitors scan progress, detects anomalies, manages lifecycle
Discover Agent
Performs reconnaissance and entry point discovery
Fingerprint Agent
Fingerprints technologies, WAFs, and services
Correlation Agent
Correlates findings across targets and vectors
Threat Agent
Maps findings to threat models and attack chains
Reasoning Engine — 18 Goal Types
Accepts goals, creates plans, generates AI prompts, validates responses, and reaches consensus across multiple AI calls.
AI Provider Abstraction
OpenAI
Models: GPT-4, GPT-4o, GPT-4o-mini, GPT-3.5-turbo
Full support with streaming, function calling, system prompts
Ollama
Models: llama3.2, mixtral, gemma2, phi3, qwen2.5, codegemma, nomic-embed-text, + any local model
Bring your own model, no API key needed, local inference
Reporting & Evidence
JSON
Programmatic consumption, CI/CD integration
Full structured data with all fields
Markdown
Quick human review, documentation
Summary, findings list with severity, recommendations
SARIF 2.1
IDE integration (VS Code, GitHub CodeQL)
SARIF-compliant with rules, results, locations, code flows
HTML
Interactive review, stakeholder presentation
Standalone HTML with navigation, filtering, search
Attack Graph (HTML)
Visual analysis of attack paths
HTML with embedded Graphviz, interactive graph
Purple Team Rules
Detection rule generation
YARA/Sigma-compatible detection rules
ZIP Evidence
Evidence package for audit or legal
Raw requests/responses, metadata, configuration
Safety Policy Levels
Safe
Read-only testing; no modification payloads; no authentication bypass
Balanced
Limited probing; read-heavy with minimal write testing to non-production endpoints
Aggressive
Full testing including authentication bypass; no destructive payloads
Research
Experimental payloads enabled; sandboxed execution recommended
Paranoid
Minimal probing; extensive pre-scan verification; conservative timing
Installation
From Source
# Clone the repository
git clone https://github.com/nullc0d30/HunterX.git
cd HunterX
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Run the post-install setup
python setup.py
# Verify installation
python hunterx.py --helpDocker
# Pull the latest image
docker pull nullc0d30/hunterx:latest
# Run a basic scan
docker run --rm -v $(pwd)/reports:/data nullc0d30/hunterx:latest \
-u http://target.com -o /data
# Run with AI analysis
docker run --rm \
-v $(pwd)/reports:/data \
-e OPENAI_API_KEY=sk-... \
nullc0d30/hunterx:latest \
-u http://target.com --ai --ai-model gpt-4 -o /data
# API mode with persistent reports
docker run --rm -p 8443:8443 -v $(pwd)/reports:/data \
nullc0d30/hunterx:latest api --port 8443CLI Reference
| Argument | Description | Default |
|---|---|---|
| -u, --url | Target URL | Required |
| -f, --targets-file | Multi-target file (one URL per line) | None |
| -p, --payload-dir | Payload directory path | payloads/ |
| -o, --output-dir | Reports output directory | reports/ |
| -c, --config | YAML configuration file | hunterx.yaml |
| --profile | Operator profile: internal, bounty, gov | bounty |
| --preset | Scan preset: quick, full, stealth | full |
| --stealth | Stealth level: low, medium, high | low |
| --threads | Concurrent thread count | 5 |
| --timeout | Request timeout in seconds | 30 |
| --retries | Request retry count | 3 |
| --max-depth | Maximum crawl depth | 3 |
| --dry-run | Logic verification only (no requests sent) | false |
| --insecure | Disable SSL certificate verification | false |
| --proxy | HTTP/HTTPS proxy URL | None |
| --ai | Enable AI-assisted analysis | false |
| --ai-model | AI model name | gpt-4 |
| --ai-provider | AI provider name | openai |
| --auth | Authentication mode | none |
REST API Reference
FastAPI server with 40+ endpoints organized into functional groups.
| Method | Path | Description |
|---|---|---|
| POST | /scan | Start an asynchronous scan job |
| GET | /scan/{id} | Poll scan status and results |
| DELETE | /scan/{id} | Cancel a running scan |
| GET | /scans | List all scan jobs (with filtering and pagination) |
| GET | /ai/providers | List configured AI providers |
| POST | /ai/chat | Send a chat completion request |
| GET | /agents | List registered agents |
| POST | /goals | Create a new reasoning goal |
| GET | /skills | List all registered security skills |
| GET | /skills/search | Search skills by name, category, or MITRE technique |
| POST | /payload/mutate | Mutate a payload using specified techniques |
| GET | /health | System health check |
| GET | /version | Get platform version |
Project Roadmap
Short-Term (v6.x)
- Community Skill Repository — Public registry for community-contributed skills with versioning and dependency management
- Additional AI Providers — Anthropic Claude, Google Gemini, AWS Bedrock, local transformers models
- Provider Failover — Automatic failover between providers with health checking
- A/B Model Comparison — Compare results from different AI providers on the same goal
Medium-Term (v7.x)
- CI/CD Pipeline Plugins — Native GitHub Actions, GitLab CI, Jenkins, Azure DevOps integrations
- SIEM Connectors — Splunk, Elasticsearch, QRadar, Sentinel output connectors
- Ticketing Integration — Jira, ServiceNow, PagerDuty finding submission
- Collaborative Scanning — Multi-user scan coordination with shared state
Long-Term
- Public Skill Marketplace — Verified and community skills with ratings, reviews, and analytics
- Community Detection Rules — User-contributed WAF and detection rules
- Interactive Tutorials — In-app guided tutorials for new users
- Video Walkthroughs — Official video guides for common workflows
- Enterprise Features — Role-based access control, audit logging, compliance reporting, SSO
Citation
If you use HunterX in academic research, please cite:
@software{HunterX,
author = {Ahmed Awad},
title = {HunterX: AI-Assisted Vulnerability Hunter},
year = {2026},
version = {6.0.0},
license = {Apache-2.0},
doi = {10.6084/m9.figshare.33102290},
url = {https://github.com/nullc0d30/HunterX}
}