Edit .env: set OPENCODEAPIKEY=oc_xxx

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

🧩 MCP Server Infrastructure

8 MCP servers for AI-tool integration, registered in opencode.jsonc:

📚 Skills System (95 Skills)

🤖 WhatsApp Bot

• E2E encrypted via @whiskeysockets/baileys (QR code pairing)
• /ask <prompt> — AI-powered security Q&A via OmniRoute
• /voice <text> — TTS response via edge-tts + ffmpeg
• QR displayed in web UI at http://localhost:8080/qr.html

🛡️ VPN Killswitch

Automatic connection-loss detection and VPN rotation:

• Detects: 429 (rate limit), 5xx (server error), timeouts, connection refused
• Supports: WireGuard and SOCKS5 proxy
• Auto-rotates VPN endpoint on failure
• Configurable check interval (default: 15s)

🚀 Quick Start

git clone https://github.com/SHAdd0WTAka/zen-ai-pentest.git
cd zen-ai-pentest
cp .env.example .env
# Edit .env: set OPENCODE_API_KEY=oc_xxx
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

# 11 specialized agent personas
deep-recon --target example.com
deep-exploit --target example.com --force
deep-audit --target example.com --phases recon,scan,exploit,report
deep-report --scan-id wf-abc123 --format pdf

# QR pairing in browser
open http://localhost:8080/qr.html
# Commands:
/ask Scan example.com and find vulnerabilities
/voice Describe the OWASP Top 10

💻 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

🤖 AI Orchestration 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 TB
    subgraph "🌐 User Interface"
        WEB["Web Terminal :8080"]
        CLI["CLI deep-*"]
        WA["WhatsApp Bot"]
        API["REST API :8000"]
    end

    subgraph "🧠 AI Inference"
        OR["OmniRoute Proxy :20128"]
        FREE["oc/deepseek-v4-flash-free"]
        PAID["oc/gpt-4o · claude-3 · llama-3"]
        HA["Hermes Agent v0.15.2<br/>95 skills · agency-agents"]
    end

    subgraph "🔌 MCP Servers"
        OA["omni-ai<br/>chat+vision+tools"]
        QT["qterminal<br/>shell+docker"]
        ZA["zen-agents<br/>11 agents"]
        MS["metasploit<br/>MSF RPC"]
        VK["vpn-killswitch<br/>failover"]
        OB["obscura<br/>vault"]
        IT["ip-tracker<br/>geo+visitors"]
    end

    subgraph "🤖 Agent Pool (ReAct Loop)"
        coord["AgentCoordinator<br/>IDLE→PLANNING→EXECUTING→<br/>OBSERVING→REFLECTING→COMPLETED"]
        guard["Guardrails<br/>IP blocking · Risk 0-3 · Timeout"]
        A1["Recon"]
        A2["Exploit"]
        A3["Analysis"]
        A4["RedTeam"]
        A5["Social · Network · Cloud<br/>ICS · Mobile · Crypto · Report"]
    end

    subgraph "🔧 Security Toolkit"
        TOOLS["72+ Tools<br/>nmap · masscan · nuclei · sqlmap · metasploit<br/>ffuf · gobuster · hydra · bloodhound<br/>responder · amass · subfinder · trivy<br/>semgrep · trufflehog · zap · nikto · burpsuite"]
    end

    WEB & CLI & WA & API --> OR
    OR --> FREE & PAID
    FREE & PAID --> HA
    HA --> OA & QT & ZA & MS & VK & OB & IT
    OA & QT & ZA & MS & VK & OB & IT --> coord
    coord --> guard
    guard --> A1 & A2 & A3 & A4 & A5
    A1 & A2 & A3 & A4 & A5 --> TOOLS

🔄 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
├── agents/                # AI Agent Implementations
│   ├── react_agent.py    # Core ReAct pattern agent (Reason→Act→Observe→Reflect)
│   ├── agent_coordinator_v3.py # Multi-agent workflow engine (11 personas)
│   ├── guardrails.py     # IP/Domain/risk-level safety filters
│   └── cli/              # CLI tools: deep-recon, deep-exploit, deep-report, deep-audit
├── core/                  # Framework Core
├── tools/                 # 72+ Security Tool Integrations
├── risk_engine/           # Risk Analysis (CVSS, EPSS, false positive detection)
├── modules/               # High-Level Modules (exploit, osint, scanners, reporting)
│   ├── tool_orchestrator.py  # Integration Bridge for containerized tools
│   ├── exploit_modules/   # Auth bypass, command injection, deserialization, SSRF, XSS, XXE, SQLi
│   └── osint_modules/    # Cert transparency, DNS enum, email harvester, whois
├── mcp/                   # MCP Servers (8 total)
│   ├── omni-ai/          # AI chat via OmniRoute proxy
│   ├── qterminal/        # Shell + Docker orchestration
│   ├── zen-agents/       # 11-agent orchestration
│   ├── metasploit/       # Metasploit RPC connector
│   ├── vpn-killswitch/   # Connection-loss VPN rotation
│   ├── obscura/          # Encrypted secret vault
│   └── ip-tracker/       # Visitor IP tracking
├── skills/                # 95 Hermes-compatible skills (tool-specific SKILL.md)
│   ├── tool-*/           # 39 tool skills (nmap, sqlmap, nuclei, etc.)
│   ├── module-*/         # 42 module skills (xss, sqli, osint, etc.)
│   └── zen-*/            # 5 framework skills (architecture, agents, workflow)
├── web_ui/                # Frontend
│   ├── terminal/         # WebShell (FastAPI + PTY over WebSocket + Cloudflare tunnel)
│   │   ├── server.py     # Terminal server with 2FA auth
│   │   ├── static/       # login.html, qr.html (WhatsApp pairing)
│   │   └── Dockerfile
│   ├── whatsapp-bot/     # E2E WhatsApp bot (Baileys + /ask AI + /voice TTS)
│   └── dashboard/        # React · Vite · TypeScript
├── docker/                # Dockerfiles
│   ├── hermes/            # Hermes Agent container
│   ├── omniroute/         # OmniRoute API proxy
│   └── vpn-proxy/         # VPN proxy container
├── database/              # PostgreSQL Models
├── reports/               # PDF · HTML · DOCX Generator
├── docker-compose.yml     # 6 services (terminal, whatsapp, omniroute, hermes, vpn, wg)
├── opencode.jsonc         # OpenCode config with all 8 MCP servers
├── .opencode/agents/      # 267 agent prompt files
├── tests/                 # 43,000+ Tests
└── 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.