The Problem

Pentest Copilot is an AI-driven penetration testing assistant that automates tool execution on attack boxes, but its codebase carries structural debt that increases risk and slows development. With 482 files, no CI/CD pipeline, and 71 measured quality findings including 25 high-severity issues, changes carry unintended blast radius. The repository also runs with privileged Docker networking and has committed secrets, making it unsuitable for untrusted environments without hardening.

What This Does

Pentest Copilot is a browser-based ethical hacking assistant that connects to a Kali attack box and runs 16 agent tools (bash, Python scripts, Burp Suite integration, browser automation via Magnitude) across 100+ capabilities in 7 security categories. The backend (backend/src/server.ts) is an Express server that mediates agent tool execution, session management, and websocket communication. The agent service (backend/src/services/agent.service.ts) orchestrates tool calls and participates in a circular import dependency with agent.tools.ts and subagent.manager.ts. The tool registry (backend/src/tools/registry) is a hub module with 7 inbound importers and 41 outbound imports (instability 0.85), meaning changes ripple widely. The Sessions model (backend/src/models/Sessions/Sessions.model.ts) is the most depended-on module (25 importers, 0 outbound), and at 660 lines is an oversized file that is hard to hold in one head. The docker-compose configuration mounts the Docker socket with privileged mode, and backend/src/utils/getSecrets.ts contains secret-shaped paths indicating committed credentials.

How It Is Wired

Execution starts at backend/src/server.ts, which initializes the Express app, registers routes for all 21 controller domains (agent, workspace, mythic, burp, etc.), and starts the HTTP server. Agent tool requests flow through backend/src/routes/agent.routes.ts → backend/src/services/agent.service.ts. The service imports from backend/src/tools/types (Ca 49, Ce 2, instability 0.04) and backend/src/tools/registry (Ca 7, Ce 41, instability 0.85), the latter being a high-instability hub. The circular import cycle involves agent.service.ts → agent.tools.ts → subagent.manager.ts → back to agent.service.ts; breaking this cycle requires extracting shared types or inverting a dependency. Tool handlers live in backend/src/tools/handlers/ (48 files) and are registered via the registry. The frontend (frontend/src/store/index.js) connects to the backend via websockets for real-time tool output and session state. The database layer uses Mongoose models in backend/src/models/ (21 model files) with schemas for sessions, workspaces, tasks, and findings.

Key external touches: The backend writes shell output to the attack box filesystem, manages VPN connections via OpenVPN profiles, and integrates with Burp Suite and Caido through dedicated client modules (backend/src/services/burp-ca.service.ts, backend/src/services/caido.client.ts). The browser automation layer (backend/src/tools/handlers/mythic-*.ts) interfaces with the Magnitude browser automation framework.

How To Use It

Setup:

# Clone the repository
git clone https://github.com/moses-y/pentest-copilot

# Install dependencies (pnpm)
cd pentest-copilot
pnpm install

# Environment configuration
cp backend/.env.template .env
# Edit .env with required keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

# Start the development environment
docker-compose up -d  # or use docker-compose.dev.yml

Configuration: Environment variables are read from backend/.env (referenced by backend/src/utils/loadConfig.ts). Required vars include model API keys (OpenAI, Anthropic, Google, Mistral). The Docker base image is node:22-bookworm-slim per backend/Dockerfile.

Running it: Start the server with pnpm start (defined in backend/package.json, likely node backend/src/server.ts). The UI runs on the port configured in the frontend config. VNC is available at localhost:5900 in Docker mode for browser observation.

Real-World Use

A security consultant assigns a boot2root engagement. They launch Pentest Copilot, connect their Kali VM, and describe the target: "OWASP Juice Shop, test authentication bypass." The agent initializes, spawns a browser agent (Magnitude) proxied through Burp Suite, attempts login flows, and iterates through up to 25 tool calls per turn. It runs subagents in parallel for directory brute-forcing and subdomain enumeration. The consultant monitors tool output via the VNC stream or websocket logs. When the agent encounters a dangerous command (e.g., rm -rf /), it pauses and requires explicit approval. After 25 iterations without progress, the session times out and the consultant reviews the findings archive in the database.

Code Health & Issues

Measured findings (71 total, 25 high, 46 medium, 0 low):

  • [HIGH/cognitive_load] Oversized file x13 — backend/src/models/Sessions/Sessions.model.ts, backend/src/utils/llm/providers.ts, backend/src/capabilities/registry.ts (e.g., 660 code lines in Sessions.model.ts)
  • [HIGH/clarity] Hub module x7 — backend/src/tools/types.ts, backend/src/models/Sessions/Sessions.model.ts, backend/src/utils/envWriter.ts (49 modules depend on this one)
  • [HIGH/soundness] Import cycle member x12 — backend/src/services/agent.service.ts, backend/src/services/agent.tools.ts, backend/src/services/subagent.manager.ts (circular dependency)
  • [MEDIUM/cognitive_load] High branching density x13 — backend/src/utils/toolArguments.ts, backend/src/utils/mythicFormat.ts, backend/src/services/ssh-profile.service.ts (29 branch points over 63 lines)
  • [HIGH/clarity] Duplicated code blocks — 401 repeated 6-line blocks across 73 files including backend/src/controllers/agent.controller.ts
  • [HIGH/cognitive_load] Deep nesting x14 — backend/src/tools/handlers/update-engagement-state.ts, frontend/src/components/common/SettingsSidebar.jsx, frontend/src/components/pages/session/mythic/MythicC2Page.jsx (max indentation depth 6)
  • [MEDIUM] 71 total findings across 6 kinds

Code Health Audit (9 findings):

  • [HIGH] Upgrade pinned dependency carrying advisory — ws@8.19.0 CVE-2026-48779, @opentelemetry/sdk-node@0.213.0 CVE-2026-44902, axios@1.13.6 CVE-2026-44494, multer@1.4.5-lts.2 CVE-2025-47935 and 27 more
  • [HIGH] Add CI workflow that builds and tests — no .github/ CI configuration; 318 source files with no automated gate
  • [HIGH] Drop privileged mode and host networking — docker-compose.yml mounts Docker socket with privileged
  • [HIGH] Add build gate for deployable artifacts — backend/Dockerfile has no automated build validation
  • [MEDIUM] Enable Dependabot or Renovate — 2 manifests, no update bot configured
  • [MEDIUM] Pin container base image by digest — backend/Dockerfile uses node:22-bookworm-slim (mutable tag)
  • [MEDIUM] Move large binaries to Git LFS — frontend/src/assets/just_image.jpeg is 8.5MB
  • [MEDIUM] Add non-root USER to the image — backend/Dockerfile has no USER directive
  • [LOW] Add repository convention files — missing .editorconfig, .gitattributes, formatter config

Committed secrets confirmed via backend/src/utils/getSecrets.ts; CI absent; lockfile present.

The Bottom Line

This is a capable AI-red-team assistant with 16 integrated tool categories and real browser automation, but it ships with significant structural debt: no CI/CD, privileged Docker execution, committed secrets, and 71 quality findings including import cycles and oversized modules. Teams should treat this as a technical prototype requiring hardening — upgrade dependencies, add a CI gate, drop privileged networking, and split the oversized model files before using it in a production engagement pipeline. The modular tool-handler architecture is the codebase's strongest design point; everything else is remediable but non-trivial.