PentestAgent is a terminal application for black-box security testing — bug bounty, red-team, and penetration-testing work — in which an LLM agent drives real tooling against a target you specify. It runs as a text UI with four modes: /assist for a single instruction with tool execution, /agent for autonomous execution of one task, /crew for a multi-agent run where an orchestrator spawns specialised workers, and /interact for a guided conversation during an assessment.
Tools run either on the host or inside a Docker container, and prebuilt images ship with pentesting utilities — a base image with nmap, netcat, and curl, and a Kali image adding Metasploit, sqlmap, and hydra — which the agent invokes through its terminal tool. Built-in tools cover a terminal, a browser, notes, and web search; prebuilt attack playbooks define structured approaches for specific assessments and run from the command line against a target.
The agent can build its own hierarchy without external orchestration. The spawnmcpagent tool starts a child copy of the agent as a subordinate Model Context Protocol (MCP) server over stdio, isolated with its own runtime, model client, conversation history, and notes; the child's tools are injected into the parent on the next call, so a parent can delegate scoped subtasks and collect results asynchronously. The same spawning is available manually from the UI through /spawn and /despawn.
MCP works in both directions: PentestAgent consumes external MCP servers configured in mcp_servers.json, and can itself run as an MCP server over stdio or SSE so external clients submit tasks, poll status, inspect results, manage tools, read logs, and control the agent remotely. When a connected server exposes more than 128 tools, the full catalogue is replaced with a single RAG optimizer tool that retrieves the most relevant tools per query using embedding similarity, keeping the context window bounded.
Findings persist across sessions: agents write notes categorised as credential, vulnerability, finding, or artifact and re-inject them into context, methodologies and CVE material placed in a knowledge directory are retrieved for context injection, and in crew mode the orchestrator builds a knowledge graph from notes to derive strategic insights. Conversations auto-save after each task, with rewind and fork controls to truncate or branch a thread, and a browser for restoring past sessions. Any model reachable through LiteLLM works, including OpenAI-compatible and Anthropic-compatible relay endpoints.
Features
- Four operating modes: single-shot assist, autonomous agent, multi-agent crew, and guided interactive chat
- Docker runtime: run tools in a container, with base and Kali images carrying nmap, Metasploit, sqlmap, hydra, and more
- Attack playbooks: prebuilt structured assessments launched against a target from the command line
- Agent self-spawning: spawnmcpagent starts isolated child agents whose tools are injected back into the parent
- Manual child control: /spawn and /despawn create and terminate child agents from the interface, each with its own panel
- MCP client and server: consumes external MCP servers and exposes itself over stdio or SSE with task, memory, and observability tools
- RAG tool optimizer: servers exposing more than 128 tools are replaced by a retrieval tool that surfaces the relevant subset per query
- Knowledge and notes: methodology and CVE sources for retrieval, plus categorised findings that persist across sessions
- Shadow graph: crew-mode orchestrator builds a knowledge graph from notes for strategic insights
- Conversation controls: auto-saved sessions with rewind, fork, and a restore browser
- Model flexibility: any LiteLLM-supported model, with custom API bases for OpenAI- or Anthropic-compatible endpoints
- Scope controls: target and in-scope CIDRs passed per run and per spawned child
