HunterX

AI-Assisted Offensive Security Engine

Discover. Validate. Prove. Report.

HunterX is not merely a vulnerability scanner. It is an open-source, AI-assisted offensive security engine for planning and running authorized security-assessment missions. It combines reconnaissance, security-tool orchestration, AI-assisted reasoning, hypothesis-driven investigation, vulnerability validation, evidence collection, proof / PoC engineering, replay / reproducibility, correlation, impact assessment and professional reporting into a single workflow.

Less noise. More verified findings.

The core message. HunterX does not stop at finding a possible vulnerability. It is built to investigate the hypothesis, validate the behavior, prove the finding, reproduce the evidence, assess the impact, and turn the result into a report-ready security finding.

Vulnerability
+ Evidence
+ Reproducibility
+ Proof / PoC
+ Impact
================
Validated Finding

Responsible use. HunterX is an authorized cybersecurity testing and research platform. You are responsible for obtaining appropriate authorization before testing any system. The author is not responsible for misuse, unauthorized access, illegal activity, or damage caused by the software. See Responsible Use and SECURITY.md.

A Scanner Finds a Possibility. HunterX Builds the Case.

A traditional scanner reports a candidate and stops:

Traditional Scanner

"Possible SQL Injection"
          ↓
       Finding?

HunterX carries the candidate through the full investigation:

Candidate
   ↓
Affected Endpoint
   ↓
Parameter
   ↓
Observed Behavior
   ↓
Hypothesis
   ↓
Verification
   ↓
Evidence
   ↓
Minimal Reproducible PoC
   ↓
PoC Validation
   ↓
Impact
   ↓
Report-Ready Finding

"Possible SQL Injection" is only a hypothesis. HunterX is designed to investigate, validate, prove, reproduce, correlate and report it — not to surface it as a verdict. Every claim HunterX makes is backed by observations, evidence, validation, proof, replay records, impact and provenance. A finding is only REPORT_READY when the reportability contract is satisfied.

From Detection to Validated Finding

A vulnerability detection is not a validated finding. HunterX drives each candidate through a lifecycle:

DETECTED → SUSPECTED → VALIDATING → VALIDATED → PROVEN → CONFIRMED → REPORT_READY
                                            ↘ FALSE_POSITIVE
                                            ↘ INCONCLUSIVE

• DETECTED / SUSPECTED — a candidate from tool output or reasoning. Not yet validated.
• VALIDATING / VALIDATED — behavior is tested and compared against the hypothesis.
• PROVEN — requires a valid, reproducible proof.
• CONFIRMED — requires the vulnerability-specific proof contract to permit confirmation and the confidence requirements to be met.
• REPORT_READY — requires evidence, proof, a reproducible PoC, impact, confidence, scope, timestamp and provenance.
• FALSE_POSITIVE — requires evidence that the original hypothesis was incorrect.
• INCONCLUSIVE — the outcome could not be determined (target changed, preconditions changed, WAF behavior changed, network instability, failed tool run or insufficient evidence).

A PoC that fails is never automatically a false positive. The engine distinguishes FALSE_POSITIVE from INCONCLUSIVE deliberately.

How HunterX Works

HunterX orchestrates the complete assessment workflow rather than attempting to replace the security-tool ecosystem:

DISCOVER
    ↓
FINGERPRINT
    ↓
REASON
    ↓
HYPOTHESIZE
    ↓
PROBE
    ↓
VERIFY
    ↓
PROVE
    ↓
POC
    ↓
REPLAY
    ↓
CORRELATE
    ↓
REPORT

HunterX orchestrates open-source security tools: it executes them with structured contracts, parses and normalizes their output into canonical observations, correlates results, reasons over hypotheses, validates with evidence, engineers and replays proofs/PoCs, and produces reports. It is built to work with the ecosystem, not to own every security capability itself.

What HunterX Brings Together

HunterX v7.0.0 (2026-08-11) is the production-ready v7 release. It assembles these capability areas into one platform:

Intelligence

• Reconnaissance
• Asset discovery
• Fingerprinting
• Target intelligence
• Cloud / SaaS attack-surface intelligence

Reasoning

• AI-assisted reasoning
• Hypothesis generation
• Adaptive mission planning
• Attack-path analysis
• Explainable next-best-action selection

Validation

• Vulnerability validation
• Evidence collection
• Proof contracts
• PoC engineering
• Replay / reproducibility
• Impact assessment

Correlation

• Cross-tool correlation
• Knowledge graph
• Evidence chains
• Topology
• Mission history

Reporting

• Findings & evidence bundles
• Remediation & retesting
• Markdown · HTML · JSON · SARIF 2.1 · PDF · evidence packages

Platform capabilities — autonomous mission orchestration and adaptive planning (hunterx mission, hunterx hunt); a Tool Integration SDK and tool-intelligence platform with a 92-tool arsenal manifest; persistent target intelligence (TIDB) with Alembic migrations, events, audit and versioning; topology and a typed event bus; knowledge-graph correlation; the Vulnerability Proof & PoC Validation Engine; professional multi-format reporting; security hardening (scope and authorization guards, sandboxing, evidence-gated confidence, secret masking, hardened XML parsing); an idempotent install.sh installer, Docker image and PyPI packaging; CI/CD pipelines; and comprehensive v7 documentation.

The Proof Engine

HunterX treats proof as part of vulnerability validation. The proof engine transforms a validated hypothesis into a report-ready finding:

HYPOTHESIS
    ↓
PROOF CONTRACT
    ↓
REQUIRED EVIDENCE
    ↓
MINIMAL PROOF STRATEGY
    ↓
PROOF CONSTRUCTION
    ↓
SAFETY VALIDATION
    ↓
SCOPE VALIDATION
    ↓
EXECUTION
    ↓
REPLAY
    ↓
EVIDENCE EVALUATION
    ↓
IMPACT
    ↓
CONFIDENCE
    ↓
VALIDATED FINDING
    ↓
REPRODUCTION PACKAGE
    ↓
REPORT

Two distinctions are fundamental:

GENERATED ≠ VALIDATED
EXECUTED ≠ VALIDATED

Generating a PoC proves nothing. Executing it once proves nothing. A finding is only PROVEN / CONFIRMED / REPORT_READY when its evidence, proof and reproducibility requirements are actually satisfied.

• Proof contracts — every supported vulnerability class has a deterministic contract defining preconditions, allowed and forbidden actions, required evidence, expected behavior, replay and impact requirements. Classes include SQL/NoSQL injection, XSS, SSRF, path traversal/LFI, IDOR, authentication, authorization, SSTI, XXE, command-injection indicators, cloud exposure and UNKNOWN_BEHAVIOR.
• Minimal, safe proofs — PoCs are structured artifacts (request templates, differential tests, configuration snapshots), never arbitrary executable scripts. Inputs are bounded, forbidden markers are refused, secrets are redacted, and every PoC is immutable with lineage.
• Replay & reproducibility — proofs are replayed deterministically with a SUCCESS / FAILED / INCONCLUSIVE / BLOCKED verdict. REPRODUCIBLE requires repeated successful replays — never a single run. A single "executed once" is never "reproducible".
• Evidence-driven impact & confidence — impact is classified strictly from captured evidence, never inferred merely from the vulnerability class. Confidence is a versioned, weighted policy over named factors — never a universal percentage. CONFIRMED can never be reached unless the proof contract permits confirmation.
• Novel / unknown behavior — unknown behaviors follow a hypothesis-driven loop (Unknown Behavior → Hypothesis → Experiment → Unexpected Result → New Hypothesis → Minimal Proof → Validated Finding) and remain candidates until sufficient evidence exists. HunterX supports hypothesis-driven investigation of unknown or application-specific behaviors; it does not claim guaranteed autonomous discovery of zero-days.
• RCE, responsibly — where applicable, proof emphasizes minimal-impact demonstration, evidence of execution and reproducibility — not destructive commands.

The engine is not a weaponization engine. Data destruction, persistence, credential dumping, reverse shells, lateral movement, DoS, mass data extraction and unrestricted database extraction are never scheduled. Proof means demonstrating the vulnerability with the minimum necessary interaction and impact.

What Can HunterX Investigate?

HunterX supports vulnerability discovery, validation and proof across a broad set of classes, as supported by its proof-contract registry:

Validation depth is defined per class by the proof-contract registry — not every class has identical validation depth, and HunterX never claims otherwise. See PoC & Validation for the full contract model.

Quick Start

INSTALL → HUNT → INSPECT → VALIDATE → REPORT

HunterX v7 organizes work as missions. Start with an authorized target:

# 1. INSTALL — Python 3.11+ on Linux, macOS or Windows
curl -sSL https://raw.githubusercontent.com/nullc0d30/HunterX/main/install.sh | sudo bash
# or from source:  git clone https://github.com/nullc0d30/HunterX.git && cd HunterX
#                  python -m pip install -e ".[api,db,dev]"

# 2. HUNT — plan and start a full-spectrum hunt mission
hunterx hunt full_security_assessment https://example.com

# 3. INSPECT — track the mission and inspect the toolchain
hunterx hunt status <mission_id>
hunterx hunt surface <mission_id>
hunterx tools list
hunterx tools capabilities
hunterx tools health

# 4. VALIDATE — work findings, PoCs and proof replay
hunterx finding list <mission_id>
hunterx finding poc <finding_id>       # PoC engineering
hunterx finding proof <finding_id>     # proof state
hunterx finding replay <finding_id>    # proof replay

# 5. REPORT — generate and export professional reports
hunterx report generate <finding_id>
hunterx report export <report_id> markdown

Verify your install:

hunterx version     # HunterX v7.0.0
hunterx help        # command list
hunterx platform    # platform composition
hunterx config      # resolved configuration

Missions persist to the configured database (SQLite by default), so hunterx mission create <objective> <target> followed by hunterx mission start <mission_id> works across CLI invocations.

See Quickstart and the full CLI Reference for complete usage.

Persistent Target Intelligence

HunterX does not treat every scan as an isolated command. It maintains structured target intelligence that persists and correlates across runs:

assets / targets → observations → findings → evidence
      ↘ history → relationships / topology → mission state
      ↘ cloud intelligence → correlation → tool results

• assets / targets — the surface under assessment
• observations — canonical normalized results from every tool run
• findings — validated results with evidence and proof
• evidence — provenance-backed evidence records
• history — target snapshots, diffs and change detection
• relationships / topology — how assets, services and cloud resources relate
• cloud intelligence — cloud/SaaS attack-surface intelligence
• correlation — cross-tool evidence chains
• mission state — checkpoint/resume and campaign state
• tool results — structured execution records

Cloud & SaaS Attack-Surface Intelligence

HunterX v7 includes evidence-backed Cloud & SaaS Attack-Surface Intelligence. Where supported, provider coverage includes AWS, Azure, GCP, OCI, Cloudflare, DigitalOcean, Akamai, Fastly, Vercel, Netlify, Heroku, Render, Fly.io, Supabase, Firebase, Kubernetes and Docker.

It provides provider detection, cloud resource intelligence, exposure classification, environment classification, topology, account/region/resource relationships, SaaS detection, cloud evidence and correlation — built from passive, static evidence (DNS, TLS, HTTP headers, HTML/JS, OpenAPI, documentation) for authorized targets. It never authenticates to cloud accounts, never accesses cloud resources and never retrieves secrets.

Knowledge Graph & Cross-Tool Correlation

HunterX correlates results across tools and missions into a knowledge graph of entities and relationships:

Assets
  ↕
Services
  ↕
Observations
  ↕
Findings
  ↕
Evidence
  ↕
Proofs
  ↕
Attack Paths

This enables cross-scan correlation, attack-path analysis and context-aware reasoning across missions.

From Finding to Professional Report

The workflow does not end at detection:

Finding
   ↓
Evidence
   ↓
Verification
   ↓
PoC
   ↓
Reproduction
   ↓
Impact
   ↓
Remediation
   ↓
Report

HunterX turns validated findings into structured, professional reports with verified export formats:

JSON  → machine-parsable
Markdown → human-readable
HTML  → visual dashboard
SARIF 2.1 → VS Code / GitHub CodeQL integration
PDF   → document export
Evidence Package → bundled evidence (ZIP)

Reports include finding, asset, endpoint, parameter, evidence, verification, PoC, reproduction, impact, confidence, relationships, risk/context, and remediation/recommendations where supported. Every statement traces to observation, evidence, validation, proof, impact, tool result, target intelligence or explicit analyst reasoning.

Installation

Requirements: Python 3.11+ on Linux, macOS or Windows.

# Installer script (Linux/macOS)
curl -sSL https://raw.githubusercontent.com/nullc0d30/HunterX/main/install.sh | sudo bash

# From PyPI
python -m pip install hunterxsec

# Or from source
git clone https://github.com/nullc0d30/HunterX.git
cd HunterX
python -m pip install -e ".[api,db,dev]"

Name note. The GitHub repository nullc0d30/HunterX is the canonical home of HunterX, created and maintained by Ahmed Awad (AKA NullC0d3). The HunterX v7 distribution is published to PyPI as hunterxsec; the plain hunterx name on PyPI belongs to a different, unrelated project. The import package and CLI command are hunterx either way.

Verify your install with hunterx version (see Quick Start).

See Installation for details, including database initialization (alembic upgrade head) and Docker.

CLI Reference

HunterX v7 ships a single hunterx command with capability groups:

See CLI Reference for the full command reference.

REST API

The v7 REST API is a FastAPI application (hunterx.api.app:create_app). Install from source with the api extra and run:

git clone https://github.com/nullc0d30/HunterX.git
cd HunterX
python -m pip install -e ".[api]"
uvicorn hunterx.api.app:create_app --host 127.0.0.1 --port 8080

API-key authentication is opt-in (admin/read-only roles). See Documentation Hub.

Docker

Official images are published on Docker Hub as nullc0d30/hunterx for Linux (amd64 / arm64). Tags follow the version (7, 7.0, 7.0.0) plus latest and stable.

🚀 1.7K+ Docker image pulls and counting.

Pull from Docker Hub

docker pull nullc0d30/hunterx:latest

Run the CLI

# Show the version
docker run --rm nullc0d30/hunterx:latest version

# Show help
docker run --rm nullc0d30/hunterx:latest help

# Interactive shell
docker run -it --rm --entrypoint sh nullc0d30/hunterx:latest

Run the REST API

The image ships with the api extras. Start the FastAPI server and point a browser at http://localhost:8080/health:

docker run -d --name hunterx-api -p 8080:8080 \
  --entrypoint uvicorn nullc0d30/hunterx:latest \
  --factory hunterx.api.app:create_app --host 0.0.0.0 --port 8080

Configuration is passed with HUNTERX_* environment variables (for example HUNTERX_API_PORT or HUNTERX_DATABASE_URL).

Docker Compose

docker-compose.yml ships a hunterx-api service (FastAPI) and a hunterx CLI service backed by the nullc0d30/hunterx:latest image:

docker compose up -d hunterx-api

The container runs as a non-root user, exposes 8080, and keeps persistent state under the named volume. See Release Guide for build and publishing details.

Tool Ecosystem

HunterX is designed to orchestrate the security tooling ecosystem rather than replace it.

HunterX integrates with, executes, parses, normalizes and correlates output from open-source security tools where the actual v7 implementation supports them. Integration status per tool is tracked in the toolchain manifest and on the Tool Ecosystem page. Status labels:

• Integrated (fully-supported) — structured execution, parser and normalizer.
• Integrated (partial-support) — parser/normalizer or adapter with documented limitations.
• Integrated (execution-only) — structured execution with a guarded adapter (never arbitrary subprocess).
• Planned / Resource — registered as a knowledge resource or known tool; not claimed as direct execution.

Categorized summary — 92 registered tools: recon & asset discovery (13), network & port scanning (7), HTTP, crawling & discovery (10), fuzzing & content discovery (5), parameter & endpoint discovery (6), vulnerability detection & validation (17), source, code & secret analysis (5), proxy & web security (2), exploitation & security research (3), knowledge & payload resources (3), cloud, container & supply chain (7), enterprise / Active Directory (9), and DNS, API & proof (5).

Recon / Asset Discovery

Network / Port Scanning

HTTP / Crawling / Discovery

Fuzzing / Content Discovery

Parameter / Endpoint Discovery

Vulnerability Detection / Validation

Source / Code / Secret Analysis

Proxy / Web Security

Exploitation / Security Research

Knowledge / Payload Resources

Cloud / Container / Supply Chain

Enterprise / Active Directory

DNS / API / Proof Ecosystem

Attribution. HunterX integrates with and leverages these third-party open-source projects. It does not claim ownership of them. Each tool keeps its own license and attribution; third-party attribution is preserved in THIRD_PARTY_NOTICES. Tool names and descriptions are used only to document interoperability.

Architecture

The v7 core is a Clean Architecture package under src/hunterx:

                    HUNTERX v7
                        │
        ┌───────────────┼───────────────┐
        │               │               │
     Missions        Reasoning       Toolchain
        │               │               │
        └───────────────┼───────────────┘
                        │
                  Core Platform
                        │
        ┌───────────────┼───────────────┐
        │               │               │
     Domain       Application     Infrastructure
        │               │               │
        └───────────────┼───────────────┘
                        │
                 Intelligence
                        │
        ┌───────────────┼───────────────┐
        │               │               │
      Evidence       Knowledge       Reporting

Package layers:

• domain — pure domain layer (entities, ports, services)
• application — use-case services
• infrastructure — adapters (db, cache, queue, secrets, sandbox)
• engines — engine facades (mission, workflow, planner, reasoning, correlation, risk, reporting)
• tools — tool adapters and the toolchain intelligence layer (SDK, intelligence, mastery)
• agents — multi-agent platform
• knowledge, reporting, config, cli, api — delivery layers

See Architecture, Foundation and Platform Composition Root.

Integrations

• Security tools — 92 registered tools across recon, scanning, crawling, fuzzing, parameters, validation, secrets, SAST, proxies, exploitation and knowledge resources (see the Tool Ecosystem section).
• AI providers — LLM-native reasoning through a decoupled AI provider layer.
• CI/CD — Docker images, SARIF export for GitHub CodeQL, REST API for pipeline integration.
• Persistence — SQL (SQLite default, PostgreSQL supported) via TIDB with Alembic migrations.

Engineering Status

At the v7.0.0 release (2026-08-11):

3,479 tests passed
8 skipped
2 deselected
0 failed

The suite spans unit, component, integration, golden, security, acceptance, performance, engineering, architecture and framework tests, plus the 92-tool toolchain contract suite. At release, the following quality gates were green: pytest, ruff, mypy (eng + shared), bandit (Medium+), vulture, architecture, docs, compliance, hygiene, dependency and lock-file consistency.

Disclaimer. These are engineering validation metrics — they document the state of the test suite and quality gates at release. They are not a guarantee of software quality, detection rates, or security assurance.

Local validation commands:

pytest -m "not tools"        # full default suite
ruff check src eng tests alembic
mypy eng src/hunterx/shared
python -m bandit -r src/hunterx
python -m eng.gates          # all quality gates

Target Users

Bug Bounty
→ Turn candidates into reproducible, report-ready findings with minimal PoCs.

Pentesting
→ Orchestrate structured assessments and produce evidence-backed reports.

Red Team
→ Plan missions, orchestrate toolchains, and correlate attack-surface intelligence.

Security Research
→ Investigate unknown and application-specific behavior with hypothesis-driven proof.

Application Security
→ Validate findings with PoC, impact and confidence instead of candidate noise.

DevSecOps / Security Engineering
→ Integrate reproducible results into CI/CD with SARIF and the REST API.

Documentation

• Documentation Hub
• Quickstart
• Installation
• Architecture
• PoC & Validation
• CLI Reference
• Tool Ecosystem
• Features
• Security
• Responsible Use

Contributing

Contributions are welcome. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and the Development Bible. Please report issues via GitHub Issues and ask questions in Discussions.

Responsible Use

HunterX is an authorized cybersecurity testing and research platform. It is designed to be used only against systems you own or are explicitly authorized to test. You are responsible for:

• Obtaining appropriate authorization (written permission) before testing any system.
• Complying with all applicable laws, regulations, and terms of service.
• Handling any data discovered during testing responsibly.

The engine never schedules data destruction, persistence, credential dumping, reverse shells, lateral movement, DoS, mass data extraction or unrestricted database extraction.

Disclaimer: The developer/author (Ahmed Awad / NullC0d3) is not responsible for misuse, unauthorized access, illegal activity, damage, or any other unethical use of the software. The software is provided "AS IS" without warranty of any kind. See Responsible Use.

License

Copyright (c) 2026 Ahmed Awad (AKA NullC0d3). All rights reserved.

Released under the Apache License, Version 2.0. See LICENSE and NOTICE. Third-party attribution is in THIRD_PARTY_NOTICES.

Author

HunterX is created and maintained by Ahmed Awad (AKA NullC0d3) — Cybersecurity Threat Intelligence Analyst, open-source developer, and security researcher.

• GitHub: nullc0d30
• Repository: nullc0d30/HunterX

Star / Follow / Contribute

If HunterX helps your authorized security work:

• Star the repository — nullc0d30/HunterX
• Try HunterX — follow the Quickstart
• Read the documentation — Documentation Hub
• Contribute — see CONTRIBUTING.md
• Report issues — GitHub Issues