EliotSec – AI‑Powered Penetration Testing Platform

EliotSec (aka “Eliot”) is a full‑stack application for orchestrating safe, repeatable penetration tests. It provides a Next.js frontend for initiating scans and viewing results, a Go (Fiber v3) backend that controls ephemeral Kali containers via Docker, and a curated Kali image with common offensive security tools. The AI penetration testing agent runs inside Kali via Codex CLI using your Claude Pro plan — no API keys are required by the backend.

Architecture Overview

                  +--------------------+
                  |     Next.js UI     |
                  |  (apps/web, Bun)   |
                  +----------+---------+
                             |
                      HTTPS  |  JSON API
                             v
                    +--------+--------+
                    |    Go API       |
                    |  Fiber v3, JWT  |
                    |  Rate limits    |
                    |  Security hdrs  |
                    +----+-------+----+
                         |       |
                  Docker |       | Optional
                 (socket)|       |  Codex Agent
                               |  (Codex CLI)
                         v       v
                +--------+-------+----------------------+
                |  Orchestrator: ephemeral Kali        |
                |  - Pull/build image (mailshieldai/    |
                |    kali-pt:latest)                   |
                |  - Run tools (nmap, nikto, …)        |
                |  - Collect artifacts                 |
                +--------------------------------------+

                +--------------------------+
                |  Storage (in‑memory now) |
                |  Results + progress      |
                +--------------------------+

Key Components

• Frontend: Next.js App Router (apps/web) with WorkOS AuthKit auth.
• Backend: Go 1.22 + Fiber v3 with JWT auth (WorkOS), security headers, rate limiting, and input validation.
• Orchestrator: Uses Docker Engine to run ephemeral Kali containers preloaded with tools (nmap, nikto, etc.).
• AI Agent: Codex CLI running inside Kali drives reconnaissance and analysis autonomously (Full‑Access mode). No API keys are required by the backend.

Prerequisites

• macOS/Linux with Docker Engine or Docker Desktop.
• Go 1.22+ (for local backend dev) and Bun or Node.js 20+ (for frontend dev).
• Optional: WorkOS keys for authentication. No OpenAI keys needed.

Quick Start (Local Dev)

1. Clone and prepare environment files

• Copy .env.example files to .env and fill in values as needed:
  • Project root: .env (optional DevOps/AI keys)
  • Backend: backend/.env
  • Frontend: frontend/.env or frontend/apps/web/.env

2. Install dependencies

make setup

3. Run development servers

make dev

• Frontend: http://localhost:3000 (or 3001 in dev, see scripts)
• Backend: http://localhost:8080

4. Run tests

make test

Production with Docker Compose

The root docker-compose.yml orchestrates the full stack:

• frontend: Next.js built image, served with next start.
• backend: Go API running on port 8080. The Docker socket is mounted so the backend can create ephemeral Kali containers.
• kali: A long‑lived Kali service primarily to ensure the Kali image is built and for manual interactive use. The backend creates additional ephemeral containers from the same image for each scan.

Build and run:

docker compose build
docker compose up -d

# Frontend: http://localhost:3000
# Backend:  http://localhost:8080

Environment Configuration (Updated for WorkOS)

Backend (backend/.env):

• PORT – API port (default 8080)

• AUTH_DISABLED – set to true for local dev without JWT validation

• WORKOS_CLIENT_ID, WORKOS_JWKS_URL, WORKOS_ISSUER, WORKOS_AUDIENCE – JWT validation

• KALI_IMAGE – Docker image to use for scans (default mailshieldai/kali-pt:latest)

• CORS_ALLOW_ORIGINS – allowed origins for the UI

Frontend (frontend/.env or apps/web/.env):

• NEXT_PUBLIC_API_URL – base URL of the backend API (e.g., http://localhost:8080)
• WorkOS keys: WORKOS_CLIENT_ID, WORKOS_API_KEY, WORKOS_COOKIE_PASSWORD, NEXT_PUBLIC_WORKOS_REDIRECT_URI.

Development Workflow

1. Start the API, then point the UI to it via NEXT_PUBLIC_API_URL.
2. Create a scan from the UI; the API validates input, queues a job, provisions an ephemeral Kali container, runs tools, collects results, and exposes them via GET /api/scan/:id/results.
3. Iterate on parsing/analysis or UI display as needed. For deeper work, add tools to the Kali image under backend/docker/kali/.

Security Considerations

• Strict HTTP headers: HSTS (when behind HTTPS), X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy.
• CORS locked down via CORS_ALLOW_ORIGINS.
• Rate limiting applied globally with per‑minute thresholds.
• JWT auth via WorkOS by default; can be disabled in local dev with AUTH_DISABLED=true.
• Input validation:
  • target (domain/URL/IP) strictly validated server‑side.
  • Path params (e.g., id) validated for allowed characters.
• Docker hardening:
  • Ephemeral containers (autoremove) with minimal capabilities inside the Kali image.
  • When containerizing the backend, Docker socket is required; restrict access to trusted hosts only.

API Documentation (Backend)

Base URL: http://localhost:8080

• GET /api/health → { status: "ok", time: string }

• POST /api/scan

  • Body: { "target": string, "depth": number }
  • 202 Accepted: { id, target, status, queuedAt, pollUrls: { status, results } }

• GET /api/scan/:id/status → scan status and progress

• GET /api/scan/:id/results → final results including tool artifacts and optional AI summary

Testing

Integration tests live in backend/test/integration_test.go and cover the end‑to‑end flow using mocked Docker operations. JWT auth validation is covered in backend/test/auth_workos_test.go. Run them with:

make test

Make Targets

• make setup – install backend and frontend dependencies
• make build – build backend binary and frontend Next.js app
• make dev – run both dev servers (frontend + backend)
• make test – run backend tests
• make docker – build Docker images via root docker‑compose
• make clean – remove build artifacts and caches

Notes

• The backend stores state in memory; for production you should replace the store with a persistent datastore.
• The Kali image is maintained under backend/docker/kali. Add/upgrade tools there and rebuild.
• For cloud deployments, run the backend on a secure host with access to a Docker Engine (or use dedicated runners) and put the API behind TLS.

Monitoring & Observability

This repo includes a Prometheus + Grafana stack with dashboards and alerts. See docs/monitoring.md for setup.