An open-source, AI-driven penetration testing agent. Connects to a Kali attack box, runs tools autonomously, analyzes results, and iterates. You describe the target. It does the rest.
Built for real-world engagements, boot2root boxes, and CTFs.
Pentest Copilot performing an auth bypass in OWASP Juice Shop:
pentest-copilot-juice-box-demo.mp4
Watch it on YouTube
- Agentic execution - the AI runs commands directly on the attack box, reads output, decides next steps, and loops. Up to 25 iterations per turn, no manual nudging required.
- 16 agent tools - bash, Python scripts, tool installation, shell management, Google search, subagent spawning, Burp Suite (proxy history, Repeater, Intruder, Collaborator), and browser automation.
- 100+ capabilities - curated registry of security tools and Python packages across 7 categories (network, rev, pwn, crypto, forensics, stego, core). Select what you need, the agent installs the rest.
- Burp Suite integration - proxy history viewer, send requests to Repeater/Intruder, Collaborator for out-of-band testing. All accessible to the agent and through the UI.
- Browser agent - real browser automation via Magnitude. Test login flows, fill forms, interact with JavaScript-heavy apps. Optionally proxy traffic through Burp. In Docker mode, watch the browser via the built-in VNC stream; in developer mode, the browser opens on your local desktop.
- VPN management - upload
.ovpn/.confbundles with referenced certificates, keys, or credentials and connect/disconnect from the browser. Multiple simultaneous connections supported. - Subagent parallelism - spawn background agents to run tasks concurrently (e.g. directory brute-force + subdomain enum at the same time).
- Safety checks - dangerous commands (recursive deletes, device writes, fork bombs) require explicit approval, even in auto-run mode.
- Bring your own model - OpenAI, Anthropic (API key or OAuth), Google, Mistral, or any OpenAI-compatible endpoint.
- Use existing local subscriptions - Pentest Copilot can use an authenticated Codex CLI in Docker or host mode, and Claude Code in host/developer mode, as normal inference providers while retaining its own tool and consent loop.
git clone https://github.com/bugbasesecurity/pentest-copilot.git
cd pentest-copilot
./run.sh startOpen http://localhost:3000, register, and start a session.
run.sh waits for the frontend, backend, MongoDB, and Redis to be ready before
reporting success. If startup fails, it prints the affected container status and
recent logs. Configure and assign a model under Settings -> Models after the
first start.
On Windows, run Pentest Copilot inside WSL2 with Docker Desktop's WSL
integration enabled. Native PowerShell and Windows SSH work hosts are not
supported because workspace commands require a POSIX shell. For reliable file
permissions and performance, clone the repository into the WSL filesystem, not
under /mnt/c.
Settings -> Models detects authenticated Codex and Claude Code CLIs. Authenticate once on the machine that runs the CLI:
codex login
claude auth loginThen select Use Codex or Use Claude Code. The official CLI owns login, refresh, and subscription entitlement handling; Pentest Copilot does not copy or replay OAuth tokens. Subscription transports receive the same conversation history and function schemas as API providers and return the same assistant/tool call contract, so Pentest Copilot continues to execute tools and consent checks.
The Docker backend includes the Linux Codex CLI and mounts only the host's
file-based ~/.codex/auth.json, following Codex's documented headless/Docker
login transfer flow. Set CODEX_AUTH_FILE before docker compose up if your
credential file lives elsewhere. The CLI may refresh that file during normal
use; never commit or share it. Host Keychain-only credentials and Claude Code
remain available only in developer/host mode until a host inference bridge is
configured. Claude subscription use is local CLI control and must comply with
Anthropic's current third-party product and subscription terms.
Current first-class model families include GPT-5.6 Sol/Terra/Luna, Claude Fable/Opus/Sonnet 5, and Kimi K3 (direct Moonshot API or OpenRouter).
In Docker mode, Pentest Copilot mounts the host's ~/.ssh and ~/keys
directories read-only. Each workspace can select a concrete Host alias from
~/.ssh/config under Connection. Every session in that workspace uses the
same host and work folder without copying private keys into MongoDB. Set
HOST_SSH_DIR or HOST_SSH_KEYS_DIR before starting Docker when those
directories live elsewhere.
Use named aliases rather than wildcard-only entries:
Host lab-box
HostName 10.10.10.10
User root
IdentityFile ~/.ssh/lab-box.pemrun.sh handles config file generation, Docker builds, and container orchestration. Use ./run.sh start -q to reuse the previous launch mode and skip prompts on subsequent runs.
For the complete OS, Docker, SSH, VPN, proxy, permissions, recovery, and deployment scenario matrix, see Setup and Troubleshooting.
./run.sh stop # Stop all containers
./run.sh logs # Tail logs
./run.sh status # Container status
./run.sh backup # Back up databases, configuration, and workspaces
./run.sh config # Update configuration
./run.sh dev # Developer mode (infra only, run frontend/backend locally)
./run.sh help # Full helpPentest Copilot can expose its local control plane over MCP for clients such as Claude Code or Codex. Open Settings -> MCP Access to copy the local MCP endpoint and bearer token.
Treat the token as local admin access: it can run commands on the configured exploit box, operate Burp, browser automation, and VPN flows, read artifacts, write findings, and update local Pentest Copilot configuration. MCP actions tied to an engagement are recorded in that session so they remain visible in the Pentest Copilot UI.
After copying the endpoint and token, you can smoke test the MCP connection:
cd backend
PENTEST_COPILOT_MCP_URL=http://localhost:8080/mcp \
PENTEST_COPILOT_MCP_TOKEN=pc_mcp_... \
corepack pnpm run mcp:smoke| Minimum | |
|---|---|
| RAM | 8 GB (+2 GB if using the built-in Kali container) |
| Disk | 20 GB |
| Docker | v20+ with Compose v2+ |
| Node.js | v22+ (dev mode only) |
| pnpm | v9+ (dev mode only) |
Docker mode binds its UI and service ports to 127.0.0.1 by default. Do not
expose the stack to a LAN or the internet without TLS, authentication, and a
deliberate reverse-proxy configuration. In the built-in Kali mode, keep durable
workspace files under /kali-data; files elsewhere in the Kali container are
removed when the container is recreated.
The in-repository Setup and Troubleshooting guide is the authoritative source for installation, configuration, recovery, and deployment. The Wiki contains additional feature reference and may lag the current release:
- Getting Started - project overview
- Architecture - system design, agent loop, subagents
- Usage - workflow, consent model, chat interface
- Features - full feature overview
- Settings - models, SSH, VNC, Burp, Magnitude
- Capabilities - tool registry and buckets
- Agent Tools - all 16 tools and consent behavior
- Burp Suite Integration - setup and usage
- Browser Agent - Magnitude configuration
- VPN Management - profile management
- Slash Commands - session utilities
- Changelog - what's new
./run.sh dev # Starts MongoDB + Redis in DockerThen in separate terminals:
cd backend && pnpm install && pnpm run watch # TypeScript compiler
cd backend && pnpm run dev # Backend server (port 8080)
cd frontend && pnpm install && pnpm run dev # Frontend (port 3000)For development setup and troubleshooting, see the Setup and Troubleshooting guide.
- Dhruva Goyal - dhruva@bugbase.ai | LinkedIn | GitHub | X
- Aditya Peela - aditya@bugbase.ai | LinkedIn | GitHub | X
- Sitaraman Subramanian - sitaraman@bugbase.ai | LinkedIn | GitHub | X
@article{goyal2024hacking,
title={Hacking, the lazy way: LLM augmented pentesting},
author={Goyal, Dhruva and Subramanian, Sitaraman and Peela, Aditya},
journal={arXiv preprint arXiv:2409.09493},
year={2024}
}Contributions welcome. See the Contributing Guide and Code of Conduct.
Pentest Copilot is intended for authorized security testing only. Always have explicit permission before testing any system.