Execute tool

Professional AI-Powered Penetration Testing Framework
Autonomous security assessment powered by state-of-the-art language models

Features • Quick Start • Architecture • Pipelines • Security • Docs

🔥 Overview

Zen-AI-Pentest is an autonomous, AI-driven penetration testing framework that combines cutting-edge large language models with 72+ professional security tools. Built for security professionals, bug bounty hunters, and enterprise red teams.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#58a6ff', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#58a6ff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph TB
    subgraph "🌐 Client Interface"
        WebUI["React Dashboard<br/>Cloudflare Pages"]
        CLI["Python CLI"]
        API["REST API + WebSocket"]
    end

    subgraph "⚡ API Gateway"
        FastAPI["FastAPI Server"]
        Auth["JWT / RBAC Auth"]
        WsMgr["WebSocket Manager"]
    end

    subgraph "🧠 AI Orchestrator"
        AgentMgr["Agent Manager"]
        Guardrails["🛡️ Guardrails<br/>IP/Domain Filter"]
        TaskQ["📊 Task Queue"]
        Risk["⚠️ Risk Levels 0-3"]
        State["📈 State Machine<br/>ReAct Pattern"]
    end

    subgraph "🤖 Agent Pool"
        A1["Agent #1<br/>Recon"]
        A2["Agent #2<br/>Exploit"]
        A3["Agent #3<br/>Report"]
        AN["Agent #N<br/>Custom"]
    end

    subgraph "🔧 Security Toolkit"
        Nmap["nmap · masscan"]
        Web["nuclei · sqlmap · zap · ffuf"]
        Exploit["Metasploit · SearchSploit"]
        Recon["amass · subfinder · httpx"]
        AD["BloodHound · NetExec"]
        OSINT["sherlock · theHarvester"]
    end

    subgraph "📊 Analysis & Reporting"
        Evidence["📋 Evidence Collection<br/>Cryptographic Signatures"]
        Attack["🗺️ Attack Path Analysis<br/>Cytoscape.js Graphs"]
        Report["📄 Report Generator<br/>PDF · HTML · DOCX · JSON"]
        Compliance["📋 Compliance Mapping<br/>ISO 27001 · PCI DSS · NIST"]
        RiskScoring["🎯 Risk Scoring<br/>CVSS · EPSS · Bayesian Filter"]
    end

    subgraph "💾 Data Layer"
        PG[("🐘 PostgreSQL<br/>Persistent State")]
        Redis[("⚡ Redis<br/>Cache & Queue")]
        FS[("📁 File Storage<br/>Reports & Evidence")]
    end

    WebUI --> FastAPI
    CLI --> FastAPI
    API --> FastAPI
    FastAPI --> Auth
    Auth --> AgentMgr
    AgentMgr --> Guardrails
    Guardrails --> TaskQ
    TaskQ --> Risk
    Risk --> State
    State --> A1 & A2 & A3 & AN
    A1 --> Nmap & Recon
    A2 --> Web & Exploit
    A3 --> AD & OSINT
    AN --> Nmap & Web
    Nmap --> Evidence
    Web --> Attack
    Exploit --> Evidence
    Attack --> Report
    State --> Report
    Report --> Compliance
    Report --> RiskScoring
    Evidence --> PG
    Attack --> PG
    Compliance --> PG
    RiskScoring --> Redis
    Report --> FS

✨ Features

🔧 72+ Integrated Security Tools

🚀 Quick Start

git clone https://github.com/SHAdd0WTAka/zen-ai-pentest.git
cd zen-ai-pentest
cp .env.example .env
docker-compose up -d

pip install -r requirements.txt
python database/models.py
python api/main.py
# Subdomain scanner
python scan_target_subdomains.py example.com
# Advanced CLI
python tools/subdomain_enum.py example.com --advanced

bash api/QUICKSTART.sh
source tools/setup_aliases.sh
k-recon "Target: example.com"
k-exploit "Write SQLi scanner"
k-chat

python scripts/setup_vms.py --kali
# See docs/setup/VIRTUALBOX_SETUP.md

💻 Usage

Python API

from agents.react_agent import ReActAgent, ReActAgentConfig

config = ReActAgentConfig(max_iterations=10, use_vm=True)
agent = ReActAgent(config)
result = agent.run(target="example.com",
                   objective="Comprehensive security assessment")
print(agent.generate_report(result))

REST API

# Auth
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Create scan
curl -X POST http://localhost:8000/scans \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Network Scan","target":"192.168.1.0/24","scan_type":"network"}'

# Execute tool
curl -X POST http://localhost:8000/tools/execute \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"tool_name":"nmap_scan","target":"scanme.nmap.org","parameters":{"ports":"22,80,443"}}'

# Generate report
curl -X POST http://localhost:8000/reports \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"scan_id":1,"format":"pdf","template":"default"}'

WebSocket (Real-Time)

const ws = new WebSocket("ws://localhost:8000/ws/scans/1");
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Scan update:", data);
};

🏗️ Architecture

System Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#58a6ff', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#58a6ff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph LR
    subgraph "Client"
        WEB["🌐 Web UI<br/>React · Cloudflare"]
        CLI["💻 CLI · Python"]
        API_CLIENT["🔌 REST Client"]
    end

    subgraph "API Gateway"
        FASTAPI["FastAPI + WebSocket"]
        AUTH["🔐 JWT/RBAC"]
        WS["📡 WebSocket"]
    end

    subgraph "Orchestrator"
        G["🛡️ Guardrails"]
        TQ["📊 Task Queue"]
        RL["⚠️ Risk 0-3"]
        SM["📈 State Machine"]
    end

    subgraph "Agents"
        A1["🤖 Agent Pool<br/>Docker Sandbox"]
    end

    subgraph "Tools"
        TOOLS["🔧 72+ Tools<br/>nmap · nuclei · sqlmap<br/>metasploit · burp · hydra"]
    end

    subgraph "Analysis"
        EV["📋 Evidence"]
        AP["🗺️ Attack Path"]
        CC["🔗 Chain of Custody"]
        COMP["📊 Compliance"]
        REP["📄 Reports"]
        RS["🎯 Risk Scoring"]
    end

    subgraph "Data"
        PG[("🐘 PostgreSQL")]
        RD[("⚡ Redis")]
        FS[("📁 File Store")]
    end

    WEB --> FASTAPI
    CLI --> FASTAPI
    API_CLIENT --> FASTAPI
    FASTAPI --> AUTH
    AUTH --> WS
    WS --> G
    G --> TQ --> RL --> SM
    SM --> A1
    A1 --> TOOLS
    TOOLS --> EV & AP
    SM --> REP
    EV --> CC
    AP --> COMP
    CC --> RS
    EV --> PG
    AP --> PG
    COMP --> PG
    RS --> RD
    REP --> FS

🔄 CI/CD Pipelines

All pipeline diagrams use Mermaid — rendered automatically by GitHub.

1. 🧪 Tests Pipeline

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#3fb950', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#3fb950', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#3fb950', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#3fb950', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph LR
    TRIG1["push main/develop"] --> TEST
    TRIG2["pull_request main/develop"] --> TEST
    TRIG3["workflow_dispatch"] --> TEST
    TEST["🧪 test (matrix 3.11, 3.12)<br/>pytest · 43k+ tests"] --> RESULT["✅ Test Summary"]
    style TEST fill:#3fb950,stroke:#1a7f37,color:#fffffffff

2. 📊 Codecov Coverage Pipeline

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#3fb950', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#3fb950', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#3fb950', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#3fb950', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph LR
    TRIG1["pull_request"] --> COV
    TRIG2["workflow_dispatch"] --> COV
    COV["📊 coverage<br/>pytest --cov=core,agents,api,tools<br/>autonomous,risk_engine,modules,web_ui"] --> UPLOAD["📤 Upload to Codecov"]
    COV --> ARTIFACT["📦 Upload artifact"]
    COV --> PR["💬 Comment PR"]
    style COV fill:#3fb950,stroke:#1a7f37,color:#fffffffff

3. 🔒 Security Scan Pipeline

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#f85149', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#f85149', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#f85149', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#f85149', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph TB
    TRIG1["pull_request main/develop"] --> SEC
    TRIG2["schedule daily 6am"] --> SEC
    TRIG3["workflow_dispatch"] --> SEC

    subgraph SEC["🔒 Security Scan"]
        DEP["📦 Dependency Scan<br/>Safety · pip-audit"]
        SECRET["🔑 Secret Detection<br/>TruffleHog · GitLeaks · GitGuardian"]
        SAST["🔍 SAST Analysis<br/>Bandit · Semgrep"]
        IAC["🏗️ IaC Scan<br/>Checkov · Trivy Config"]
        SCORE["📈 OSSF Scorecard"]
    end

    DEP --> SUMMARY["📋 Security Summary"]
    SECRET --> SUMMARY
    SAST --> SUMMARY
    IAC --> SUMMARY
    SCORE --> SUMMARY
    SAST --> SARIF1["📎 Upload Semgrep SARIF"]
    IAC --> SARIF2["📎 Upload Checkov SARIF"]
    IAC --> SARIF3["📎 Upload Trivy SARIF"]
    SCORE --> SARIF4["📎 Upload Scorecard SARIF"]
    DEP --> ART1["📦 Upload Reports"]

4. ✅ CodeQL Analysis

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#58a6ff', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#58a6ff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph LR
    TRIG["schedule weekly Sunday"] --> CQL
    subgraph CQL["CodeQL Advanced"]
        CHECKOUT["📥 Checkout"]
        INIT["⚙️ Initialize CodeQL<br/>security-extended + security-and-quality"]
        BUILD["🔨 Autobuild"]
        ANALYZE["🔬 Perform Analysis"]
    end
    CQL --> RES["✅ SARIF Results"]

5. 🚀 Deploy Pipeline

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#d29922', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#d29922', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#d29922', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#d29922', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph TB
    TRIG1["release published"] --> DEPLOY
    TRIG2["workflow_dispatch staging/prod"] --> DEPLOY

    subgraph DEPLOY["Deploy Pipeline"]
        CHECK["✅ pre-deploy-check<br/>pytest + bandit"]
        STAGE["🧪 deploy-staging<br/>staging.pentest.example.com"]
        PROD["🚀 deploy-production<br/>pentest.example.com"]
    end

    CHECK --> STAGE
    STAGE --> PROD
    PROD --> SLACK["📬 Notify Slack"]
    CHECK --> SUM["📋 deploy-summary"]
    STAGE --> SUM
    PROD --> SUM

6. 📦 Release Pipeline

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#bc8cff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#bc8cff', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#bc8cff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#bc8cff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph TB
    TRIG["workflow_dispatch<br/>version + prerelease"] --> PRE

    PRE["📋 pre-release-checks<br/>version · changelog"] --> BUILD
    PRE --> CHLOG["📝 changelog"]
    PRE --> REL["🏷️ github-release"]

    BUILD["📦 build<br/>python -m build · twine"] --> REL
    REL --> PYPI["⬆️ pypi-publish<br/>twine upload"]
    REL --> DOCKER["🐳 docker build & push<br/>ghcr.io · amd64 + arm64"]
    REL --> DOCS["📚 docs<br/>mkdocs · mkdocs-material"]

    PYPI --> POST["📬 post-release<br/>discussion · milestone"]
    DOCKER --> NOTIFY["🔔 notify<br/>Slack + Discord"]
    DOCKER --> SUMMARY["📋 release-summary"]
    PYPI --> NOTIFY
    PYPI --> SUMMARY

7. ⚙️ CI Pipeline (Legacy)

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#8b949e', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#8b949e', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#8b949e', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#8b949e', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
graph TB
    TRIG["workflow_dispatch"] --> CI
    subgraph CI["CI Pipeline (Legacy)"]
        T["🧪 test<br/>matrix 3.10 · 3.11 · 3.12"]
        L["✨ lint<br/>black · isort · flake8 · ruff"]
        S["🔒 security-scan<br/>bandit · safety"]
    end
    T --> CG["📊 coverage-gate<br/>check >= 80%"]
    T --> SUM["📋 ci-summary"]
    L --> SUM
    S --> SUM
    CG --> SUM

🧪 Test Suite

# All tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=. --cov-report=html --cov-report=term

# Unit tests
pytest tests/unit/ -v

# Integration
pytest tests/integration/ -v

# Security
pytest tests/security/ -v

# Exclude slow
pytest tests/ -m "not slow" -v

🛡️ Security

Built-in Protections

• ✅ Private IP Blocking: Prevents scanning 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
• ✅ Loopback Protection: Blocks 127.x.x.x and ::1
• ✅ Local Domain Filter: Prevents .local, .internal, localhost
• ✅ Risk Level Control: Restricts tools by safety level (0-3)
• ✅ Rate Limiting: Prevents abuse

Risk Levels

🔧 Configuration

Option 1: Obsidian Vault (Recommended)

bash mcp/obsidian/setup.sh
code ~/Documents/Obsidian\ Vault/Secrets/secrets.yaml

Option 2: Environment Variables

cp .env.example .env
nano .env
source .env

📁 Project Structure

zen-ai-pentest/
├── api/                   # FastAPI Backend
│   ├── main.py           # API server · routes · middleware
│   ├── auth.py           # JWT authentication · RBAC
│   └── websocket.py      # Real-time scan updates
├── agents/                # AI Agent Implementations
│   ├── react_agent.py    # Core ReAct pattern agent
│   ├── react_agent_vm.py # VM-backed agent
│   └── personas/         # 11 specialized AI personas
├── core/                  # Framework Core
│   ├── orchestrator.py   # Workflow orchestration
│   ├── models.py         # Data models
│   └── cache.py          # Multi-tier caching
├── tools/                 # 72+ Security Tools
│   ├── nmap/             # Network scanning
│   ├── nuclei/           # Vulnerability detection
│   ├── sqlmap/           # SQL injection
│   ├── metasploit/       # Exploitation framework
│   └── ...               # 68+ more integrations
├── risk_engine/           # Risk Analysis
│   ├── cvss.py           # CVSS scoring
│   ├── epss.py           # EPSS probability
│   └── false_positive_engine.py  # Bayesian filtering
├── modules/               # High-Level Modules
│   ├── scanner/          # Automated scanning
│   └── exploit_modules/  # Exploit validation
├── web_ui/                # Frontend
│   ├── frontend/         # React · Vite · TypeScript
│   └── dashboard/        # Analytics dashboard
├── database/              # PostgreSQL Models
├── reports/               # PDF · HTML · DOCX Generator
├── docker/                # Docker Compose · Dockerfiles
├── tests/                 # 43,000+ Tests
│   ├── unit/             # Component tests
│   ├── integration/      # E2E workflows
│   └── security/         # SAST/DAST validation
└── docs/                  # Documentation

📚 Documentation

🌐 Community

_{📱 Scan QR codes for instant mobile access}

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

👥 Authors

@SHAdd0WTAka Founder · Lead Developer

Kimi AI AI Development Partner

📄 License

MIT License — see LICENSE.

⚠️ IMPORTANT: For authorized security testing only. Always obtain proper permission before testing any system you do not own.