PentestAgent
An executable AI framework for authorized black-box penetration testing workflows.
- Source repo
- GH05TCREW/pentestagent
- Stars
- ★ 3.2k
- Last updated
- 11d ago
- License
- MIT
- Primary language
- Python
- FA score
- 50/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A bug-bounty researcher with authorization wants a structured black-box web assessment using the
thp3_webplaybook. - Not a fit if
- Users without explicit authorization to test a target; unauthorized access is prohibited
- Users unwilling to install extra dependencies such as Docker or Playwright Chromium
- Source review
- 50/100 · Major gaps
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_webplaybook. - 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.
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.
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_agentsupport 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.jsonfindings, 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_searchrequires its ownTAVILY_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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| PentestAgent This agent | 50 · Major gaps | CLIFree + model costs | ★ 3.2k | 11d ago | Python | OpenAI API · Claude API |
| PentesterFlow | 73 · Some gaps | CLIFree + model costs | ★ 1.4k | 2mo ago | TypeScript | OpenAI API |
| PentestCode | 55 · Major gaps | CLIFree + model costs | ★ 928 | 1d ago | TypeScript | OpenAI API · Claude API |
| DarkMoon Autonomous Pentesting | 48 · Major gaps | CLIFree + model costs | ★ 1.2k | 9d ago | Python | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: Tool list includes terminal, browser, etc., but no explicit least-privilege design; user confirmation mechanisms exist (e.g., Esc to stop, /clear), but not all dangerous operations require confirmation; data flow transparency partial, with conversation history and tool call logs, but data flow not explicit; sensitive data handling has notes categories, but no encryption or redaction; dependency security has version ranges, but no vulnerability scanning or locking; external effects have Docker isolation option, but default local execution; rollback has rewind/fork, but only for conversation history; source attribution has author info, but publisher unverified. Deductions: lack of explicit permission controls, data protection, dependency audit details.
Evidence: README and pyproject.toml consistent, version numbers match; dependencies have version ranges, but not pinned; failure messages partial, with some tool error handling, but not comprehensive. Deductions: dependencies not pinned, failure handling incomplete.
Evidence: Audience is security testers, scenarios clear; capability boundaries have scope parameters and tool lists; trigger precision has commands and tool descriptions; environment fit has Docker and local execution. Deductions: boundary limits and failure scenarios not explicit.
Evidence: Information architecture clear, with project structure; install notes detailed; naming stable; examples and FAQ present; known limitations not explicit; MIT license; version 0.2.0 but no changelog; maintenance responsibility has author but not explicit. Deductions: missing known limitations and changelog.
Evidence: Output has report generation and notes; marginal value has automation; cost-benefit has Docker images but not evaluated. Deductions: cost-benefit not quantified.
Evidence: README has feature descriptions, but no evidence provided; cross-source verification limited; facts and inferences not clearly separated. Deductions: lack of verifiable evidence.
- Publisher identity unverified, use with caution.
- Dependencies not pinned, supply chain risk.
- Default local execution may impact system, recommend Docker isolation.
- Sensitive data handling lacks explicit encryption or redaction.
FAQ
Which model providers are supported?
PENTESTAGENT_MODEL.Can tools run in an isolated environment?
pentestagent tui --docker uses DockerRuntime, and the project documents both a base image and a Kali-based image.Can another client call the agent programmatically?
pentestagent mcp_server supports stdio and SSE, exposing task, configuration, memory, log, and tool-management operations.How is testing scope controlled?
--scope or a scope CIDR list when starting an MCP server or child agent.