Demo
Installation
Watch on YouTube
PentestGPT in Action
Watch on YouTube
What's New in v1.0 (Agentic Upgrade)
- Multi-Stage Pipeline - The agent works through staged phases (recon → exploit → walkthrough for CTF; asset discovery → vulnerability identification → report for pentests), feeding each stage's findings into the next.
- Autonomous Agent - Drives Claude Code or Codex to run tools and reason without human intervention.
- Session Persistence - Save and resume penetration testing sessions.
The autonomous CTF pipeline is backend-pluggable for Claude Code and Codex. The interactive
modernized legacy mode (pentestgpt-legacy) supports a wider provider set: OpenAI, Anthropic,
Google Gemini, DeepSeek, xAI, Qwen, Moonshot, and local Ollama. See
Interactive Multi-LLM Mode.
Features
- AI-Powered Challenge Solver - Leverages LLM advanced reasoning to perform penetration testing and CTFs
- Live Walkthrough - Tracks steps in real-time as the agent works through challenges
- Multi-Category Support - Web, Crypto, Reversing, Forensics, PWN, Privilege Escalation
- Real-Time Feedback - Watch the AI work with live activity updates
- Extensible Architecture - Clean, modular design ready for future enhancements
Quick Start
Prerequisites
- Python 3.12+
- uv - Python package manager
- Claude Code CLI (
claude) - installed and authenticated for local Claude runs. See Claude Code docs
- Codex CLI (
codex) - installed and authenticated for local Codex runs. The Docker flow below bundles both CLIs.
Installation
git clone https://github.com/GreyDGL/PentestGPT.git
cd PentestGPT
make install # runs uv sync
Commands Reference
| Command |
Description |
make install |
Install dependencies |
make test |
Run all tests |
make check |
Run lint + typecheck |
make build |
Build distributable package |
Usage
# Run against a target (CTF mode by default)
pentestgpt --target 10.10.11.234
# With challenge context
pentestgpt --target 10.10.11.50 --instruction "WordPress site, focus on plugin vulnerabilities"
# Penetration-test mode (asset discovery → vulnerabilities → report)
pentestgpt --target 10.10.11.234 --mode pentest
# List previously saved sessions
pentestgpt --list-sessions
The agent works through a multi-stage pipeline, feeding each stage's findings into the next — recon → exploit → walkthrough for CTF, asset discovery → vulnerability identification → report for pentest.
Run in Docker (install once, log in once)
A self-contained image bundles the tool + the Claude Code and Codex CLIs. You log in once and
the sessions persist in named volumes — no re-login on later runs.
make docker-build # build the tool image
make docker-login # ONE-TIME, idempotent: checks logins, logs in only what's missing
make docker-auth-status # check both are logged in (ROUNDTRIP=1 for a live 1-token check)
# Run the pipeline against a target (any backend / model / mode):
make docker-run TARGET=http://127.0.0.1:8000 BACKEND=codex MODEL=gpt-5.5 MODE=ctf
make docker-run TARGET=10.10.11.234 BACKEND=claude MODEL=opus MODE=pentest
make docker-login logs in Claude (setup-token → token stored in the volume) and Codex (its
own in-container codex login, OAuth callback forwarded via socat — not seeded, since ChatGPT refresh
tokens are single-use). It is idempotent: re-running skips whatever is still valid. Logins persist across
container recreation; make docker-down keeps them, make docker-nuke removes the login volumes (to
force a fresh login / rotate a token). Design + details: docs/docker-dev-plan.md.
Interactive Multi-LLM Mode (modernized legacy)
The classic, human-in-the-loop PentestGPT from the USENIX 2024 paper is preserved and
modernized as pentestgpt-legacy. It runs three cooperating LLM sessions —
reasoning / generation / parsing — that maintain a Pentesting Task Tree (PTT) while you
drive the session interactively (next, more, todo, discuss). The autonomous fixed-stage
pipeline supports Claude and Codex backends; this legacy mode talks natively to many providers
via their official SDKs.
Set an API key for any provider you want to use (in your environment or .env — see
.env.example). Only the providers you configure are enabled.
OPENAI_API_KEY=... ANTHROPIC_API_KEY=... GEMINI_API_KEY=... # or GOOGLE_API_KEY
DEEPSEEK_API_KEY=... GROK_API_KEY=... QWEN_API_KEY=... KIMI_API_KEY=...
Run
# Auto-pick the best available models for each session
pentestgpt-legacy
# Choose models per session
pentestgpt-legacy --reasoning-model claude-opus-4-8 --parsing-model gemini-3.5-flash
# Local model via Ollama (OpenAI-compatible)
pentestgpt-legacy --reasoning-model ollama:qwen3 --base-url http://localhost:11434/v1
# List every supported model (shows which providers are configured)
pentestgpt-legacy --list-models
# Live round-trip every configured model and print a pass/fail matrix
pentestgpt-legacy --smoke-test
Supported models (web-verified June 2026)
pentestgpt-legacy --list-models always renders the live registry. Re-run --smoke-test
after model IDs change. Current snapshot:
| Provider |
Current models |
Legacy (kept) |
Env key |
| OpenAI |
gpt-5.5, gpt-5.5-pro, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5.3-codex |
gpt-4o, gpt-4o-mini, o3, o4-mini |
OPENAI_API_KEY |
| Anthropic |
claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5-20251001 |
— |
ANTHROPIC_API_KEY |
| Google Gemini |
gemini-3.1-pro, gemini-3.5-flash, gemini-3-pro, gemini-3.1-flash-lite |
gemini-2.5-pro, gemini-2.5-flash |
GEMINI_API_KEY / GOOGLE_API_KEY |
| DeepSeek |
deepseek-v4-flash, deepseek-v4-pro |
deepseek-chat, deepseek-reasoner |
DEEPSEEK_API_KEY |
| xAI Grok |
grok-4.3 |
— |
GROK_API_KEY / XAI_API_KEY |
| Alibaba Qwen |
qwen3.7-max, qwen3.5-flash |
qwen3-max |
QWEN_API_KEY / DASHSCOPE_API_KEY |
| Moonshot Kimi |
kimi-k2.6 |
— |
KIMI_API_KEY (.cn default; set MOONSHOT_BASE_URL for .ai) |
| Local (Ollama) |
ollama:<model> (e.g. ollama:qwen3) |
— |
none (OLLAMA_BASE_URL) |
The registry lives in pentestgpt_legacy/llm/registry.py (the single source of truth).
Adding a model is one ModelSpec entry; OpenAI-compatible providers reuse one connector.
Telemetry
PentestGPT collects anonymous usage data to help improve the tool. This data is sent to our Langfuse project and includes:
- Session metadata (target type, duration, completion status)
- Tool execution patterns (which tools are used, not the actual commands)
- Flag detection events (that a flag was found, not the flag content)
No sensitive data is collected - command outputs, credentials, or actual flag values are never transmitted.
Opting Out
# Via command line flag
pentestgpt --target 10.10.11.234 --no-telemetry
# Via environment variable
export LANGFUSE_ENABLED=false
Benchmark history
PentestGPT achieved an 86.5% success rate (90/104 benchmarks) on an XBOW validation-suite
experiment in December 2025. That number is a historical research result, not a current
pentestgpt-agent regression guarantee.
XBOW harnesses and result archives are maintained outside this product repository as reference-only
research artifacts. The supported PentestGPT CLI, Makefile, CI, and Docker runtime do not expose an
XBOW runner. A future evaluation may reuse that corpus through a separately owned adapter without
making it a product dependency.
Citation
If you use PentestGPT in your research, please cite our paper:
@inproceedings{299699,
author = {Gelei Deng and Yi Liu and Víctor Mayoral-Vilches and Peng Liu and Yuekang Li and Yuan Xu and Tianwei Zhang and Yang Liu and Martin Pinzger and Stefan Rass},
title = {{PentestGPT}: Evaluating and Harnessing Large Language Models for Automated Penetration Testing},
booktitle = {33rd USENIX Security Symposium (USENIX Security 24)},
year = {2024},
isbn = {978-1-939133-44-1},
address = {Philadelphia, PA},
pages = {847--864},
url = {https://www.usenix.org/conference/usenixsecurity24/presentation/deng},
publisher = {USENIX Association},
month = aug
}
License
Distributed under the MIT License. See LICENSE.md for more information.
Disclaimer: This tool is for educational purposes and authorized security testing only. The authors do not condone any illegal use. Use at your own risk.
Acknowledgments
(back to top)
PentestGPT 是一个智能体框架，它利用大语言模型自动执行渗透测试并解决 CTF 挑战，按侦察、利用、报告等分阶段流程推进工作。