[opensourcedex]

pentestagent is a free, open source ai interaction & interfaces project written in Python and released under MIT. It has 3,083 GitHub stars, 613 forks and 30 open issues, and was last pushed 11 days ago. On this registry it ranks #54 of 76 tracked projects in AI Interaction & Interfaces, with 5 head-to-head comparisons available. It gained 6 stars over the last 3 tracked days.

What is pentestagent?

What it is

PentestAgent is Python-based AI agent framework for black-box security testing. Project lives in AI & Machine Learning / AI Interaction & Interfaces ecosystem. It supports bug bounty, red-team, and penetration testing workflows. It provides terminal user interface, Docker tool execution, multi-agent orchestration, and model access through OpenAI, Anthropic, or other LiteLLM-supported providers.

Problem solved: black-box testing often needs repeated reconnaissance, tool invocation, note tracking, and report assembly. PentestAgent frames those steps as agent modes. Operators can target IP or scope, list tools, save notes, generate report, and use prebuilt attack playbooks. It can run Linux pentesting tools inside Docker, reducing host dependency.

Key capabilities

  • TUI runs pentestagent, pentestagent -t 192.168.1.1, and pentestagent tui --docker.
  • Model config uses .env keys like ANTHROPIC_API_KEY, OPENAI_API_KEY, PENTESTAGENT_MODEL, plus OPENAI_API_BASE or ANTHROPIC_API_BASE for relays.
  • Docker image ghcr.io/gh05tcrew/pentestagent:latest provides nmap, netcat, curl; ghcr.io/gh05tcrew/pentestagent:kali provides metasploit, sqlmap, hydra, and terminal tool access.
  • Modes include /assist, /agent, /crew, and /interact; /crew uses orchestrator spawning specialized workers.
  • Commands cover /target, /tools, /notes, /report, /memory, /prompt, /conversations, /mcp, /spawn, /despawn, /clear, /quit, and /help.
  • MCP support appears through /mcp for visualization or adding server, and /spawn for child MCP agent with target, scope, model, RAG, and MCP flags.
  • Prebuilt attack playbooks define structured black-box testing approach.

Who uses it and how

  • Bug bounty testers can set target, run /agent or /crew on task, inspect tools, save notes, and generate report from session.
  • Red-team operators can use Kali Docker profile for metasploit, sqlmap, hydra, and msfconsole through terminal tool.
  • Security teams can use Docker isolation for host protection while agent invokes nmap, msfconsole, sqlmap directly.
  • Automation users can integrate MCP servers and spawn child agents for scoped targets.
  • Web testers can install Chromium through Playwright for browser tool.

Getting started

Clone repository, run ./scripts/setup.sh or .\scripts\setup.ps1, then pip install -e ".[all]" and playwright install chromium. Create .env with provider key and model, then run pentestagent or Docker image ghcr.io/gh05tcrew/pentestagent:latest.

When to use it — and when not to

Use PentestAgent when black-box testing needs LLM-driven tool execution, Docker isolation, MCP extensibility, and session notes/reporting. It replaces manual terminal workflows, not full managed security testing. Self-hosters must operate Python 3.10+, provider API keys, Docker for container tools, and Chromium for browser tool. Facts show open issues 30, contributors absent, repo age 1 year, and README truncated around playbooks, so maturity and playbook detail need review.

project readme (upstream, from github) — read inline

PentestAgent

AI Penetration Testing

GH05TCREW%2Fpentestagent | Trendshift

Python License Version Security MCP

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

# 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 works.

Using a relay / custom API base

Point PentestAgent at any OpenAI-compatible endpoint via OPENAI_API_BASE:

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

For Anthropic-compatible endpoints use ANTHROPIC_API_BASE instead. See .env.example for full provider notes and embedding options.

Run

pentestagent                      # Launch TUI
pentestagent -t 192.168.1.1       # Launch with target
pentestagent tui --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)

# 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

# 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 /assist One single-shot instruction, with tool execution
Agent /agent Autonomous execution of a single task
Crew /crew Multi-agent mode. Orchestrator spawns specialized workers
Interact /interact Interactive mode. Chat with the agent, it will help you and guide during the pentesting procedure

TUI Commands

/assist <task>    One single-shot instruction.
/agent <task>     Run autonomous agent on task
/crew <task>      Run multi-agent crew on task
/interact <task>  Chat with the agent in guided mode
/target <host>    Set target
/tools            List available tools
/notes            Show saved notes
/report           Generate report from session
/memory           Show token/memory usage
/prompt           Show system prompt
/conversations    Browse and restore saved conversations
/mcp <list/add>   Visualizes or adds a new MCP server.
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
                  Manually spawn a child MCP agent from the TUI.
/despawn <server_name>
                  Terminate and remove a previously spawned child agent.
/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:

pentestagent run -t example.com --playbook thp3_web

Playbook Demo

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), spawn_mcp_agent

Agent Self-Spawning (spawn_mcp_agent)

spawn_mcp_agent is a built-in tool that allows a running agent to spawn a child copy of itself as a subordinate MCP server connected over stdio. The child process is fully isolated — its own runtime, LLM client, conversation history, and notes store — and its complete tool set is injected back into the parent agent's available tools after spawning.

This enables hierarchical, multi-agent workflows without any external orchestration: the agent self-organises by delegating scoped subtasks to children it spawns on demand.

Argument Type Default Description
target string — Pentest target to pass to the child
scope string[] — In-scope targets/CIDRs for the child
model string env var Model identifier, overrides PENTESTAGENT_MODEL on the child
no_rag boolean false Skip RAG engine initialisation on the child
no_mcp boolean true Skip external MCP server connections on the child (recommended)

After spawn_mcp_agent returns, the child's tools (run_task, run_task_async, await_tasks, etc.) are available on the next tool call. The child's server name is assigned automatically (e.g. child_agent_1) and returned in the result.

Example — orchestrator delegating parallel recon to two children:

# Turn 1: spawn two isolated child agents
spawn_mcp_agent  target="10.0.1.0/24"  scope=["10.0.1.0/24"]
spawn_mcp_agent  target="10.0.2.0/24"  scope=["10.0.2.0/24"]

# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Turn 3: wait and collect
child_agent_1__await_tasks  task_ids=["<id1>"]  timeout_seconds=600
child_agent_2__await_tasks  task_ids=["<id2>"]  timeout_seconds=600
child_agent_1__get_task_result  task_id="<id1>"
child_agent_2__get_task_result  task_id="<id2>"

Manual Child Agent Control (/spawn and /despawn)

Beyond the automatic spawn_mcp_agent tool, the TUI exposes two commands that let you spawn and terminate child agents manually, independently of a running agent loop.

/spawn
/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

Spawns a new child MCP agent over stdio and attaches it to the current session. The child appears as a collapsible terminal panel in the TUI sidebar and its tools become available to the parent agent on the next tool call.

Argument Description
target Pentest target to pass to the child (positional or --target)
--scope CIDR One or more in-scope CIDRs (repeatable)
--model MODEL Override the model for the child agent
--no-rag Skip RAG engine initialisation on the child
--no-mcp Skip external MCP server connections on the child

Examples:

/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag
/despawn
/despawn <server_name>

Terminates the child agent identified by server_name (e.g. child_agent_1), removes its terminal panel from the TUI, and disconnects its tools from the parent session. Use /mcp list to see the names of all currently active child agents.

Example:

/despawn child_agent_1

MCP RAG Tool Optimizer

When an MCP server exposes more than 128 tools, PentestAgent automatically replaces the full catalogu

readme truncated — read the full docs on github

Frequently asked questions

Is pentestagent free to use?

pentestagent is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does pentestagent do?

PentestAgent is an AI agent framework for black-box security testing, supporting bug bounty, red-team, and penetration testing workflows.

What is pentestagent written in?

pentestagent is primarily written in Python. Its source is publicly available at https://github.com/GH05TCREW/pentestagent, and it has 3,083 GitHub stars.