Top AI Repos — open-source AI, indexed and scored

Top AI Repos tracks AI repositories on GitHub and answers two different questions about each one: is it moving right now, and would you bet a product on it.

SHAdd0WTAka/Zen-Ai-Pentest

🛡⚔️AI-Powered Penetration Testing Framework with automated vulnerability scanning, multi-agent system, and compliance reporting🛡⚔️

79MITPython

View on GitHub Website

Stars: 435
Forks: 77
Watchers: 5
Open issues: 0
Contributors: —

Star history, last 90 days+2 over 3 snapshots

2026-07-31 · 4332026-08-06 · 435

Star history, last 90 days
Date	Stars
2026-07-31	433
2026-08-05	435
2026-08-06	435

Today

— stars today

This week

— stars this week

This month

— stars this month

Momentum

5.0

growth rate 0.00%/day

From the README

Zen-AI-Pentest

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

🤖 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

🤖 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

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

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
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.

Rendered by GitHub from the current README

Read on GitHub

Top contributors

No contributor data yet — it is fetched during the contributor sync pass.

Quality score

Would you bet a product on this? Bounded 0–100 and slow moving.

79/10079

Maintenance: 100%; How recently the default branch was pushed to
Releases: 63%; Recency and cadence of tagged releases
Community: 20%; Contributor breadth and bus factor
Issue backlog: 100%; Open issues measured against the size of the audience
Documentation: 100%; README depth, plus a homepage and topics
Licensing: 100%; How freely the code can be adopted

What to know before adopting

Nothing flagged — maintained, documented and cleanly licensed.
Usable in commercial products with attribution.

Details

Created: 6 months ago
Last push: 19 hours ago
Last release: 6 months ago
Release tag: v3.0.0
Releases in the last year: 9
Default branch: main
Size: 100k KB
Owner type: User
Owner location: WSL-KALi-Terminal-Mount-evrything-but-always-IN-Siem-OPERATIONS/soc/PolyciesandRegulations/but_dondt_expect_to_much_No_certs_No_Bse_cve_ROOKIE.LVL_SOC--BLUETEAMER^^
Discovered via: phrase:multi-agent
First indexed: 7 days ago
Last synced: 19 hours ago

SHAdd0WTAka/Zen-Ai-Pentest

🛡⚔️AI-Powered Penetration Testing Framework with automated vulnerability scanning, multi-agent system, and compliance reporting🛡⚔️

79MITPython

View on GitHub Website

Stars: 435
Forks: 77
Watchers: 5
Open issues: 0
Contributors: —

Star history, last 90 days+2 over 3 snapshots

2026-07-31 · 4332026-08-06 · 435

Star history, last 90 days
Date	Stars
2026-07-31	433
2026-08-05	435
2026-08-06	435

Today

— stars today

This week

— stars this week

This month

— stars this month

Momentum

5.0

growth rate 0.00%/day

From the README

Zen-AI-Pentest

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

%%{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

🤖 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

🤖 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

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

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
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.

Rendered by GitHub from the current README

Read on GitHub

Top contributors

No contributor data yet — it is fetched during the contributor sync pass.

Quality score

Would you bet a product on this? Bounded 0–100 and slow moving.

79/10079

Maintenance: 100%; How recently the default branch was pushed to
Releases: 63%; Recency and cadence of tagged releases
Community: 20%; Contributor breadth and bus factor
Issue backlog: 100%; Open issues measured against the size of the audience
Documentation: 100%; README depth, plus a homepage and topics
Licensing: 100%; How freely the code can be adopted

What to know before adopting

Nothing flagged — maintained, documented and cleanly licensed.
Usable in commercial products with attribution.

Details

Created: 6 months ago
Last push: 19 hours ago
Last release: 6 months ago
Release tag: v3.0.0
Releases in the last year: 9
Default branch: main
Size: 100k KB
Owner type: User
Owner location: WSL-KALi-Terminal-Mount-evrything-but-always-IN-Siem-OPERATIONS/soc/PolyciesandRegulations/but_dondt_expect_to_much_No_certs_No_Bse_cve_ROOKIE.LVL_SOC--BLUETEAMER^^
Discovered via: phrase:multi-agent
First indexed: 7 days ago
Last synced: 19 hours ago

Top AI Repos — open-source AI, indexed and scored

Trend

From the README

🔥 Overview

✨ Features

🤖 Autonomous AI

🎯 Risk Engine

🔒 Exploit Validation

🧠 AI Persona System

🗺️ Attack Path Analysis

📊 Benchmarking

🔧 72+ Integrated Security Tools

🧩 MCP Server Infrastructure

📚 Skills System (95 Skills)

🤖 WhatsApp Bot

🛡️ VPN Killswitch

🚀 Quick Start

🐳 Docker (Full Stack)

📦 Local Install

🤖 AI Agents (CLI)

📱 WhatsApp Bot

💻 Usage

Python API

REST API

WebSocket (Real-Time)

🏗️ Architecture

System Architecture

🤖 AI Orchestration Architecture

🔄 CI/CD Pipelines

1. 🧪 Tests Pipeline

2. 📊 Codecov Coverage Pipeline

3. 🔒 Security Scan Pipeline

4. ✅ CodeQL Analysis

5. 🚀 Deploy Pipeline

6. 📦 Release Pipeline

7. ⚙️ CI Pipeline (Legacy)

🧪 Test Suite

🛡️ Security

Built-in Protections

Risk Levels

🔧 Configuration

Option 1: Obsidian Vault (Recommended)

Option 2: Environment Variables

📁 Project Structure

📚 Documentation

🌐 Community

🤝 Contributing

👥 Authors

📄 License

Top contributors

Quality score

What to know before adopting

Categories

Details

Trend

From the README

🔥 Overview

✨ Features

🤖 Autonomous AI

🎯 Risk Engine

🔒 Exploit Validation

🧠 AI Persona System

🗺️ Attack Path Analysis

📊 Benchmarking

🔧 72+ Integrated Security Tools

🧩 MCP Server Infrastructure

📚 Skills System (95 Skills)

🤖 WhatsApp Bot

🛡️ VPN Killswitch

🚀 Quick Start

🐳 Docker (Full Stack)

📦 Local Install

🤖 AI Agents (CLI)

📱 WhatsApp Bot

💻 Usage

Python API

REST API

WebSocket (Real-Time)

🏗️ Architecture

System Architecture