Repository: GreyDGL/PentestGPT

Stars: 12619

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PentestGPT is an AI-powered autonomous penetration testing agent with a terminal user interface (TUI). It uses an agentic pipeline to solve CTF challenges, Hack The Box machines, and authorized security assessments.

Published at USENIX Security 2024: Paper

Stack: Python 3.12+, uv, Docker (Ubuntu 24.04), Textual (TUI), Rich (CLI), Agent SDK

Common Commands

bash

Development

uv sync                           # Install dependencies
uv run pentestgpt --target X      # Run locally
Testing

make test                         # Run all tests
make test-cov                     # Run tests with coverage
uv run pytest tests/test_controller.py -v  # Run single test file
Code Quality

make lint                         # Run ruff linter
make format                       # Format code with ruff
make typecheck                    # Run mypy type checking
make check                        # All checks (lint + typecheck)
Docker Workflow

make install                      # Build Docker image
make connect                      # Connect to container (main usage)
make stop                         # Stop container
make clean-docker                 # Remove everything including config

Architecture

Entry Point

- pentestgpt/interface/main.py - CLI entry, argument parsing, mode selection
- Command: pentestgpt --target <IP/URL> [--instruction "hint"] [--non-interactive] [--raw] [--debug]

Core Layer (`pentestgpt/core/`)

- agent.py - PentestAgent: Wraps the LLM agent, handles flag detection, logs to /workspace/pentestgpt-debug.log
- backend.py - AgentBackend interface + ClaudeCodeBackend implementation (framework-agnostic design)
- controller.py - AgentController: 5-state lifecycle (IDLE->RUNNING->PAUSED->COMPLETED->ERROR), pause/resume at message boundaries
- events.py - EventBus: Singleton pub/sub for TUI-agent decoupling (STATE_CHANGED, MESSAGE, TOOL, FLAG_FOUND events)
- session.py - SessionStore: File-based persistence in ~/.pentestgpt/sessions/, supports session resumption
- config.py - Pydantic settings with .env file support

Interface Layer (`pentestgpt/interface/`)

- tui.py - Textual TUI app with real-time activity feed, F1 help, Ctrl+P pause, Ctrl+Q quit
- components/ - ActivityFeed, SplashScreen, tool-specific Renderers

System Prompts (`pentestgpt/prompts/`)

- pentesting.py - CTF_SYSTEM_PROMPT: CTF methodology, flag formats, persistence directives

Key Patterns

- Event-Driven: TUI subscribes to EventBus; agent emits events for state changes, messages, flags
- Singletons: EventBus.get(), get_global_tracer() for global access
- Abstract Backend: AgentBackend interface allows swapping LLM backends
- Flag Detection: Regex patterns in agent.py match flag{}, HTB{}, CTF{}, 32-char hex

Testing

Tests use pytest with pytest-asyncio. Mock backends for unit tests.

bash

uv run pytest tests/ -v                           # All tests
uv run pytest tests/test_controller.py -v         # Single file
uv run pytest tests/test_controller.py::test_name # Single test

Docker Notes

- Non-root user: pentester with sudo
- Workdir: /workspace (mounted from ./workspace)
- LLM config persisted in claude-config volume
- Pre-installed: nmap, netcat, curl, wget, git, ripgrep, tmux

Legacy Version

The previous multi-LLM version (v0.15) is archived in legacy/. It supports:
- OpenAI (GPT-4o, o3, o4-mini)
- Google Gemini
- Deepseek
- Ollama (local LLMs)
- GPT4All

To develop on the legacy version:

bash

cd legacy
pip install -e .

Benchmark System

Use the standalone benchmark runner at benchmark/standalone-xbow-benchmark-runner/:

bash

cd benchmark/standalone-xbow-benchmark-runner

python3 run_benchmarks.py --range 1-10 --pattern-flag # Run benchmarks 1-10 python3 run_benchmarks.py --all --pattern-flag # Run all 104 benchmarks python3 run_benchmarks.py --retry-failed # Retry failed benchmarks python3 run_benchmarks.py --dry-run --range 1-5 # Preview without executing

See benchmark/standalone-xbow-benchmark-runner/README.md for full documentation.

Repository Structure

text

.
├── pentestgpt/           # Main package (agentic version)
│   ├── core/             # Agent, controller, events, session
│   ├── interface/        # TUI and CLI
│   ├── prompts/          # System prompts
│   ├── benchmark/        # Benchmark runner module
│   └── tools/            # Tool framework
├── benchmark/            # Benchmark suites
│   ├── xbow-validation-benchmarks/  # 104 XBOW benchmarks
│   └── standalone-xbow-benchmark-runner/  # Benchmark runner
├── tests/                # Test suite
├── workspace/            # Runtime workspace (Docker mount)
├── legacy/               # Archived v0.15 (multi-LLM)
├── Dockerfile            # Ubuntu 24.04 container
├── docker-compose.yml    # Container orchestration
└── Makefile              # Development commands

Modification Requirements

When modifying code, ensure:
- Adherence to existing architecture and patterns
- Comprehensive tests for new features
- Ensure to run tests after changes, and do further updates to ensure code quality. Always keep the documentation up to date with any architectural changes. Also ensure all tests pass after modifications.

README.md

<a name="readme-top"></a>

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![Discord][discord-shield]][discord-url]

<br />
<div align="center">

<h3 align="center">PentestGPT</h3>

<p align="center">
AI-Powered Autonomous Penetration Testing Agent
<br />
<strong>Published at USENIX Security 2024</strong>
<br />
<br />
<a href="https://pentestgpt.com"><strong>Official Website: pentestgpt.com »</strong></a>
<br />
<br />
<a href="https://www.usenix.org/conference/usenixsecurity24/presentation/deng">Research Paper</a>
·
<a href="https://github.com/GreyDGL/PentestGPT/issues">Report Bug</a>
·
<a href="https://github.com/GreyDGL/PentestGPT/issues">Request Feature</a>
</p>
</div>

<a href="https://trendshift.io/repositories/3770" target="_blank"><img src="https://trendshift.io/api/badge/repositories/3770" alt="GreyDGL%2FPentestGPT | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

---

Demo

Installation

![Installation Demo](https://asciinema.org/a/761661)

Watch on YouTube

PentestGPT in Action

![PentestGPT Demo](https://asciinema.org/a/761663)

Watch on YouTube

---

What's New in v1.0 (Agentic Upgrade)

- Autonomous Agent - Agentic pipeline for intelligent, autonomous penetration testing
- Session Persistence - Save and resume penetration testing sessions
- Docker-First - Isolated, reproducible environment with security tools pre-installed

In Progress: Multi-model support for OpenAI, Gemini, and other LLM providers

---

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

- Docker (required) - Install Docker
- LLM Provider (choose one):
- Anthropic API Key from console.anthropic.com
- Claude OAuth Login (requires Claude subscription)
- OpenRouter for alternative models at openrouter.ai
- Tutorial: Using Local Models with Claude Code

Installation

bash

Clone and build

git clone --recurse-submodules https://github.com/GreyDGL/PentestGPT.git
cd PentestGPT
make install
Configure authentication (first time only)

make config
Connect to container

make connect

Note: The --recurse-submodules flag downloads the benchmark suite. If you already cloned without it, run: git submodule update --init --recursive

Try a Benchmark

bash

cd benchmark/standalone-xbow-benchmark-runner
python3 run_benchmarks.py --range 1-1 --pattern-flag

See Benchmark Documentation for detailed usage.

Commands Reference

| Command | Description |
|---------|-------------|
| make install | Build the Docker image |
| make config | Configure API key (first-time setup) |
| make connect | Connect to container (main entry point) |
| make stop | Stop container (config persists) |
| make clean-docker | Remove everything including config |

---

Usage

bash

Interactive TUI mode (default)

pentestgpt --target 10.10.11.234
Non-interactive mode

pentestgpt --target 10.10.11.100 --non-interactive
With challenge context

pentestgpt --target 10.10.11.50 --instruction "WordPress site, focus on plugin vulnerabilities"

Keyboard Shortcuts: F1 Help | Ctrl+P Pause/Resume | Ctrl+Q Quit

---

Using Local LLMs

PentestGPT supports routing requests to local LLM servers (LM Studio, Ollama, text-generation-webui, etc.) running on your host machine.

Prerequisites

- Local LLM server with an OpenAI-compatible API endpoint
- LM Studio: Enable server mode (default port 1234)
- Ollama: Run ollama serve (default port 11434)

Setup

bash

Configure PentestGPT for local LLM

make config
Select option 4: Local LLM
Start your local LLM server on the host machine

Then connect to the container

make connect

Customizing Models

Edit scripts/ccr-config-template.json to customize:

- localLLM.api_base_url: Your LLM server URL (default: host.docker.internal:1234)
- localLLM.models: Available model names on your server
- Router section: Which models handle which operations

| Route | Purpose | Default Model |
|-------|---------|---------------|
| default | General tasks | openai/gpt-oss-20b |
| background | Background operations | openai/gpt-oss-20b |
| think | Reasoning-heavy tasks | qwen/qwen3-coder-30b |
| longContext | Large context handling | qwen/qwen3-coder-30b |
| webSearch | Web search operations | openai/gpt-oss-20b |

Troubleshooting

- Connection refused: Ensure your LLM server is running and listening on the configured port
- Docker networking: Use host.docker.internal (not localhost) to access host services from Docker
- Check CCR logs: Inside the container, run cat /tmp/ccr.log

---

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

bash

Via command line flag

pentestgpt --target 10.10.11.234 --no-telemetry
Via environment variable

export LANGFUSE_ENABLED=false

---

Benchmarks

PentestGPT includes 104 XBOW validation benchmarks for comprehensive testing and evaluation.

bash

cd benchmark/standalone-xbow-benchmark-runner

Performance Highlights

PentestGPT achieved an 86.5% success rate (90/104 benchmarks) on the XBOW validation suite:

- Cost: Average $1.11, Median $0.42 per successful benchmark
- Time: Average 6.1 minutes, Median 3.3 minutes per successful benchmark
- Success rates by difficulty:
- Level 1: 91.1%
- Level 2: 74.5%
- Level 3: 62.5%

For detailed benchmark results, analysis, and automated testing instructions, see the Benchmark Documentation.

---

Legacy Version

The previous multi-LLM version (v0.15) supporting OpenAI, Gemini, Deepseek, and Ollama is archived in legacy/:

bash

cd legacy && pip install -e . && pentestgpt --reasoning gpt-4o

---

Citation

If you use PentestGPT in your research, please cite our paper:

bibtex

@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

- Research supported by Quantstamp and NTU Singapore

[contributors-shield]: https://img.shields.io/github/contributors/GreyDGL/PentestGPT.svg?style=for-the-badge
[contributors-url]: https://github.com/GreyDGL/PentestGPT/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/GreyDGL/PentestGPT.svg?style=for-the-badge
[forks-url]: https://github.com/GreyDGL/PentestGPT/network/members
[stars-shield]: https://img.shields.io/github/stars/GreyDGL/PentestGPT.svg?style=for-the-badge
[stars-url]: https://github.com/GreyDGL/PentestGPT/stargazers
[issues-shield]: https://img.shields.io/github/issues/GreyDGL/PentestGPT.svg?style=for-the-badge
[issues-url]: https://github.com/GreyDGL/PentestGPT/issues
[license-shield]: https://img.shields.io/github/license/GreyDGL/PentestGPT.svg?style=for-the-badge
[license-url]: https://github.com/GreyDGL/PentestGPT/blob/master/LICENSE.md
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://www.linkedin.com/in/gelei-deng-225a10112/
[linkedin-url2]: https://www.linkedin.com/in/vmayoral/
[discord-shield]: https://dcbadge.vercel.app/api/server/eC34CEfEkK
[discord-url]: https://discord.gg/eC34CEfEkK

Repository: GreyDGL/PentestGPT

Stars: 12619

CLAUDE.md Copy Chapter

CLAUDE.md

Project Overview Copy Chapter

Common Commands Copy Chapter

Development

Testing

Code Quality

Docker Workflow

Architecture Copy Chapter

Entry Point Copy Section

Core Layer (pentestgpt/core/) pentestgpt/core/)')" title="Copy section prompt for LLMs"> Copy Section

Interface Layer (pentestgpt/interface/) pentestgpt/interface/)')" title="Copy section prompt for LLMs"> Copy Section

System Prompts (pentestgpt/prompts/) pentestgpt/prompts/)')" title="Copy section prompt for LLMs"> Copy Section

Key Patterns Copy Chapter

Testing Copy Chapter

Docker Notes Copy Chapter

Legacy Version Copy Chapter

Benchmark System Copy Chapter

Repository Structure Copy Chapter

Modification Requirements Copy Chapter

README.md Copy Chapter

Demo Copy Chapter

Installation Copy Section

PentestGPT in Action Copy Section

What's New in v1.0 (Agentic Upgrade) Copy Chapter

Features Copy Chapter

Quick Start Copy Chapter

Prerequisites Copy Section

Installation Copy Section

Clone and build

Configure authentication (first time only)

Connect to container

Try a Benchmark Copy Section

Commands Reference Copy Section

Usage Copy Chapter

Interactive TUI mode (default)

Non-interactive mode

With challenge context

Using Local LLMs Copy Chapter

Prerequisites Copy Section

Setup Copy Section

Configure PentestGPT for local LLM

Select option 4: Local LLM

Start your local LLM server on the host machine

Then connect to the container

Customizing Models Copy Section

Troubleshooting Copy Section

Telemetry Copy Chapter

Opting Out Copy Section

Via command line flag

Via environment variable

Benchmarks Copy Chapter

Performance Highlights Copy Section

Legacy Version Copy Chapter

Citation Copy Chapter

License Copy Chapter

Acknowledgments Copy Chapter

Explore Related Technologies & Topics

CLAUDE.md

Project Overview

Common Commands

Architecture

Entry Point

Core Layer (`pentestgpt/core/`)

Interface Layer (`pentestgpt/interface/`)

System Prompts (`pentestgpt/prompts/`)

Key Patterns

Testing

Docker Notes

Legacy Version

Benchmark System

Repository Structure

Modification Requirements

README.md

Demo

Installation

PentestGPT in Action

What's New in v1.0 (Agentic Upgrade)

Features

Quick Start

Prerequisites

Installation

Try a Benchmark

Commands Reference

Usage

Using Local LLMs

Prerequisites

Setup

Customizing Models

Troubleshooting

Telemetry

Opting Out

Benchmarks

Performance Highlights

Legacy Version

Citation

License

Acknowledgments