0xpwn

0xpwn

AI-powered penetration testing engine. Point it at a target and let a ReAct agent drive reconnaissance, scanning, and vulnerability discovery — all tools run inside a Docker sandbox so nothing touches the host.

Input: Target URL, hostname, IP, or CIDR via CLI Output: Structured findings with CVE enrichment, phase-by-phase execution logs

  CLI  ──▶  ReAct Agent  ──▶  Docker Sandbox  ──▶  Target
  (Typer)   (LLM-driven       (Kali + nmap,       (your scope)
             tool selection)    nuclei, ffuf,
                                httpx, subfinder)

---

Installation

Option 1: Install from PyPI (recommended)

pip install 0xpwn

Option 2: Install with pipx (isolated environment)

pipx install 0xpwn

Verify installation

0xpwn --help

---

Setup

1. Build the Sandbox Image

All scan tools run inside a Docker container based on Kali Linux:

docker build -t oxpwn-sandbox:dev docker/

2. Configure an LLM Provider

0xpwn uses LiteLLM — any supported provider works:

# Google Gemini
export GEMINI_API_KEY=your_key_here

# OpenAI
export OPENAI_API_KEY=your_key_here

# Anthropic
export ANTHROPIC_API_KEY=your_key_here

# Or use the generic key
export OXPWN_API_KEY=your_key_here

3. Run the Setup Wizard (optional)

0xpwn config wizard

Saves model and API key preferences to ~/.config/oxpwn/config.yaml.

---

Usage

Run a scan

# Basic scan with model specified
0xpwn scan --target example.com --model gemini/gemini-2.5-flash

# Use environment variable for model
export OXPWN_MODEL=gemini/gemini-2.5-flash
0xpwn scan --target 192.168.1.0/24

# Custom sandbox settings
0xpwn scan --target example.com \
  --model openai/gpt-4o \
  --sandbox-image oxpwn-sandbox:dev \
  --network-mode bridge \
  --max-iterations-per-phase 15

If no model is configured, the interactive wizard runs automatically.

Manage configuration

# Show current config
0xpwn config show

# Run setup wizard
0xpwn config wizard

# Reset configuration
0xpwn config reset

---

Available Tools

The ReAct agent selects tools autonomously based on the scan phase. All tools execute inside the Docker sandbox:

---

How It Works

0xpwn uses a ReAct (Reasoning + Acting) agent that plans and executes penetration testing in phases:

1. Reconnaissance — Subdomain enumeration, port scanning, service fingerprinting
2. Scanning — Vulnerability detection, web probing, directory fuzzing
3. Analysis — CVE enrichment via NVD, finding correlation, risk assessment

Each phase runs up to N iterations (default 10). The agent decides which tool to run, parses the output, and feeds results into the next decision. Findings are enriched with CVE data from the National Vulnerability Database.

---

Scan Options

---

Environment Variables

---

Architecture

src/oxpwn/
├── cli/                  # Typer CLI, Rich streaming output, setup wizard
├── agent/                # ReAct agent loop, tool dispatch, event system
├── llm/                  # LiteLLM client wrapper with error taxonomy
├── sandbox/              # Docker container lifecycle management
│   └── tools/            # Tool parsers (nmap, nuclei, httpx, ffuf, subfinder)
├── enrichment/           # NVD CVE lookup, caching, finding extraction
├── config/               # YAML config manager with env/CLI precedence
└── core/                 # Data models (ScanState, Finding, ToolResult)

docker/
└── Dockerfile            # Kali-based sandbox with pre-installed tools

Key design decisions:

• Docker isolation — all offensive tools run in a sandboxed container, never on the host
• LiteLLM abstraction — swap LLM providers without code changes
• Structured error taxonomy — every failure mode has a typed exception with actionable CLI output
• Phase-based execution — the agent progresses through recon → scanning → analysis with bounded iterations

---

Troubleshooting

---

Contributing

Build from source

git clone https://github.com/vahagn-madatyan/0xpwn.git
cd 0xpwn

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install with dev dependencies
pip install -e ".[dev]"

# Build the sandbox image
docker build -t oxpwn-sandbox:dev docker/

# Run from source
0xpwn --help

Run tests

# Unit tests only
pytest tests/unit/ -v --tb=short

# All tests (requires Docker + running services)
pytest tests/ -v

# Specific test file
pytest tests/unit/test_react_agent.py -v

Making a release

Releases are published to PyPI automatically via GitHub Actions when a version tag is pushed:

# Update version in pyproject.toml and src/oxpwn/__init__.py
# Commit the version bump
git tag v0.2.0
git push origin v0.2.0

The CI pipeline builds the distribution, runs tests, publishes to TestPyPI on every push, and publishes to PyPI on tags matching v*.

---

License

Apache License 2.0