greydgl--pentestgpt
gelei
abe3be01b4
Major rewrite of PentestGPT to use an agentic pipeline architecture: Core Changes: - New event-driven architecture with EventBus for TUI-agent decoupling - Implemented AgentController with 5-state lifecycle (IDLE->RUNNING->PAUSED->COMPLETED->ERROR) - Added AgentBackend interface with ClaudeCodeBackend implementation - Session management with file-based persistence for resumable pentests - Langfuse integration for observability and tracing Interface: - New Textual-based TUI with real-time activity feed - Keyboard shortcuts: F1 help, Ctrl+P pause, Ctrl+Q quit - Enhanced CLI with --target, --instruction, --non-interactive, --debug flags Project Structure: - Moved legacy multi-LLM version (v0.15) to legacy/ directory - New pentestgpt/core/ for agent, controller, events, session modules - New pentestgpt/interface/ for TUI and CLI components - New pentestgpt/benchmark/ for xbow benchmark integration - Comprehensive test suite in tests/ with unit and integration tests DevOps: - Docker support with Ubuntu 24.04 container - GitHub Actions CI/CD pipeline - Makefile with dev commands (test, lint, format, typecheck) - Added xbow-validation-benchmarks as submodule
275 行
8.9 KiB
Markdown
275 行
8.9 KiB
Markdown
<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
|
|
<a name="readme-top"></a>
|
|
|
|
<!-- PROJECT SHIELDS -->
|
|
[![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]
|
|
|
|
<!-- PROJECT LOGO -->
|
|
<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://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>
|
|
|
|
<!-- ABOUT THE PROJECT -->
|
|
<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>
|
|
|
|
> [!WARNING]
|
|
> **PentestGPT is a research prototype only**
|
|
>
|
|
> PentestGPT is a research prototype that pioneered the use of GenAI in cybersecurity. Please be aware of third-party services claiming to offer paid PentestGPT products - the original project is free and open-source.
|
|
|
|
---
|
|
|
|
## Demo
|
|
|
|
### Installation
|
|
[](https://asciinema.org/a/761661)
|
|
|
|
### PentestGPT in Action
|
|
[](https://asciinema.org/a/761663)
|
|
|
|
---
|
|
|
|
## 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](https://docs.docker.com/get-docker/)
|
|
- **Claude Model** (prioritized) - PentestGPT is optimized for Claude models via:
|
|
- Anthropic API Key from [console.anthropic.com](https://console.anthropic.com/)
|
|
- Claude OAuth Login (requires Claude subscription)
|
|
- OpenRouter for alternative models at [openrouter.ai](https://openrouter.ai/keys)
|
|
|
|
### 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
|
|
uv run pentestgpt-benchmark start XBEN-037-24
|
|
```
|
|
|
|
Then connect into the container and run:
|
|
|
|
```bash
|
|
pentestgpt --target http://host.docker.internal:8000
|
|
```
|
|
|
|
### 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
|
|
|
|
---
|
|
|
|
## Telemetry
|
|
|
|
PentestGPT collects anonymous usage data to help improve the tool. This data is sent to our [Langfuse](https://langfuse.com) 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 100+ vulnerability challenges for testing and development.
|
|
|
|
```bash
|
|
pentestgpt-benchmark list # List all benchmarks
|
|
pentestgpt-benchmark list --levels 1 # Filter by difficulty
|
|
pentestgpt-benchmark list --tags sqli # Filter by vulnerability type
|
|
pentestgpt-benchmark start XBEN-037-24 # Start a benchmark
|
|
pentestgpt-benchmark status # Check running benchmarks
|
|
pentestgpt-benchmark stop XBEN-037-24 # Stop a benchmark
|
|
```
|
|
|
|
**Available Tags:** `sqli`, `xss`, `idor`, `ssti`, `ssrf`, `lfi`, `rce`
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- **uv** (required) - Python package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
|
- **Claude Code CLI** - Configure with `claude login` or `export ANTHROPIC_API_KEY='your-key'`
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
uv sync # Install dependencies
|
|
uv run pentestgpt --target 10.10.11.234 # Run locally
|
|
```
|
|
|
|
### Project Commands
|
|
|
|
```bash
|
|
make test # Run pytest
|
|
make lint # Run ruff linter
|
|
make typecheck # Run mypy
|
|
make ci # Run full CI simulation (lint, format, typecheck, test, build)
|
|
make ci-quick # Quick CI without build step
|
|
```
|
|
|
|
---
|
|
|
|
## Legacy Version
|
|
|
|
The previous multi-LLM version (v0.15) supporting OpenAI, Gemini, Deepseek, and Ollama is archived in [`legacy/`](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.
|
|
|
|
---
|
|
|
|
## Contact
|
|
|
|
- **Gelei Deng** - [![LinkedIn][linkedin-shield]][linkedin-url] - gelei.deng@ntu.edu.sg
|
|
- **Yi Liu** - yi009@e.ntu.edu.sg
|
|
- **Yuekang Li** - yuekang.li@unsw.edu.au
|
|
- **Víctor Mayoral Vilches** - [![LinkedIn][linkedin-shield]][linkedin-url2] - v.mayoralv@gmail.com
|
|
- **Peng Liu** - liu_peng@i2r.a-star.edu.sg
|
|
|
|
---
|
|
|
|
## Acknowledgments
|
|
|
|
- Research supported by [Quantstamp](https://www.quantstamp.com/) and [NTU Singapore](https://www.ntu.edu.sg/)
|
|
|
|
<p align="right">(<a href="#readme-top">back to top</a>)</p>
|
|
|
|
<!-- MARKDOWN LINKS & IMAGES -->
|
|
[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
|