PentestAgent Logo # PentestAgent ### AI Penetration Testing [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt) [![Version](https://img.shields.io/badge/Version-0.2.0-orange.svg)](https://github.com/GH05TCREW/pentestagent/releases) [![Security](https://img.shields.io/badge/Security-Penetration%20Testing-red.svg)](https://github.com/GH05TCREW/pentestagent) [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://github.com/GH05TCREW/pentestagent)
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975 ## Requirements - Python 3.10+ - API key for OpenAI, Anthropic, or other LiteLLM-supported provider ## Install ```bash # Clone git clone https://github.com/GH05TCREW/pentestagent.git cd pentestagent # Setup (creates venv, installs deps) .\scripts\setup.ps1 # Windows ./scripts/setup.sh # Linux/macOS # Or manual python -m venv venv .\venv\Scripts\Activate.ps1 # Windows source venv/bin/activate # Linux/macOS pip install -e ".[all]" playwright install chromium # Required for browser tool ``` ## Configure Create `.env` in the project root: ``` ANTHROPIC_API_KEY=sk-ant-... PENTESTAGENT_MODEL=claude-sonnet-4-20250514 ``` Or for OpenAI: ``` OPENAI_API_KEY=sk-... PENTESTAGENT_MODEL=gpt-5 ``` Any [LiteLLM-supported model](https://docs.litellm.ai/docs/providers) works. ## Run ```bash pentestagent # Launch TUI pentestagent -t 192.168.1.1 # Launch with target pentestagent --docker # Run tools in Docker container ``` ## Docker Run tools inside a Docker container for isolation and pre-installed pentesting tools. ### Option 1: Pull pre-built image (fastest) ```bash # Base image with nmap, netcat, curl docker run -it --rm \ -e ANTHROPIC_API_KEY=your-key \ -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \ ghcr.io/gh05tcrew/pentestagent:latest # Kali image with metasploit, sqlmap, hydra, etc. docker run -it --rm \ -e ANTHROPIC_API_KEY=your-key \ ghcr.io/gh05tcrew/pentestagent:kali ``` ### Option 2: Build locally ```bash # Build docker compose build # Run docker compose run --rm pentestagent # Or with Kali docker compose --profile kali build docker compose --profile kali run --rm pentestagent-kali ``` The container runs PentestAgent with access to Linux pentesting tools. The agent can use `nmap`, `msfconsole`, `sqlmap`, etc. directly via the terminal tool. Requires Docker to be installed and running. ## Modes PentestAgent has three modes, accessible via commands in the TUI: | Mode | Command | Description | |------|---------|-------------| | Assist | (default) | Chat with the agent. You control the flow. | | Agent | `/agent ` | Autonomous execution of a single task. | | Crew | `/crew ` | Multi-agent mode. Orchestrator spawns specialized workers. | ### TUI Commands ``` /agent Run autonomous agent on task /crew Run multi-agent crew on task /target Set target /tools List available tools /notes Show saved notes /report Generate report from session /memory Show token/memory usage /prompt Show system prompt /mcp Visualizes or adds a new MCP server. /clear Clear chat and history /quit Exit (also /exit, /q) /help Show help (also /h, /?) ``` Press `Esc` to stop a running agent. `Ctrl+Q` to quit. ## Playbooks PentestAgent includes prebuilt **attack playbooks** for black-box security testing. Playbooks define a structured approach to specific security assessments. **Run a playbook:** ```bash pentestagent run -t example.com --playbook thp3_web ``` ![Playbook Demo](assets/playbook.gif) ## Tools PentestAgent includes built-in tools and supports MCP (Model Context Protocol) for extensibility. **Built-in tools:** `terminal`, `browser`, `notes`, `web_search` (requires `TAVILY_API_KEY`) ### MCP Integration PentestAgent supports MCP (Model Context Protocol) servers. Configure `mcp_servers.json` for any MCP servers they intend to use. Example config (place under `mcp_servers.json`): ```json { "mcpServers": { "nmap": { "command": "npx", "args": ["-y", "gc-nmap-mcp"], "env": { "NMAP_PATH": "/usr/bin/nmap" } } } } ``` ### CLI Tool Management ```bash pentestagent tools list # List all tools pentestagent tools info # Show tool details pentestagent mcp list # List MCP servers pentestagent mcp add [args...] # Add MCP server pentestagent mcp test # Test MCP connection ``` ## Knowledge - **RAG:** Place methodologies, CVEs, or wordlists in `pentestagent/knowledge/sources/` for automatic context injection. - **Notes:** Agents save findings to `loot/notes.json` with categories (`credential`, `vulnerability`, `finding`, `artifact`). Notes persist across sessions and are injected into agent context. - **Shadow Graph:** In Crew mode, the orchestrator builds a knowledge graph from notes to derive strategic insights (e.g., "We have credentials for host X"). ## Project Structure ``` pentestagent/ agents/ # Agent implementations config/ # Settings and constants interface/ # TUI and CLI knowledge/ # RAG system and shadow graph llm/ # LiteLLM wrapper mcp/ # MCP client and server configs playbooks/ # Attack playbooks runtime/ # Execution environment tools/ # Built-in tools ``` ## Development ```bash pip install -e ".[dev]" pytest # Run tests pytest --cov=pentestagent # With coverage black pentestagent # Format ruff check pentestagent # Lint ``` ## Legal Only use against systems you have explicit authorization to test. Unauthorized access is illegal. ## License MIT