Skip to content

Home

Jump to bottom
goyal.dhruva@gmail.com edited this page Mar 11, 2026 · 14 revisions

Pentest Copilot

Pentest Copilot is an open-source, AI-driven penetration testing agent. It connects to a Kali Linux attack box over SSH, runs security tools autonomously, analyzes results, and iterates, all from a browser-based interface.

Unlike traditional AI assistants that wait for you to copy-paste output back and forth, Pentest Copilot operates as an agent. You describe the target and scope. It takes it from there: reconnaissance, enumeration, exploitation, reporting. You stay in control through a consent system that lets you approve or auto-run tool executions.

Prerequisites

Requirement Minimum
Docker + Docker Compose v20+ / v2+
RAM 8 GB (add 2 GB if running the built-in Kali container)
Disk 20 GB free
pnpm v9+ (only for developer mode)
Node.js v22+ (only for developer mode)

Quick Start

  1. Clone the repository:
git clone https://github.com/bugbasesecurity/pentest-copilot.git
cd pentest-copilot
  1. Run the setup script:
./run.sh start
  1. Open http://127.0.0.1:3000 in your browser, register an account, and start a session.

That's it. The run.sh script handles everything: config file generation, Docker builds, container orchestration.

Setup Modes

run.sh supports three modes:

Mode What it runs When to use
Core Docker MongoDB, Redis, Backend, Frontend You have your own external Kali/exploit box
Docker + Kali All of the above + a Kali container You want a self-contained setup with a built-in attack box
Developer MongoDB, Redis (and optionally Kali) You want to run the backend and frontend locally for development

run.sh Commands

Command Description
./run.sh start Guided start with configuration prompts
./run.sh start -q Quick start, skip prompts, use existing config
./run.sh config Update configuration (model keys, SSH, Google Search, Langfuse)
./run.sh dev Start in developer mode
./run.sh dev -q Quick dev start
./run.sh stop Stop all containers
./run.sh logs Tail container logs
./run.sh status Show container status
./run.sh help Show all available commands

run.sh setup wizard in the terminal

Configuration

Pentest Copilot uses two configuration files:

config.toml

Static configuration that requires a container restart to take effect. Created automatically from config.toml.template on first run.

[server]
port = 8080
deployment = "LOCAL"
base_url_frontend = "http://localhost:3000"
cors_origins = "http://localhost:3000"

[database]
mongo_uri = "mongodb://mongodb:27017"
mongo_database = "pentestcopilot"
redis_url = "redis://redis:6379"

[session]
secret = ""  # auto-generated on first run
lifetime = "7d"

[tracing]
langfuse_enabled = false

backend/.env

Dynamic configuration for model keys, SSH, integrations. Changes take effect immediately without restarting. Created from backend/.env.template on first run and also configurable through the Settings UI.

Key variables:

Variable Description
MODEL_PROVIDER LLM provider: openai, anthropic, google, mistral, openai-compatible
MODEL Model name (e.g. gpt-4o, claude-sonnet-4-20250514)
MODEL_API_KEY API key for the chosen provider
SSH_HOST Exploit box hostname or IP
SSH_PORT SSH port (default: 22)
SSH_USERNAME SSH user (default: root)
SSH_PASSWORD SSH password
BURP_RPC_HOST Burp Suite RPC host (optional)
MAGNITUDE_ENABLED Enable browser agent: true / false (optional)

For the full list of environment variables, see backend/.env.template.

What's Next

  • Architecture - how the system is put together
  • Usage - how to use Pentest Copilot day-to-day
  • Settings - configure models, SSH, integrations

Getting Started

Using Pentest Copilot

Configuration

Integrations

Reference

Clone this wiki locally