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

Loading

---

✨ Features

🤖 Autonomous AI ReAct Pattern: Reason → Act → Observe → Reflect State Machine: IDLE → PLANNING → EXECUTING → OBSERVING → REFLECTING → COMPLETED Memory System: Short-term, long-term, context windows Self-Correction: Retry logic & adaptive planning Human-in-the-Loop: Optional pause for critical decisions	🎯 Risk Engine False Positive Reduction: Bayesian + multi-model voting Business Impact: Financial, compliance, reputation scoring CVSS/EPSS: Industry-standard vulnerability assessment LLM Voting: Multi-model consensus for accuracy Priority Ranking: Automated finding prioritization	🔒 Exploit Validation Sandboxed Execution: Docker isolated testing 4-Level Safety: Read-Only → Full exploitation Evidence Collection: Screenshots, HTTP captures, PCAP Chain of Custody: Complete audit trail Auto-Remediation: Fix recommendations
🧠 AI Persona System 11 Specialized Personas: Recon, Exploit, Report, Audit, Social, Network, Mobile, Red Team, ICS, Cloud, Crypto CLI Tool: k-recon, k-exploit, k-chat REST API: Flask-based with WebSocket Web UI: Modern browser interface Screenshot Analysis: AI-powered image analysis	🗺️ Attack Path Analysis Visual Graphs: Interactive Cytoscape.js visualization Entry Point Mapping: Track all attack vectors Crown Jewel Analysis: Critical asset identification Attack Simulation: Test paths without execution Risk Scoring: Difficulty & impact assessment	📊 Benchmarking Competitor Comparison: vs PentestGPT, AutoPentest Test Scenarios: HTB, OWASP WebGoat, DVWA Metrics: Time-to-find, coverage, false positive rate Visual Reports: Charts & statistical analysis CI Integration: Automated regression testing

🔧 72+ Integrated Security Tools

Category	Tools
Network Scanning	nmap · masscan · scapy · tshark · tcpdump · netdiscover · arp-scan
Web Security	BurpSuite · SQLMap · Gobuster · OWASP ZAP · FFuF · Nikto · WAFW00F · WhatWeb · Nuclei
Exploitation	Metasploit Framework · SearchSploit
Brute Force	Hydra · Hashcat · John · Ncrack
Reconnaissance	Amass · Nuclei · TheHarvester · Subfinder · HTTPX · Sherlock · Scout
Active Directory	BloodHound · NetExec · Responder · ldapsearch · enum4linux
OSINT	Sherlock · Ignorant · TheHarvester · Scout
Code Analysis	Semgrep · TruffleHog · Gitleaks · Bandit
Container	Trivy · Docker · Kubectl
Wireless	Aircrack-ng · airmon-ng · airodump-ng · aireplay-ng
System	Netcat · Socat · OpenSSL · Proxychains · Tor

🧩 MCP Server Infrastructure

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

Server	Purpose	Tools
omni-ai	AI chat via OmniRoute (free models)	chat, stream, vision, web_extract, list_models
qterminal	Shell/Docker orchestration	spawn, exec, kill, network, images, agents
zen-agents	11-agent orchestration	agent_run, workflow_create, full_audit, agent_list
metasploit	Metasploit RPC connector	module_search, module_execute, session_list
vpn-killswitch	Connection-loss failover	check, rotate, status, set_proxy, history
obscura	Encrypted secret vault	store, get, list, delete, init, export
ip-tracker	Visitor IP tracking	check_visitors, resolve_ip, my_public_ip

📚 Skills System (95 Skills)

Type	Count	Description
Framework	5	zen-framework, agents-usage, tools, risk-engine, workflow
Platform	9	devops-docker, ci-cd, rag-vector, browser-automation, multi-language, security-review, bash, ai-delegation, solidity
Tools	39	nmap, masscan, nuclei, sqlmap, metasploit, ffuf, gobuster, bloodhound, hydra, zap, nikto, amass, subfinder, sherlock, trivy, semgrep, burpsuite, etc.
Modules	42	exploit modules (xss, sqli, ssrf, lfi, deserialization), osint modules (dns, email, whois, cert), scanners, reporting

🤖 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

🐳 Docker (Full Stack) 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 Service Port Web Terminal :8080 OmniRoute AI :20128 Hermes Agent — WhatsApp Bot :23001	📦 Local Install 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
🤖 AI Agents (CLI) # 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	📱 WhatsApp Bot # 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

Loading

---

🤖 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

Loading

---

🔄 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

Loading

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

Loading

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"]

Loading

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"]

Loading

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

Loading

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

Loading

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

Loading

---

🧪 Test Suite

Metric	Value	Status
Test Files	1,145+	✅
Total Tests	43,000+	✅ Verified
Coverage	~10%	⚠️ Improving
Target	80%+	🎯 Goal

# 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

Level	Description	Tools
SAFE (0)	Recon only	whois, dns, subdomain
NORMAL (1)	Standard scanning	+ nmap, nuclei
ELEVATED (2)	Light exploitation	+ sqlmap, exploit
AGGRESSIVE (3)	Full exploitation	+ pivot, lateral

---

🔧 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

Document	Description
Architecture	Complete system design
API Reference	REST + WebSocket endpoints
Installation	Docker · Local · Production
Docker Guide	Deployment & configuration
Security Audit	Security assessment
Agent Guide	AI development partner guide
Benchmarks	Performance results
Roadmap 2026	Future plans

---

🌐 Community

Platform	Link
🎮 Discord	discord.gg/zJZUJwK9AC
🐙 GitHub	github.com/SHAdd0WTAka/Zen-Ai-Pentest
🌍 Website	zen-ai-pentest.pages.dev
📊 Dashboard	live dashboard

_{📱 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.