Skip to content

Home

Jump to bottom
Sitaraman S edited this page Mar 17, 2025 · 12 revisions

1. Getting Started

To get started with Pentest Copilot, follow these steps:

Clone the repository:

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

Configure environment variables:

Rename ./.env.template to .env in the main directory. Rename ./backend/.env.template to ./backend/.env.

cp .env.template .env
cp backend/.env.template backend/.env

Set up custom exploit box (Kali server)

To use a custom host on the integrated browser terminal, you can set the SSH_* environment variables in ./backend/.env:

SSH_HOST=localhost
SSH_PORT=4242
SSH_USERNAME=root

# use either SSH_PASSWORD or SSH_PRIVATE_KEY + SSH_PRIVATE_KEY_PASSPHRASE
SSH_PASSWORD=''
# OR
SSH_PRIVATE_KEY='/path/to/your/private/key'
SSH_PRIVATE_KEY_PASSPHRASE=

Note

If you are using a custom host, ensure that the host is accessible from the backend server.

Set up OpenAI API keys:

In ./backend/.env, add your OpenAI or any Custom LLM Model API keys for both the large and small models:

Important

Custom LLM models are required to use the OpenAI Chat API format for pentest copilot to run effectively.

MODEL_API_KEY_LARGE=your_large_model_api_key
MODEL_API_KEY_SMALL=your_small_model_api_key

Launch the tool using Docker Compose:

docker compose up --build -d

Access the application:

Once the containers are running, access the frontend at http://127.0.0.1:3000.

Environment Configuration ⚙️

Pentest Copilot requires configuration through environment variables. Below are the key variables for both the main directory and the backend.

Main Directory (.env)

Variable Description Default
NEXT_PUBLIC_BACKEND_URI URL of the backend server http://127.0.0.1:8080
NEXT_PUBLIC_DEPLOYMENT Deployment environment LOCAL
NEXT_PUBLIC_GTM_ID Google Tag Manager ID (optional)

Backend (./backend/.env)

Variable Description Default
BASE_URL_FRONTEND URL of the frontend server http://127.0.0.1:3000
DEPLOYMENT Deployment environment LOCAL
MONGO_DATABASE Name of the MongoDB database pentestcopilot
MONGO_URI MongoDB connection string mongodb://127.0.0.1:27017/pentestcopilot
SESS_LIFETIME Session lifetime in milliseconds 1000
SESS_NAME Session cookie name sid
SESS_SECRET Secret key for signing session cookies thisismysessionsecret!123
PORT Port for the backend server 8080
MODEL_LARGE Identifier for the large OpenAI model gpt-4-1106-preview
MODEL_API_KEY_LARGE API key for the large OpenAI model your_large_model_api_key
MODEL_SMALL Identifier for the small OpenAI model gpt-3.5-turbo-1106
MODEL_API_KEY_SMALL API key for the small OpenAI model your_small_model_api_key
SSH_HOST Hostname for the custom exploit box localhost
SSH_PORT Port for the custom exploit box 4242
SSH_USERNAME Username for the custom exploit box root
SSH_PASSWORD Password for the custom exploit box ''
SSH_PRIVATE_KEY Path to the private key for SSH '/path/to/private/key'
SSH_PRIVATE_KEY_PASSPHRASE Passphrase for the private key ''

Architecture Overview 🏗️

Pentest Copilot follows a microservices architecture using Docker containers:

Service Port(s) Description
MongoDB 27017 Stores application data like user data, sessions and workspace information
Redis 6379 Handles authentication and workspace data for fast querying
Backend 8080 Node.js application that runs the API and socket connections for real-time communication with the frontend and Kali container
Frontend 3000 Hosts the user interface built with Next.js
Kali 4200, 1194/udp, 9020 Kali Linux container with pre-installed pentesting tools, accessible via SSH, OpenVPN, and noVNC

Note

You can see the list of tools being installed in the Kali container by checking ./kali/tools.sh. This file installs all tools, tool names, and the download commands.

System Requirements 💻

To run Pentest Copilot effectively, your host machine should meet the following minimum requirements:

  • RAM: 8GB (to accommodate the frontend, backend, databases, and the resource-intensive Kali container)
  • Processor: Multi-core processor (for smooth operation of multiple containers)
  • Disk Space: 20GB (for the Kali container and other components)

Important

8GB RAM is minimum requirement to build docker images, otherwise the builds mightfail.

Important

The Kali container, which runs a full Kali Linux desktop with pentesting tools, requires significant resources. Allocating at least 2GB RAM to the Kali container is recommended for optimal performance.

Woohoo! You're all set to start using Pentest Copilot. Up next, look into how to use pentest copilot to kick off a pentest session here: Usage.

Clone this wiki locally