PentestAgent

AI Penetration Testing

ghostcrew_demo.mp4

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.

Run

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)

# 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	(default)	Chat with the agent. You control the flow.
Agent	/agent <task>	Autonomous execution of a single task.
Crew	/crew <task>	Multi-agent mode. Orchestrator spawns specialized workers.

TUI Commands

/agent <task>    Run autonomous agent on task
/crew <task>     Run multi-agent crew on task
/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
/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

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

Add external tools via MCP servers in pentestagent/mcp/mcp_servers.json:

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

CLI Tool Management

pentestagent tools list         # List all tools
pentestagent tools info <name>  # Show tool details
pentestagent mcp list           # List MCP servers
pentestagent mcp add <name> <command> [args...]  # Add MCP server
pentestagent mcp test <name>    # 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

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