PentestAI

Multi-agent AI-powered penetration testing framework. Uses Claude models (via AWS Bedrock) to coordinate a team of specialized security agents with access to a full Kali Linux toolset.

Legal Disclaimer: This tool is intended for authorized security testing only. Always obtain written permission before testing any system you do not own. Unauthorized access to computer systems is illegal.

Architecture

Features

• 6 specialized agents — Recon, Web Attack, Exploit, Research, Post-Exploit, Report
• Full Kali toolset via Docker (nmap, nuclei, sqlmap, ffuf, nikto, metasploit, etc.)
• RAG knowledge base — 870+ cybersecurity skill cards indexed with pgvector
• Auto region rotation — rotates across AWS Bedrock regions on quota limits
• Session persistence — resume interrupted engagements
• Safety guardrails — scope validation, authorization checks, rules of engagement

Prerequisites

• Python 3.11+
• Docker Desktop
• AWS account with Bedrock access (Claude models enabled)
• PostgreSQL with pgvector extension (for knowledge base)

Quick Start

# Clone the repository
git clone https://github.com/YOUR_USERNAME/pentestai.git
cd pentestai

# Install dependencies
pip install -e "."

# Copy and configure environment
cp .env.example .env
# Edit .env with your AWS credentials and database URL

# Start infrastructure
docker compose -f docker/docker-compose.yml up -d

# Verify setup
python -m src.main setup

# (Optional) Load knowledge base
git clone https://github.com/yaklang/hack-skills.git data/hack-skills
python -m src.main ingest-skills

Usage

Authorized Penetration Test (with scope enforcement)

python -m src.main run target.example.com \
    --auth-ref "SOW-2026-001" \
    --scope-file scope.yaml \
    --client "Acme Corp" \
    --max-iterations 15

Hack Mode (CTF / self-owned targets)

python -m src.main hack target.example.com -obj "full compromise"

# Interactive chat with the team
python -m src.main hack target.example.com --chat

# Resume after quota limit
python -m src.main hack --resume

Other Commands

python -m src.main setup            # Check infrastructure
python -m src.main sessions         # List saved sessions
python -m src.main scope-template   # Generate scope.yaml template
python -m src.main ingest-skills    # Load knowledge base

Project Structure

src/
├── main.py              # CLI entry point
├── config.py            # Settings and region rotation
├── models/              # Pydantic models (Engagement, Finding, Report)
├── agents/              # Agent definitions (recon, web_attack, exploit, etc.)
├── team/                # Multi-agent team orchestration
├── tools/               # Tool implementations (docker exec, browser, recon, etc.)
├── safety/              # Scope guard, authorization validation
├── knowledge/           # pgvector skill loading and retrieval
└── report/              # Jinja2 report generation
docker/
├── Dockerfile.kali      # Kali Linux with security tools
├── Dockerfile.app       # Python app container
└── docker-compose.yml   # Full stack orchestration
scripts/
├── import_cybersecurity_skills.py
└── setup_kali_tools.sh

Configuration

Copy .env.example to .env and fill in:

Variable	Description
AWS_ACCESS_KEY_ID	AWS credentials for Bedrock
AWS_SECRET_ACCESS_KEY	AWS secret key
AWS_REGION	Starting region (rotates automatically)
DATABASE_URL	PostgreSQL connection string
KALI_CONTAINER_NAME	Docker container name for Kali

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run linting: ruff check src/
5. Submit a pull request

License

MIT License. See LICENSE for details.

Responsible Use

This tool is designed for:

• Authorized penetration testing engagements
• CTF competitions
• Security research on systems you own
• Educational purposes

Never use this tool against systems without explicit written authorization.