AutoPwn

Agentic binary exploitation framework built around an LLM-driven ReAct loop, MCP tool servers, and pwntools execution.

AutoPwn analyzes ELF binaries, chooses exploitation strategies based on mitigations, and iterates toward working exploits with built-in dynamic-analysis and exploit-generation tools.

Features

• ReAct-style exploitation loop with tool use (checksec, symbols, gadgets, GDB, exploit execution)
• MCP-backed tool servers for:
  • static/recon helpers (ELF symbols, strings, libc offsets, payload builders)
  • dynamic debugging helpers (GDB breakpoint/run/stack/vmmap)
• Exploit runner with machine-readable success signals (shell_detected, flag_detected)
• Prompt + knowledge-base driven strategy guidance
• Test suite with challenge fixtures for ret2win/ret2libc/format/shellcode workflows

Project Layout

• agent/ - ReAct loop, prompts, planner, CLI entrypoint
• agent/mcp_servers/ - packaged MCP tool server implementations
• tests/ - unit/integration tests + challenge binaries/sources
• exploits/ - generated solve scripts and latest attempt mirrors

Requirements

• Python 3.11+
• gdb available for dynamic-analysis tools
• optional: pwntools extras for exploit workflows
• optional: Ghidra + a JDK for the ghidra_decompile tool (set GHIDRA_HOME / PWN_GHIDRA_HOME; put java on PATH or set JAVA_HOME / PWN_JAVA_HOME)

Installation

git clone https://github.com/colinthebomb1/AutoPwn.git
cd AutoPwn
python -m venv .venv
source .venv/bin/activate
pip install .

Configuration

Copy .env.example to .env and set at least:

• ANTHROPIC_API_KEY (required)

Optional knobs:

• MODEL_NAME (default: claude-sonnet-4-6; use a dated model ID if you need to pin a snapshot)
• PWN_AGENT_MAX_ITERATIONS (default: 30)
• PWN_AGENT_CONTEXT_TURNS
• PWN_AGENT_TOOL_RESULT_MAX
• PWN_AGENT_RUN_EXPLOIT_SCRIPT_SNIP
• PWN_AGENT_MAX_OUTPUT_TOKENS
• PWN_AGENT_BOOTSTRAP_GHIDRA (default: 1) — run headless Ghidra once at startup; set 0 to skip
• PWN_AGENT_BOOTSTRAP_MAX_CHARS_WITH_GHIDRA — larger bootstrap JSON cap when decompilation succeeds (default 12000)
• JAVA_HOME or PWN_JAVA_HOME — if java is not on your PATH (common in some venvs/IDE launches), point at a JDK so Ghidra can start
• PWN_AGENT_USER_CONTEXT_MAX — max length for --notes / --notes-file text sent to the model (default 12000)

Quick Start

Run against a local challenge binary:

autopwn tests/challenges/ret2win_x64

Override model / iteration budget:

autopwn tests/challenges/ret2libc_real_x64 -m claude-sonnet-4-6 -n 20

Preview prompt/playbook selection without calling the model:

autopwn tests/challenges/heap_poison_null_byte_x64 --prompt-report

Use remote target:

autopwn ./chall -r host:port

Add CTF or author context (description, constraints, suspected bug class, solve sketch):

autopwn ./chall --notes "Heap UAF + FSOP; libc 2.39, Full RELRO"

Long writeups:

autopwn ./chall --notes-file ./challenge.txt

(--notes-file overrides --notes if both are passed.)

Testing

Run all tests:

pytest -q

In constrained environments where PTYs are limited, skip dynamic GDB tests:

pytest -q --ignore=tests/test_mcp_dynamic.py

Notes

• Latest attempted exploit is mirrored to exploits/last_attempt_<binary>.py.
• Successful solves save to exploits/solve_<binary>.py.
• The framework is intended for CTF/research and controlled targets you are authorized to test.

License

MIT