PentestAgent
An executable AI framework for authorized black-box penetration testing workflows.
What does this agent do, and when should you use it?
PentestAgent is a Python AI-agent framework for black-box security testing across bug bounty, red-team, and penetration-testing workflows. It offers a terminal UI and CLI with Assist, Agent, Crew, and Interact modes. The agent can use built-in terminal, browser, notes, web search, and self-spawning MCP-agent tools, while also consuming external MCP servers. It combines persisted conversations and findings with optional RAG knowledge sources, and Crew mode builds a Shadow Graph from notes. It can run locally or inside Docker images with penetration-testing tools, and can expose its own MCP server over stdio or SSE.
A user sets a target through pentestagent -t <target> or /target <host>, then submits work with /assist <task>, /agent <task>, /crew <task>, or /interact <task>. The agent can invoke the built-in terminal, browser, and notes tools, plus web_search when TAVILY_API_KEY is configured; in Docker it can directly use Linux tools including nmap, msfconsole, and sqlmap. pentestagent run -t example.com --playbook thp3_web runs a bundled attack playbook. Findings are stored in loot/notes.json, conversations are stored as JSON, and files placed in pentestagent/knowledge/sources/ can be injected through RAG. In MCP server mode it exposes tools including run_task, run_task_async, get_task_result, list_tools, and store_memory; spawn_mcp_agent can create isolated child agents and add their tools back to the parent agent.
- A bug-bounty researcher with authorization wants a structured black-box web assessment using the `thp3_web` playbook.
- A red-team operator needs to delegate port scanning and service enumeration for separate network ranges to child agents and collect results asynchronously.
- A penetration-testing consultant wants to work in the Kali Docker image with preinstalled tools such as Metasploit, sqlmap, and Hydra.
- A security team using Claude Desktop or Cursor wants to submit tasks to PentestAgent through its stdio MCP server.
- A tester needs findings, notes, and conversation history retained so an earlier assessment can be restored or forked.
What are this agent's strengths and limitations?
- It offers a TUI, CLI, Docker execution, and an MCP server, covering both interactive and programmatic use.
- Crew mode and `spawn_mcp_agent` support hierarchical delegation to child agents with isolated runtime, conversation history, and notes storage.
- For an MCP server with more than 128 tools, the built-in RAG optimizer retrieves relevant tools by embedding similarity to keep the working context manageable.
- Automatic conversation saves, persistent `loot/notes.json` findings, and the Crew-mode Shadow Graph preserve and connect assessment context.
- It requires a compatible provider API key and model configuration; the repository does not state model pricing or quotas.
- The browser tool requires a separate Playwright Chromium installation, and `web_search` requires its own `TAVILY_API_KEY`.
- Docker is required when using the isolated runtime and preinstalled penetration-testing tools, and Docker must already be installed and running.
- The project explicitly limits use to systems with authorization; unauthorized access may be illegal.
How do you install or deploy this agent?
Requires Python 3.10+ and an API key for OpenAI, Anthropic, or another LiteLLM-supported provider. Run git clone https://github.com/GH05TCREW/pentestagent.git, then cd pentestagent, followed by ./scripts/setup.sh on Linux/macOS or ./scripts/setup.ps1 on Windows. Alternatively, create and activate a virtual environment, run pip install -e ".[all]", then run playwright install chromium. Create .env in the project root, for example OPENAI_API_KEY=sk-... and PENTESTAGENT_MODEL=gpt-5; Anthropic configuration uses ANTHROPIC_API_KEY and an appropriate model name.
How do you use this agent?
For a first interactive run, execute pentestagent -t 192.168.1.1, then enter /agent <task> for an autonomous task or /interact <task> for guided work. To run a playbook, use pentestagent run -t example.com --playbook thp3_web. For container isolation, use pentestagent tui --docker, or run docker run -it --rm -e ANTHROPIC_API_KEY=your-key -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 ghcr.io/gh05tcrew/pentestagent:latest. To expose it to an MCP client, run pentestagent mcp_server --type stdio; for SSE, use pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080.