nullc0d30/hunterx repository overview

⁠HunterX v7 — AI-Assisted Vulnerability Discovery, Validation & Proof Engine

HunterX is an open-source, AI-assisted vulnerability discovery, validation and proof engine for authorized security testing. It does not stop at candidate detections: it plans and orchestrates missions, reasons over hypotheses, validates findings with evidence, engineers and replays proofs and PoCs, and produces report-ready output.

This image runs the HunterX v7.0.0 CLI (and REST API) inside a minimal, non-root container.

Discover → Fingerprint → Reason → Hypothesize → Probe → Verify → Prove → PoC → Replay → Correlate → Report

⁠Quick Start

# Pull the current release
docker pull nullc0d30/hunterx:7.0.0

# Verify the version you pulled
docker run --rm nullc0d30/hunterx:7.0.0 version

# Show the command reference
docker run --rm nullc0d30/hunterx:7.0.0 help

The image entrypoint is the hunterx CLI, which uses subcommands (for example hunterx version, hunterx help, hunterx hunt ...). Running the container with no arguments prints the usage text.

⁠What Is HunterX?

HunterX is an AI-assisted vulnerability discovery, validation and proof engine and red-team framework. It orchestrates the open-source security-tool ecosystem rather than replacing it: HunterX executes tools with structured contracts, normalizes their output, correlates results, reasons over hypotheses, validates with evidence, engineers and replays minimal safe proofs/PoCs, and produces professional reports.

A traditional scanner stops at "possible SQL injection". HunterX is built to investigate the hypothesis, verify the behavior, prove the finding, reproduce the evidence, assess the impact, and turn the result into a report-ready, validated finding:

Detection → Evidence → Verification → Reproduction → PoC → Validated Finding

⁠Key Capabilities

• Autonomous mission orchestration and adaptive mission planning (hunterx mission, hunterx hunt)
• AI-assisted reasoning through a decoupled AI provider layer — grounded in evidence, never a substitute for it
• Toolchain intelligence layer with 92 registered open-source security tools, machine-readable contracts, structured execution, parsers and normalizers
• Evidence-driven vulnerability validation with proof contracts, replay and reproducibility
• Proof / PoC engineering with minimal safe proofs and evidence-gated confidence and impact
• Target memory and campaign intelligence, including cloud/SaaS attack-surface intelligence and knowledge-graph correlation
• Professional reporting: Markdown, HTML, JSON, SARIF 2.1, PDF and evidence packages
• Persistent mission state (SQLite by default) with the TIDB persistence layer
• REST API (FastAPI) with opt-in API-key authentication
• Clean Architecture Python core, Apache-2.0 licensed

⁠Image Tags

⁠Usage

⁠Verify the installed version

docker run --rm nullc0d30/hunterx:7.0.0 version
# HunterX v7.0.0

⁠CLI

# Show the resolved configuration
docker run --rm nullc0d30/hunterx:latest config

# Show platform composition
docker run --rm nullc0d30/hunterx:latest platform

# List the integrated toolchain
docker run --rm nullc0d30/hunterx:latest tools list

# Start a full-spectrum mission against an authorized target
# (requires a target you own or are explicitly authorized to test)
docker run --rm nullc0d30/hunterx:latest hunt full_security_assessment https://YOUR-AUTHORIZED-TARGET

Missions, findings, reports and target memory persist to the configured database (SQLite by default), so chained invocations such as hunterx mission create ... → hunterx mission start <mission_id> work across container runs when the same database volume is mounted.

⁠REST API

The image ships the FastAPI application. Start it 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

curl http://localhost:8080/health
# {"status":"ok"}

API-key authentication is opt-in. When enabled, every request (except /health) requires a valid X-API-Key header:

docker run -d --name hunterx-api -p 8080:8080 \
  -e HUNTERX_API_AUTH_ENABLED=true \
  -e HUNTERX_API_KEY=YOUR_ADMIN_KEY \
  --entrypoint uvicorn nullc0d30/hunterx:latest \
  --factory hunterx.api.app:create_app --host 0.0.0.0 --port 8080

⁠Persistent data

HunterX persists mission state to the database. The image stores it in the application data directory (/opt/hunterx/data, image default sqlite:////opt/hunterx/data/hunterx.db). Mount a volume there:

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

The container runs as the non-root hunterx user and /opt/hunterx/data is writable by it.

⁠Interactive shell

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

⁠Docker Compose

The repository ships a docker-compose.yml with two services:

docker compose up -d hunterx-api          # API service (port 8080)
docker compose run --rm hunterx help      # CLI service

⁠Configuration

Configuration is resolved in this order (each level overrides the previous):

1. Built-in defaults and the bundled hunterx.yaml profile
2. A user profile file — HUNTERX_CONFIG environment variable, or hunterx.yaml in the working directory (/app)
3. HUNTERX_* environment variables

⁠Environment variables

⁠AI provider configuration (optional)

AI is optional: with no provider configured HunterX runs on a safe NullAIClient fallback. Provider and model are selected independently; each provider uses its own key variable:

Each provider resolves its own API endpoint (for example openai → api.openai.com, deepseek → api.deepseek.com, openrouter → openrouter.ai); HunterX never silently reroutes one provider to another and never rewrites the configured model. Missing credentials, invalid keys, invalid models, rate limits and provider outages are reported truthfully. Every provider route is implemented and unit-tested; live completion requires your own credential for the selected provider.

Example:

docker run --rm \
  -e HUNTERX_AI_PROVIDER=openai \
  -e HUNTERX_AI_MODEL=gpt-4o-mini \
  -e HUNTERX_AI_OPENAI_KEY=YOUR_API_KEY \
  nullc0d30/hunterx:7.0.0 config

Example:

docker run --rm \
  -e HUNTERX_LOG_LEVEL=DEBUG \
  -e HUNTERX_DATABASE_URL=sqlite:////opt/hunterx/data/hunterx.db \
  nullc0d30/hunterx:7.0.0 config

⁠Docker Security

• The container runs as the non-root hunterx user (UID 999) and exposes a single writable volume at /opt/hunterx/data for persistent state.
• The image is multi-stage, based on python:3.11-slim, and publishes OCI labels (source, license, version) for supply-chain inspection.
• Use pinned image tags (nullc0d30/hunterx:7.0.0) for reproducible deployments.
• Protect API credentials: enable HUNTERX_API_AUTH_ENABLED, use a strong HUNTERX_API_KEY, and do not expose the API port beyond your trusted network.
• Review anything you mount into the container — mounted host paths are visible to the container process.
• HunterX executes security tooling that can generate active traffic. Only run it against systems you own or are explicitly authorized to test.

⁠Responsible Use

HunterX is intended exclusively for authorized security testing: penetration testing, in-scope bug bounty programs, red-team operations, defensive security research, and laboratory environments. You are responsible for obtaining written authorization before testing any system and for complying with all applicable laws and terms of service. HunterX is licensed under Apache 2.0 and provided "AS IS" without warranty.

See Responsible Use⁠ and the Security Policy⁠.

⁠Troubleshooting

⁠Documentation & Resources

• Repository: github.com/nullc0d30/HunterX⁠
• Documentation: nullc0d30.github.io/HunterX⁠
• Quickstart: Quickstart⁠
• Installation: Installation⁠
• CLI Reference: CLI Reference⁠
• Configuration: Configuration⁠
• Architecture: Architecture⁠
• PoC & Validation: PoC & Validation⁠
• Tool Ecosystem: Tool Ecosystem⁠
• What's New in v7: v7 Release⁠
• FAQ: FAQ⁠
• Changelog: Changelog⁠
• Security: Security Policy⁠
• Responsible Use: Responsible Use⁠
• Report issues: GitHub Issues⁠
• AI Configuration: AI Configuration⁠

⁠Support HunterX

If HunterX is useful to your authorized security work, consider supporting its continued development:

GitHub Sponsors⁠ —

HunterX is created and maintained by Ahmed Awad (NullC0d3)⁠, released under the Apache License 2.0.