🧠 PentestMind

AI-powered autonomous penetration testing agent built with LangChain + Claude.

PentestMind orchestrates a full pentest engagement: reconnaissance → scanning → CVE correlation → MITRE ATT&CK mapping → risk scoring → professional report — all driven by a ReAct agent that reasons over tool outputs in natural language.

⚠️ Legal Notice: PentestMind is intended for authorised security assessments only. Using it against systems without explicit written permission is illegal. Always operate within agreed scope and rules of engagement.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         PentestMind                             │
│                                                                 │
│  CLI (main.py)  ──►  FastAPI (api/server.py)                   │
│                              │                                  │
│                    ┌─────────▼──────────┐                      │
│                    │    Orchestrator     │  ← Plans phases      │
│                    └─────────┬──────────┘                      │
│                              │                                  │
│                    ┌─────────▼──────────┐                      │
│                    │    Brain Agent      │  ← ReAct reasoning   │
│                    │  (LangChain + Claude│                      │
│                    └──┬──────┬──────┬───┘                      │
│                       │      │      │                           │
│              ┌────────▼┐  ┌──▼───┐ ┌▼────────────┐            │
│              │  Nmap   │  │ MSF  │ │ CVE / MITRE │            │
│              │ Wrapper │  │ RPC  │ │  Lookup     │            │
│              └─────────┘  └──────┘ └─────────────┘            │
│                                                                 │
│              ┌─────────────────────────────────┐               │
│              │  RAG Memory (ChromaDB)           │               │
│              │  Risk Engine  │  Webhook Handler │               │
│              └─────────────────────────────────┘               │
└─────────────────────────────────────────────────────────────────┘

---

Quick Start

1. Prerequisites

• Python 3.12+
• nmap installed (apt install nmap / brew install nmap)
• Anthropic API key

2. Install

git clone https://github.com/yourorg/pentestmind
cd pentestmind

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

3. Configure

cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY at minimum

4. Ingest knowledge base

python main.py ingest

5. Run a scan

# Quick Nmap scan
python main.py scan 192.168.1.100 --ports 1-1024

# Look up a CVE
python main.py cve CVE-2021-41773

# Send a one-off AI task
python main.py task 192.168.1.100 "Scan for open ports and check services for known vulnerabilities"

6. Run a full engagement

python main.py engage 192.168.1.100 --scope "all ports" --auth full

7. Start the API server

python main.py serve
# API docs at http://localhost:8000/docs

---

Docker

# Build and start all services (API + Metasploit + ChromaDB)
cp .env.example .env  # edit first
docker-compose up -d

# View logs
docker-compose logs -f pentestmind

# Stop
docker-compose down

---

API Reference

All endpoints (except /health, /, and /webhooks/*) require:

X-API-Key: <your API_SECRET_KEY>

Key Endpoints

Method	Path	Description
GET	/health	Health check
POST	/engagements	Create & plan engagement
POST	/engagements/{id}/execute	Run engagement (background)
GET	/engagements/{id}/report	Get Markdown report
POST	/agents/{target}/task	Send task to BrainAgent
POST	/cve/lookup	Fetch CVE from NVD
POST	/cve/search	Search CVEs by keyword
POST	/mitre/technique	Look up ATT&CK technique
GET	/mitre/search?q=...	Search ATT&CK techniques
POST	/memory/ingest	Ingest knowledge base
GET	/memory/search?q=...	Semantic search memory
POST	/webhooks/{source}	Receive scanner webhook

Full interactive docs: http://localhost:8000/docs

---

Webhook Integration

Send scanner output directly to PentestMind for automatic enrichment and risk scoring.

Nuclei

nuclei -target https://example.com -json-export nuclei_out.json
curl -X POST http://localhost:8000/webhooks/nuclei \
  -H "Content-Type: application/json" \
  -d @nuclei_out.json

OWASP ZAP

Configure ZAP's "Active Scan" → Alerts export to: http://localhost:8000/webhooks/zap

Signed Webhooks (HMAC-SHA256)

import hashlib, hmac, time, requests

secret = b"your-webhook-secret"
payload = json.dumps(data).encode()
ts = str(int(time.time()))
sig = hmac.new(secret, ts.encode() + b"." + payload, hashlib.sha256).hexdigest()

requests.post(
    "http://localhost:8000/webhooks/custom",
    data=payload,
    headers={
        "X-PentestMind-Signature": sig,
        "X-PentestMind-Timestamp": ts,
        "Content-Type": "application/json",
    },
)

---

Project Structure

pentestmind/
├── agents/
│   ├── brain_agent.py       # Core ReAct LangChain agent
│   └── orchestrator.py      # Engagement planner & executor
├── api/
│   └── server.py            # FastAPI REST server
├── config.py                # Pydantic settings (all env vars)
├── data/
│   ├── chroma_db/           # ChromaDB vector store (git-ignored)
│   ├── knowledge_base/      # Seed documents for RAG
│   └── reports/             # Generated Markdown reports
├── main.py                  # CLI entry point (Typer)
├── modules/
│   ├── cve/                 # NVD client + CVE parser
│   ├── llm/                 # LLM client wrapper (Claude)
│   ├── mitre/               # MITRE ATT&CK STIX loader
│   ├── rag/                 # Embeddings + ChromaDB memory
│   ├── scoring/             # Risk engine + Finding model
│   └── webhooks/            # Scanner webhook handler + schemas
├── tests/                   # Pytest test suite
├── tools/
│   ├── msf_wrapper.py       # Metasploit LangChain tools
│   ├── nmap_wrapper.py      # Nmap LangChain tool
│   └── safe_executor.py     # Sandboxed subprocess runner
└── utils/
    ├── logger.py            # Loguru structured logging
    └── prompts.py           # All LangChain prompt templates

---

Running Tests

pytest tests/ -v --tb=short
pytest tests/ --cov=. --cov-report=html

---

Safety Model

PentestMind has multiple layers of safety:

Layer	Mechanism
SAFE_MODE	Blocks all MSF module execution when true (default)
CIDR allowlist	ALLOWED_TARGET_CIDRS restricts scannable IPs
Command blocklist	SafeExecutor blocks destructive shell commands
Confirmation gate	confirm=True required before any exploit runs
Authorisation prompt	CLI and agent always ask for written auth confirmation
Audit log	Every action logged to data/logs/audit.log

---

Environment Variables

See .env.example for the full list with descriptions.

Minimum required: ANTHROPIC_API_KEY

---

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Write tests for your changes
4. Run pytest and ruff check .
5. Open a PR with a clear description

---

License

MIT – see LICENSE for details.

Always use responsibly and within authorised scope.