Pentest Copilot

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.

In Action

Pentest Copilot performing an auth bypass in OWASP Juice Shop:

Watch it on YouTube

What It Does

• 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 profiles 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.

Quick Start

git clone https://github.com/bugbasesecurity/pentest-copilot.git
cd pentest-copilot
./run.sh start

Open http://localhost:3000, register, and start a session.

run.sh handles config file generation, Docker builds, and container orchestration. On first run it prompts for your model provider and API key. Use ./run.sh start -q to skip prompts on subsequent runs.

./run.sh stop       # Stop all containers
./run.sh logs       # Tail logs
./run.sh status     # Container status
./run.sh config     # Update configuration
./run.sh dev        # Developer mode (infra only, run frontend/backend locally)
./run.sh help       # Full help

System Requirements

	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)

Documentation

Full documentation lives in the Wiki:

• Getting Started - setup, configuration, environment variables
• 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

Local Development

./run.sh dev    # Starts MongoDB + Redis in Docker

Then 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)

See the Wiki for detailed setup instructions.

Authors

• Dhruva Goyal - dhruva@bugbase.ai | LinkedIn | GitHub | X
• Aditya Peela - aditya@bugbase.ai | LinkedIn | GitHub | X
• Sitaraman Subramanian - sitaraman@bugbase.ai | LinkedIn | GitHub | X

Citations

@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}
}

Contributing

Contributions welcome. See the Contributing Guide and Code of Conduct.

License

MIT License

Disclaimer

Pentest Copilot is intended for authorized security testing only. Always have explicit permission before testing any system.