Pen Pal is an AI-powered penetration testing assistant that turns vulnerability scanning and exploitation into an automated, end-to-end workflow. Point it at a target network and it will discover vulnerabilities with OpenVAS, rank them by severity, and use an LLM-driven agent to select and run Metasploit modules against each finding, iterating, adapting, and reporting as it goes.
Traditional pentesting involves hours of manual triage: cross-referencing CVEs, searching for the right Metasploit module, tweaking options, reading output, and deciding what to try next. Pen Pal collapses that cycle into an autonomous loop. The agent uses retrieval-augmented generation (RAG) over a FAISS index of every Metasploit module's documentation to find the most relevant exploit or auxiliary module for a given vulnerability, configures it, executes it via Metasploit's RPC interface, and evaluates the result to decide its next move. Every step is logged and surfaced through a web dashboard and REST API so you can monitor progress, review findings, and intervene at any point.
- OpenVAS/Greenbone integration launches and monitors vulnerability scans against target hosts
- Configurable severity thresholds filter results by minimum CVSS score so the agent focuses on what matters
- Vulnerability capping limits the number of findings passed to the exploitation phase to control scope and runtime
- LLM-driven decision making using Ollama to select modules, configure options, and evaluate execution results
- Iterative agent loop that can pivot strategies, try alternative modules, or stop early based on results (configurable max iterations)
- Metasploit RPC execution runs modules against targets through Metasploit Framework's RPC interface
- Real-time run tracking with phase progress indicators and live status updates for pentest and agent runs
- Vulnerability breakdown per run showing severity distribution and exploitation success/failure for each finding
- Agent execution history with step-by-step logs of every module selection, execution, and decision
- REST API for programmatic access to scans, pentest runs, agent runs, and statistics
- Multi-tenant (WIP) organizations with role-based access control (admin, analyst, viewer)
- Interactive agent that accepts natural-language queries and translates them into Metasploit actions
- Pentest orchestrator (PLANNED) that runs the full scan-triage-exploit pipeline from the command line
- Scan -- OpenVAS discovers vulnerabilities on target hosts, filtered by CVSS severity
- Exploit -- The LLM agent uses RAG over Metasploit module docs to select and execute the best exploit for each vulnerability
- Decide -- After each attempt the agent evaluates results and decides whether to continue, pivot, or stop
- Report -- Every step is tracked and surfaced through the web dashboard and API
This is a uv workspace monorepo with three packages:
pen-pal/
├── core/ # pen-pal-core
│ ├── src/pen_pal_core/
│ │ ├── agent/ # LLM agent, RAG retriever, tool router
│ │ ├── pentest/ # Scan-triage-exploit orchestrator
│ │ └── gmp/ # OpenVAS / GMP client
│ ├── vector_store/ # FAISS index of Metasploit module docs
│ └── metasploit-framework/ # Git submodule
│
├── backend/ # pen-pal-api (FastAPI)
│ ├── src/pen_pal_api/
│ │ ├── routers/ # REST endpoints
│ │ ├── services/ # Business logic
│ │ ├── db/ # SQLAlchemy models & Alembic migrations
│ │ └── schemas/ # Pydantic request/response models
│ └── Dockerfile
│
├── frontend/ # React SPA
│ ├── src/
│ │ ├── pages/ # Dashboard, pentest runs, agent runs
│ │ ├── components/ # Shared UI (data tables, badges, dialogs)
│ │ └── api/ # Typed API client
│ └── Dockerfile
│
└── landing/ # Marketing site (Astro)
| Layer | Technologies |
|---|---|
| Core | Python 3.12+, LangChain, Ollama, FAISS, python-gvm, msgpack-rpc |
| Backend | FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, Alembic, PyJWT |
| Frontend | React, TypeScript, Vite, Tailwind CSS, shadcn/ui, TanStack Query |
| Landing | Astro, React, Tailwind CSS |
| Infra | Docker, Docker Compose, Metasploit Framework, OpenVAS/Greenbone |
- uv package manager
- Docker and Docker Compose
git clone --recurse-submodules https://github.com/manusfv/pen-pal
cd pen-palCopy the .env.EXAMPLE file into a .env file with your credentials (MSF, GMP, database, JWT secret)
uv syncdocker compose -f docker-compose.dev.yml upThis starts PostgreSQL, Metasploit RPC, OpenVAS/Greenbone, Ollama, the FastAPI backend, and the React frontend.
- Frontend: http://localhost:5173
- API: http://localhost:8000
# Run the agent with a query
uv run agent "find and exploit CVE-2024-XXXX on 192.168.1.0/24"
# Parse Metasploit module documentation into the vector store
uv run parse-docsuv run ruff check . # Lint (check only)
uv run ruff check --fix . # Lint (auto-fix)
uv run ruff format --check . # Format (check only)
uv run ruff format . # Format (apply)uv run pytest # All tests
uv run pytest tests/unit # Unit tests only
uv run pytest tests/integration # Integration tests (requires Docker services)
uv run pytest tests/e2e # End-to-end tests (requires full stack Docker services)
uv run pytest -x # Stop on first failureIntegration tests require running services (PostgreSQL + Metasploit RPC). Use the helper script:
./core/scripts/run-integration-tests.shEnd-to-end tests require the full stack (GVM, DVWA, Metasploit, Ollama) to be running in order to complete pentest workflows. Again, you can use the helper script:
./core/scripts/run-e2e-tests.shcd backend
uv run alembic upgrade head # Apply migrations
uv run alembic revision --autogenerate -m "description" # Create migration