How bugbasesecurity/pentest-copilot works
Project Type and Purpose
• Pentest Copilot is a full-stack, browser-based AI-powered ethical hacking assistant.
• It follows a microservices/containerized architecture: Next.js frontend, Express/TypeScript backend, MongoDB, Redis, an AI API integration (OpenAI), and an optional Kali Linux container for pentesting.
File Structure
• Top-level directories:
• frontend/: Next.js 13 app using React, Ant Design, Redux Toolkit, React Query, Xterm (in-browser terminal), SCSS.
• backend/: Node.js + Express + TypeScript. Organized by controllers, routes, services, models (Mongoose), middlewares, utils.
• kali/: Dockerfile + entrypoint + tools.sh to build a Kali Linux container with SSH, OpenVPN, noVNC.
• nginx/: Reverse-proxy container.
• assets/: Static images and banners.
• Config & orchestration:
• docker-compose.yml: Defines services (frontend, backend, mongodb, redis, kali, nginx).
• .env.template files for each component.
Key Architecture Insights from README
• Microservices: Each service runs in its own container.
• Data stores: MongoDB for persistence, Redis for session/auth caching.
• Real-time: Socket.IO for live terminal, AI prompts/responses.
• AI integration: Backend calls OpenAI API (gpt-4/gpt-3.5).
Main Components & Their Roles
a. Client/browser (Next.js UI)
b. Frontend server (Next.js Node server)
c. Backend API server (Express/TypeScript)
d. Databases: MongoDB (persistent), Redis (cache/session)
e. External AI Service (OpenAI API)
f. Kali Container (SSH/VNC/OpenVPN endpoint + pentest tools)
g. Reverse Proxy (Nginx for TLS, routing)
h. Docker Compose (orchestration)
Component Interactions & Data Flow
• Browser ↔ Frontend: HTTP(S) requests, SSR/SSG, WebSocket (via Socket.IO client).
• Frontend ↔ Backend: REST API calls, WebSocket for real-time sessions.
• Backend ↔ MongoDB: via Mongoose for users, sessions, workspaces, todos.
• Backend ↔ Redis: session tokens, workspace state caching.
• Backend ↔ OpenAI API: HTTP calls to generate commands, summaries.
• Backend ↔ Kali Container: SSH or Socket.IO tunnel to execute commands, retrieve output.
• Browser ↔ Kali Container (indirect): Through backend & WebSocket, terminal emulation via Xterm.
• Frontend ↔ Reverse Proxy (Nginx): All incoming traffic funnels through Nginx (optional).
Architectural Patterns & Design Principles
• Microservices + Containers: Each logical service in its own Docker container.
• Separation of Concerns:
• UI layer (Next.js)
• API layer (Express)
• Data layer (MongoDB/Redis)
• Pentest environment (Kali)
• Event-Driven Real-Time: Socket.IO pub/sub for live terminal and AI feedback.
• Agentic AI: Backend orchestrates AI as an autonomous agent to run commands.
• MVC on Backend: Controllers → Routes → Services → Models.