zen-ai-pentest-framework

---
name: zen-ai-pentest-framework
description: AI-powered autonomous penetration testing framework with multi-agent system, real security tool execution, and compliance reporting
triggers:
  - run a penetration test with AI
  - scan for vulnerabilities using AI agents
  - execute automated security testing
  - perform AI-assisted penetration testing
  - analyze security with Zen AI Pentest
  - run autonomous security scans
  - test application security with AI framework
  - deploy AI penetration testing tools
---

# Zen AI Pentest Framework

> Skill by [ara.so](https://ara.so) — Security Skills collection.

## Overview

Zen-AI-Pentest is a production-ready, AI-powered autonomous penetration testing framework that orchestrates 72+ real security tools through an intelligent multi-agent system. It executes actual tools (Nmap, Nuclei, SQLMap, FFuF, etc.) with safety controls, not mocks or simulations.

**Key capabilities:**
- Autonomous AI agents using ReAct pattern (Reason → Act → Observe → Reflect)
- Real tool execution in Docker sandbox with 4-level safety controls
- Risk engine with false positive reduction and CVSS/EPSS scoring
- FastAPI backend with WebSocket real-time updates
- PostgreSQL persistence and Redis caching
- JWT authentication with RBAC
- Professional PDF/HTML reporting with compliance mapping
- CI/CD integration (GitHub Actions, GitLab CI, Jenkins)

## Installation

### Prerequisites

- Python 3.10+
- Docker and Docker Compose
- PostgreSQL 13+ (or use Docker Compose)
- Redis (optional, for caching)

### Quick Start with Docker Compose

```bash
# Clone repository
git clone https://github.com/SHAdd0WTAka/Zen-Ai-Pentest.git
cd Zen-Ai-Pentest

# Set environment variables
cp .env.example .env
# Edit .env with your API keys and configuration

# Start full stack
docker-compose up -d

# Access web UI
# http://localhost:3000 (default credentials: admin/admin)

# Access API docs
# http://localhost:8000/docs
```

### Manual Installation

```bash
# Install Python dependencies
pip install -r requirements.txt

# Install security tools (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y nmap nuclei sqlmap ffuf whatweb wafw00f subfinder httpx nikto

# Initialize database
python -m alembic upgrade head

# Run API server
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

# In another terminal, run frontend
cd frontend
npm install
npm run dev
```

## Configuration

### Environment Variables

Create `.env` file in project root:

```bash
# API Keys (REQUIRED)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Database
DATABASE_URL=postgresql://zen:zen_password@localhost:5432/zen_pentest
REDIS_URL=redis://localhost:6379/0

# Security
JWT_SECRET_KEY=your-random-secret-key-min-32-chars
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Safety Controls (0-3)
# 0: Read-only info gathering
# 1: Active scanning (port scans)
# 2: Vulnerability probing
# 3: Exploit validation (requires VPN)
DEFAULT_SAFETY_LEVEL=1
REQUIRE_VPN_FOR_LEVEL_3=true

# Notifications (optional)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# Agent Configuration
MAX_ITERATIONS=10
AGENT_TIMEOUT=300
ENABLE_MEMORY=true
MEMORY_WINDOW=5

# Tool Timeouts (seconds)
NMAP_TIMEOUT=300
NUCLEI_TIMEOUT=600
SQLMAP_TIMEOUT=900
```

### Configuration File

`config/config.yaml`:

```yaml
agents:
  default_model: "gpt-4"
  fallback_model: "claude-3-opus"
  temperature: 0.7
  max_tokens: 4096
  
tools:
  enabled:
    - nmap
    - nuclei
    - sqlmap
    - ffuf
    - subfinder
  
  nmap:
    default_args: ["-sV", "-sC", "-T4"]
    max_ports: 10000
    
  nuclei:
    templates_dir: "/nuclei-templates"
    severity: ["critical", "high", "medium"]
    
reporting:
  formats: ["pdf", "html", "json"]
  templates_dir: "templates/reports"
  
compliance:
  frameworks: ["OWASP", "PCI-DSS", "GDPR"]
```

## Core API Usage

### Authentication

```python
import requests

API_BASE = "http://localhost:8000"

# Login
response = requests.post(
    f"{API_BASE}/api/v1/auth/login",
    json={"username": "admin", "password": "admin"}
)
token = response.json()["access_token"]

# Use token in headers
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}
```

### Create and Execute Scan

```python
# Create a new scan
scan_data = {
    "target": "example.com",
    "scan_type": "full",  # Options: quick, full, custom
    "tools": ["nmap", "nuclei", "whatweb"],
    "safety_level": 1,  # 0-3
    "options": {
        "ports": "1-1000",
        "aggressive": False,
        "parallel": True
    }
}

response = requests.post(
    f"{API_BASE}/api/v1/scans",
    json=scan_data,
    headers=headers
)
scan_id = response.json()["scan_id"]
print(f"Scan created: {scan_id}")

# Get scan status
status = requests.get(
    f"{API_BASE}/api/v1/scans/{scan_id}",
    headers=headers
).json()
print(f"Status: {status['state']}")  # IDLE, PLANNING, EXECUTING, etc.

# Get results
results = requests.get(
    f"{API_BASE}/api/v1/scans/{scan_id}/results",
    headers=headers
).json()

print(f"Findings: {len(results['findings'])}")
for finding in results['findings']:
    print(f"  - {finding['severity']}: {finding['title']}")
```

### WebSocket Real-Time Updates

```python
import asyncio
import websockets
import json

async def monitor_scan(scan_id, token):
    uri = f"ws://localhost:8000/api/v1/ws/scans/{scan_id}?token={token}"
    
    async with websockets.connect(uri) as websocket:
        async for message in websocket:
            data = json.loads(message)
            print(f"[{data['type']}] {data['message']}")
            
            if data['type'] == 'completed':
                break

# Run
asyncio.run(monitor_scan(scan_id, token))
```

## Python SDK Usage

### Basic Scan Workflow

```python
from zen_pentest import ZenClient
from zen_pentest.agents import AutonomousAgent
from zen_pentest.tools import ToolRegistry

# Initialize client
client = ZenClient(
    api_url="http://localhost:8000",
    api_key=os.getenv("ZEN_API_KEY")
)

# Quick scan
scan = client.create_scan(
    target="example.com",
    scan_type="quick"
)
scan.wait_for_completion(timeout=600)
report = scan.get_report(format="pdf")
report.save("report.pdf")

# Advanced scan with custom agent
agent = AutonomousAgent(
    llm="gpt-4",
    tools=["nmap", "nuclei", "sqlmap"],
    safety_level=2,
    memory_enabled=True
)

result = agent.run_scan(
    target="https://example.com",
    objectives=[
        "Map attack surface",
        "Identify web vulnerabilities",
        "Test for SQL injection"
    ]
)

print(f"State transitions: {result.state_history}")
print(f"Findings: {len(result.findings)}")
print(f"Risk score: {result.risk_score}")
```

### Custom Tool Integration

```python
from zen_pentest.tools import BaseTool
from zen_pentest.schemas import ToolResult

class CustomScannerTool(BaseTool):
    name = "custom_scanner"
    description = "Custom vulnerability scanner"
    risk_level = 1
    
    def validate_input(self, target: str) -> bool:
        # Validate target (no private IPs, etc.)
        return self.is_public_target(target)
    
    def execute(self, target: str, **kwargs) -> ToolResult:
        # Your custom logic
        results = self._run_custom_scan(target)
        
        return ToolResult(
            success=True,
            data=results,
            metadata={"tool": self.name, "target": target}
        )
    
    def parse_output(self, raw_output: str) -> dict:
        # Parse tool output
        return {"vulnerabilities": [...]}

# Register custom tool
registry = ToolRegistry()
registry.register(CustomScannerTool())

# Use in scan
agent = AutonomousAgent(tools=["custom_scanner"])
result = agent.run_scan(target="example.com")
```

### Multi-Agent Coordination

```python
from zen_pentest.agents import ResearcherAgent, AnalystAgent, CoordinatorAgent

# Create specialized agents
researcher = ResearcherAgent(
    tools=["subfinder", "httpx", "whatweb"]
)

analyst = AnalystAgent(
    tools=["nuclei", "ffuf", "nikto"]
)

# Coordinate workflow
coordinator = CoordinatorAgent(
    agents=[researcher, analyst],
    strategy="sequential"  # or "parallel"
)

result = coordinator.execute_mission(
    target="example.com",
    depth=3
)

# Researcher findings feed into analyst
for finding in result.findings:
    print(f"{finding.agent}: {finding.title} [{finding.severity}]")
```

## CLI Usage

### Basic Commands

```bash
# Run quick scan
zen-pentest scan -t example.com --quick

# Full scan with specific tools
zen-pentest scan -t example.com \
  --tools nmap,nuclei,sqlmap \
  --safety-level 2 \
  --output report.pdf

# Check scan status
zen-pentest status --scan-id abc123

# List all scans
zen-pentest list --status running

# Generate report from existing scan
zen-pentest report --scan-id abc123 \
  --format pdf \
  --output custom-report.pdf \
  --compliance OWASP,PCI-DSS

# Export results
zen-pentest export --scan-id abc123 \
  --format json \
  --output results.json
```

### Advanced CLI Features

```bash
# Custom agent configuration
zen-pentest scan -t example.com \
  --agent-config config/custom-agent.yaml \
  --max-iterations 15 \
  --memory enabled

# Resume interrupted scan
zen-pentest resume --scan-id abc123

# Benchmark mode
zen-pentest benchmark \
  --scenario htb-academy \
  --compare manual,autopentester

# Tool inventory check
zen-pentest tools --check

# Database migration
zen-pentest db upgrade head
```

## Common Patterns

### Safe Reconnaissance Scan

```python
# Level 0: Read-only information gathering
client = ZenClient()
scan = client.create_scan(
    target="example.com",
    safety_level=0,
    tools=["whois", "dns", "subfinder", "whatweb"]
)
results = scan.execute()

# Safe for production environments
print(f"Subdomains found: {len(results.subdomains)}")
print(f"Technologies: {results.technologies}")
```

### Vulnerability Assessment with Validation

```python
# Level 2: Active scanning + validation
scan = client.create_scan(
    target="https://example.com",
    safety_level=2,
    tools=["nuclei", "ffuf"],
    options={
        "validate_findings": True,
        "false_positive_filter": True,
        "risk_scoring": True
    }
)

results = scan.execute()

# Only validated, high-confidence findings
critical_findings = [
    f for f in results.findings
    if f.severity == "critical" and f.validated
]

for finding in critical_findings:
    print(f"CVSS {finding.cvss_score}: {finding.title}")
    print(f"Evidence: {finding.evidence_path}")
    print(f"Remediation: {finding.remediation}")
```

### CI/CD Integration

```python
# .github/workflows/security-scan.yml
from zen_pentest.ci import GitHubAction

action = GitHubAction()
result = action.run_scan(
    target=os.getenv("STAGING_URL"),
    fail_on_severity="high",
    report_format="sarif"
)

# Automatically creates GitHub Security Advisory
if result.has_findings:
    action.create_security_advisory(result.findings)
    exit(1 if result.severity >= "high" else 0)
```

### Compliance Reporting

```python
from zen_pentest.reporting import ComplianceMapper

# Generate compliance report
mapper = ComplianceMapper(frameworks=["OWASP", "PCI-DSS", "GDPR"])
compliance_report = mapper.map_findings(scan.findings)

print(f"OWASP Top 10 coverage: {compliance_report.owasp.coverage}%")
print(f"PCI-DSS gaps: {compliance_report.pci_dss.gaps}")

# Export for auditors
compliance_report.export("audit-report.pdf", template="official")
```

## Troubleshooting

### Common Issues

**Tool execution fails:**
```bash
# Check tool installation
zen-pentest tools --check

# Verify Docker sandbox
docker ps | grep zen-pentest-sandbox

# Check tool permissions
zen-pentest tools --test nmap
```

**Database connection errors:**
```python
# Test database connection
from zen_pentest.db import check_connection

if not check_connection():
    print("Database unreachable. Check DATABASE_URL in .env")
    
# Reset database
zen-pentest db reset --force
```

**Agent timeout:**
```python
# Increase timeout and iterations
agent = AutonomousAgent(
    timeout=600,  # 10 minutes
    max_iterations=20,
    enable_checkpoints=True  # Resume on failure
)
```

**High memory usage:**
```bash
# Limit concurrent scans
export MAX_CONCURRENT_SCANS=2

# Disable memory feature
export ENABLE_MEMORY=false

# Clear Redis cache
redis-cli FLUSHDB
```

**False positives:**
```python
# Enable stricter validation
scan = client.create_scan(
    target="example.com",
    options={
        "validation_threshold": 0.8,  # 80% confidence
        "llm_voting": True,  # Multi-model consensus
        "require_evidence": True
    }
)
```

### Debug Mode

```bash
# Enable verbose logging
export ZEN_DEBUG=true
export LOG_LEVEL=DEBUG

# Run scan with debug output
zen-pentest scan -t example.com --debug --log-file debug.log

# Check logs
tail -f logs/zen-pentest.log
```

### Testing Installation

```python
# Run self-test suite
from zen_pentest.tests import run_diagnostics

diagnostics = run_diagnostics()
print(diagnostics.report())

# Expected output:
# ✓ Database: Connected
# ✓ Redis: Available
# ✓ Tools: 72/72 installed
# ✓ API: Responding
# ✓ Agents: Initialized
```

## Safety and Legal Considerations

**IMPORTANT:** Only scan systems you own or have explicit written permission to test.

```python
# Built-in safety checks
from zen_pentest.safety import SafetyValidator

validator = SafetyValidator()

# Blocks private IPs, localhost, cloud metadata endpoints
if not validator.is_safe_target("10.0.0.1"):
    raise ValueError("Cannot scan private network")

# Requires VPN for Level 3 (exploit validation)
if safety_level == 3 and not validator.is_vpn_active():
    raise ValueError("VPN required for Level 3 scans")
```

Configure authorized targets in `config/authorized-targets.yaml`:

```yaml
authorized_targets:
  - domain: "*.example.com"
    owner: "Your Company"
    expiry: "2026-12-31"
    max_safety_level: 3
```

## Resources

- **Documentation**: https://shadd0wtaka.github.io/Zen-Ai-Pentest/
- **API Reference**: http://localhost:8000/docs (when running)
- **GitHub**: https://github.com/SHAdd0WTAka/Zen-Ai-Pentest
- **Discord**: https://discord.gg/BSmCqjhY
- **Live Demo**: https://zen-ai-pentest.pages.dev

## Advanced Topics

See additional documentation:
- [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - Architecture deep dive
- [README_ENHANCED_TOOLS.md](README_ENHANCED_TOOLS.md) - Tool integration guide
- [docs/TESTING.md](docs/TESTING.md) - Testing framework
- [ROADMAP_2026.md](ROADMAP_2026.md) - Future features