Zen-AI-Pentest

🛡️ Professional AI-Powered Penetration Testing Framework

Guest Control: Execute tools inside isolated VMs
🆕 GitHub MCP Integration: Model Context Protocol für GitHub
🆕 QR Code Modal: Schneller Zugriff via QR Codes
🆕 Cloudflare Deployment: Automatisches Deployment

🌐 Live Demo

Frontend: https://zen-ai-pentest.pages.dev - React Dashboard
API: https://zen-ai-pentest.workers.dev - Cloudflare Workers API
Health Check: https://zen-ai-health.aydinatakan.workers.dev/health - Worker Health Monitor
Alpha Dashboard: https://03c8d80c.zen-alpha-pentest.pages.dev - Zen Alpha Pentest
AI Analysis: https://v2-0.zen-ai-pentest.pages.dev/ai-analysis - AI-Powered Analysis Interface
Login: admin / admin ( für Demo-Zwecke)

🚀 Modern API & Backend

FastAPI: High-performance REST API
PostgreSQL: Persistent data storage
WebSocket: Real-time scan updates
JWT Auth: Role-based access control (RBAC)
Background Tasks: Async scan execution

📊 Reporting & Notifications

PDF Reports: Professional findings reports
HTML Dashboard: Interactive web interface
Slack/Email: Instant notifications
JSON/XML: Integration with other tools

🐳 Easy Deployment

Docker Compose: One-command full stack deployment
CI/CD: GitHub Actions pipeline
Production Ready: Optimized for enterprise use

🆕 New in v3.0 (2026)

🔐 GitHub MCP Server: Secure Model Context Protocol integration
💬 Global Chat: AI-powered chat interface im Dashboard
📱 Kimi Terminal: Web-basierte CLI Integration
🌉 Auth Bridge: Lokale Kimi CLI Authentifizierung
📶 Twitch Tunnel: Kreative Tunnel-Lösung
🤖 100 Agent POC: Full-Stack Multi-Agent System
🔗 Device Auth: Sichere Geräte-Authentifizierung

🎯 Real Data Execution - No Mocks!

Zen-AI-Pentest executes real security tools - no simulations, no mocks, only actual tool execution:

✅ Nmap - Real port scanning with XML output parsing
✅ Nuclei - Real vulnerability detection with JSON output
✅ SQLMap - Real SQL injection testing with safety controls
✅ FFuF - Blazing fast web fuzzer
✅ WhatWeb - Technology detection (900+ plugins)
✅ WAFW00F - WAF detection (50+ signatures)
✅ Subfinder - Subdomain enumeration
✅ HTTPX - Fast HTTP prober
✅ Nikto - Web vulnerability scanner
✅ Multi-Agent - Researcher & Analyst agents cooperate
✅ Docker Sandbox - Isolated tool execution for safety

📖 Enhanced Tools: README_ENHANCED_TOOLS.md

All tools run with safety controls:

Private IP blocking (protects internal networks)
Timeout management (prevents hanging)
Resource limits (CPU/memory constraints)
Read-only filesystems (Docker sandbox)

📖 Details: IMPLEMENTATION_SUMMARY.md

🧪 Comprehensive Test Suite

Zen-AI-Pentest features a comprehensive test suite supporting robust development:

Metric	Value	Status
Test Files	1,145+	✅ Real
Total Tests	43,000+	✅ Verified
Coverage	~10% (measured)	⚠️ Work in Progress
Target Coverage	80%+	🎯 Goal

⚠️ Note: While we have 43,000+ tests, our actual code coverage is ~10%. Many modules are in active development. See COVERAGE_CORRECTION.md for details.

Test Categories

Category	Count	Description
Unit Tests	1,142 files	Component-level testing
Integration Tests	20+ files	End-to-end workflows
Security Tests	15+ files	SAST/DAST validation
Performance Tests	10+ files	Benchmarking suite

Quick Test Commands

# Run all tests
pytest tests/ -v

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

# Unit tests only
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

📖 Testing Docs: TESTING_MASSIVE_SCALE.md | docs/TESTING.md

🚀 Quick Start

📚 Table of Contents

Overview
Features
- For AI Agents
Quick Start
Installation
Usage
Architecture
API Reference
Project Structure
Configuration
Secret Management
Testing
Docker Deployment
Safety First
Documentation
Contributing
Community & Support
License

🎯 Overview

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

  graph TB
      subgraph "Client Interface"
          WebUI[🌐 Web UI]
          CLI[💻 CLI]
          API_Client[🔌 REST API]
      end

      subgraph "API Gateway"
          FastAPI[FastAPI + WebSocket]
          Auth[🔐 JWT/RBAC]
          AgentMgr[🤖 Agent Manager]
      end

      subgraph "Workflow Orchestrator"
          Guardrails[🛡️ Guardrails]
          TaskQueue[📊 Task Queue]
          RiskLevels[⚠️ Risk Levels 0-3]
          VPN[🔒 VPN Check]
          State[📈 State Machine]
      end

      subgraph "Reporting"
          ReportGen[📝 Report Generator]
      end

      subgraph "Agent Pool"
          Agent1[🤖 Agent #1]
          Agent2[🤖 Agent #2]
          AgentN[🤖 Agent #N]
      end

      subgraph "Security Toolkit"
          Nmap[🔍 nmap]
          Whois[📡 whois]
          Dig[🌐 dig]
          Nuclei[⚡ nuclei]
          SQLMap[🎯 sqlmap]
      end

      subgraph "Analysis & Reporting"
          Evidence[📋 Evidence Collection]
          AttackPath[🗺️ Attack Path]
          ChainOfCustody[🔗 Chain of Custody]
          Compliance[📊 Compliance Mapping]
          ReportTemplates[📄 Report Templates]
          RiskScoring[🎯 Risk Scoring]
      end

      subgraph "Data Layer"
          Postgres[🐘 PostgreSQL]
          Redis[⚡ Redis Cache]
          Storage[📁 File Storage]
      end

      WebUI --> FastAPI
      CLI --> FastAPI
      API_Client --> FastAPI
      FastAPI --> Auth
      Auth --> AgentMgr
      AgentMgr --> Guardrails
      Guardrails --> TaskQueue
      TaskQueue --> RiskLevels
      RiskLevels --> VPN
      VPN --> State
      State --> Agent1
      State --> Agent2
      State --> AgentN
      Agent1 --> Nmap
      Agent1 --> Whois
      Agent2 --> Dig
      Agent2 --> Nuclei
      AgentN --> SQLMap
      Nmap --> Evidence
      Whois --> AttackPath
      SQLMap --> ChainOfCustody
      State --> ReportGen
      ReportGen --> ReportTemplates
      ReportGen --> Compliance
      AttackPath --> ReportTemplates
      ChainOfCustody --> RiskScoring
      Compliance --> Postgres
      ReportTemplates --> Storage
      RiskScoring --> Redis

Key Highlights

🤖 AI-Powered: Leverages state-of-the-art LLMs for intelligent decision making
🔒 Security-First: Multiple safety controls and validation layers
🚀 Production-Ready: Enterprise-grade with CI/CD, monitoring, and support
📊 Comprehensive: 72+ integrated security tools (Inventory)
🔧 Extensible: Plugin system for custom tools and integrations
☁️ Cloud-Native: Deploy on AWS, Azure, or GCP
📱 Quick Access: Scan QR codes for instant mobile access

_{☝️ Click to view all QR codes or scan with your phone!}

✨ Features

🤖 Autonomous AI Agent

ReAct Pattern: Reason → Act → Observe → Reflect
State Machine: IDLE → PLANNING → EXECUTING → OBSERVING → REFLECTING → COMPLETED
Memory System: Short-term, long-term, and context window management
Tool Orchestration: Automatic selection and execution of 72+ pentesting tools
Self-Correction: Retry logic and adaptive planning
Human-in-the-Loop: Optional pause for critical decisions

🎯 Risk Engine

False Positive Reduction: Multi-factor validation with Bayesian filtering
Business Impact: Financial, compliance, and reputation risk calculation
CVSS/EPSS Scoring: Industry-standard vulnerability assessment
Priority Ranking: Automated finding prioritization
LLM Voting: Multi-model consensus for accuracy

🔒 Exploit Validation

Sandboxed Execution: Docker-based isolated testing
Safety Controls: 4-level safety system (Read-Only to Full)
Evidence Collection: Screenshots, HTTP captures, PCAP
Chain of Custody: Complete audit trail
Remediation: Automatic fix recommendations

📊 Benchmarking

Competitor Comparison: vs PentestGPT, AutoPentest, Manual
Test Scenarios: HTB machines, OWASP WebGoat, DVWA
Metrics: Time-to-find, coverage, false positive rate
Visual Reports: Charts and statistical analysis
CI Integration: Automated regression testing

🔗 CI/CD Integration

GitHub Actions: Native action support
GitLab CI: Pipeline integration
Jenkins: Plugin and pipeline support
Output Formats: JSON, JUnit XML, SARIF
Notifications: Slack, JIRA, Email alerts
Exit Codes: Pipeline-friendly status codes

🧠 AI Persona System

11 Specialized Personas: Recon, Exploit, Report, Audit, Social, Network, Mobile, Red Team, ICS, Cloud, Crypto
CLI Tool: Interactive and one-shot modes (k-recon, k-exploit, etc.)
REST API: Flask-based API with WebSocket support
Web UI: Modern browser interface with screenshot analysis
Context Preservation: Multi-turn conversations with memory
Screenshot Analysis: Upload and analyze images with AI personas
🆕 Global Chat: Eingebetteter AI Chat im Dashboard (v3.0)
🆕 Kimi Terminal: Web-basierte Terminal-Integration (v3.0)

📋 Evidence & Chain of Custody

Tamper-Proof Collection: Cryptographic signatures for all evidence
Chain of Custody: Complete audit trail for legal proceedings
Multi-Format Export: Screenshots, HTTP captures, PCAP files
Court-Ready Reports: ISO 27001 compliant documentation
Signature Verification: SHA-256 hashing with integrity checks

📄 Report Generation

Executive Reports: High-level summaries for C-level executives
Technical Reports: Detailed findings with evidence and remediation
Compliance Reports: OWASP, ISO 27001, PCI DSS, NIST mappings
Export Formats: PDF, HTML, DOCX, JSON
Professional Templates: Customizable branding and layout

🗺️ Attack Path Analysis

Visual Graphs: Interactive attack path visualization (Cytoscape.js)
Entry Point Mapping: Identify and track all entry vectors
Crown Jewel Analysis: Critical asset identification
Attack Simulation: Test exploitation paths without execution
Risk Scoring: Difficulty and impact assessment per path

🛡️ Security Guardrails

IP Validation - Blocks private networks (10.x, 192.168.x, 172.16-31.x)
Domain Filtering - Prevents localhost/internal domain scanning
Risk Levels - 4 levels (SAFE → AGGRESSIVE) with tool restrictions
Rate Limiting - Prevents abuse

🤖 Multi-Agent System

Workflow Orchestrator - Manages complex pentest workflows
Task Distribution - Assigns tasks to available agents
Real-time Updates - WebSocket communication
Result Aggregation - Collects and analyzes findings

🔒 VPN Integration (Optional)

ProtonVPN Support - Native CLI integration
Generic Detection - Works with OpenVPN, WireGuard, etc.
Safety Warnings - Alerts when scanning without VPN
Strict Mode - Can require VPN for scans

🐳 Docker Ready

One-Command Deploy - docker-compose up -d
Isolated Environment - All tools pre-installed
Scalable - Run multiple agents
Production Ready - Health checks & monitoring

🛠️ 72+ Integrated Tools (v3.0)

Category	Tools
Network	Nmap, Masscan, Scapy, Tshark, tcpdump, netdiscover, arp-scan
Web	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, Ignorant, Scout
Active Directory	BloodHound, NetExec, Responder, ldapsearch, enum4linux
Wireless	Aircrack-ng Suite (aircrack-ng, airmon-ng, airodump-ng, aireplay-ng)
OSINT	Sherlock, Ignorant, TheHarvester, Scout
Code Analysis	Semgrep, TruffleHog, Gitleaks, Bandit
Container	Trivy, Docker, Kubectl
System	Netcat, Socat, OpenSSL, Proxychains, Tor

🔍 Subdomain Scanner

Multi-Technique Enumeration: DNS, Wordlist, Certificate Transparency
Advanced Techniques: Zone Transfer (AXFR), Permutation/Mangling
OSINT Integration: VirusTotal, AlienVault OTX, BufferOver
IPv6 Support: AAAA record enumeration
Technology Detection: Automatic fingerprinting of live hosts
Export Formats: JSON, CSV, TXT
REST API: Async and sync scanning endpoints
CLI Tools: Standalone scanner with comprehensive options

🤖 For AI Agents

AGENTS.md - Essential guide for AI development partners
Real Tool Execution - No mocks, actual security tools
Multi-Agent System - Researcher, Analyst, Exploit agents
Safety Controls - 4-level sandbox system
Architecture Guide - Complete system overview

🔔 Notifications & Integrations

Telegram Bot: @Zenaipenbot - Instant CI/CD notifications
Discord Integration: Automated channel updates & GitHub webhooks
Slack/Email: Enterprise notification support
GitHub Actions: Native workflow integration
QR Code Gallery: Quick access to all resources

☁️ Multi-Cloud & Virtualization

Local: VirtualBox VM Management
Cloud: AWS EC2, Azure VMs, Google Cloud Compute
Snapshots: Automated clean-state workflows

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone repository
git clone https://github.com/SHAdd0WTAka/zen-ai-pentest.git
cd zen-ai-pentest

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Start full stack
docker-compose up -d

# Access:
# Dashboard: http://localhost:3000
# API Docs:  http://localhost:8000/docs
# API:       http://localhost:8000

Option 2: Local Installation

# Install dependencies
pip install -r requirements.txt

# Initialize database
python database/models.py

# Start API server
python api/main.py

# Run subdomain scan
python scan_target_subdomains.py

# Or use the advanced CLI
python tools/subdomain_enum.py example.com --advanced

Option 3: AI Personas Quick Start

# Start the AI Personas API & Web UI
bash api/QUICKSTART.sh

# Or manually:
bash api/manage.sh start
# Open http://127.0.0.1:5000

# CLI Usage
source tools/setup_aliases.sh
k-recon "Target: example.com"
k-exploit "Write SQLi scanner"
k-chat  # Interactive mode

Option 4: VirtualBox VM Setup

# Automated Kali Linux setup
python scripts/setup_vms.py --kali

# Manual setup
# See docs/setup/VIRTUALBOX_SETUP.md

📖 Installation

For detailed installation instructions, see:

💻 Usage

Python API

from agents.react_agent import ReActAgent, ReActAgentConfig

# Configure agent
config = ReActAgentConfig(
    max_iterations=10,
    use_vm=True,
    vm_name="kali-pentest"
)

# Create agent
agent = ReActAgent(config)

# Run autonomous scan
result = agent.run(
    target="example.com",
    objective="Comprehensive security assessment"
)

# Generate report
print(agent.generate_report(result))

REST API

# Authentication
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","config":{"ports":"top-1000"}}'

# 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);
};

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT INTERFACE                            │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   🌐 Web UI  │  │   💻 CLI     │  │   🔌 API     │              │
│  │   (React)    │  │   (Python)   │  │   (REST)     │              │
│  │   Cloudflare │  │              │  │   WebSocket  │              │
│  │   Pages      │  │              │  │              │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
└─────────┼─────────────────┼─────────────────┼───────────────────────┘
          │                 │                 │
          └─────────────────┼─────────────────┘
                            │ HTTPS / JWT
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         API GATEWAY                                 │
│                    FastAPI + WebSocket                              │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                │
│  │   🔐 Auth    │ │   📋 Work-   │ │   🤖 Agent   │                │
│  │   (JWT/RBAC) │ │   flow API   │ │   Manager    │                │
│  └──────────────┘ └──────────────┘ └──────────────┘                │
└─────────────────────────┬───────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    WORKFLOW ORCHESTRATOR                            │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   🛡️         │  │   📊 Task    │  │   ⚠️ Risk    │              │
│  │   Guardrails │  │   Queue      │  │   Levels     │              │
│  │   (IP/Domain │  │              │  │   (0-3)      │              │
│  │   Filter)    │  │              │  │              │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   🔒 VPN     │  │   📈 State   │  │   📝 Report  │              │
│  │   Check      │  │   Machine    │  │   Generator  │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────┬───────────────────────────────────────────┘
                          │ WebSocket + Task Distribution
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         AGENT POOL                                  │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   🤖 Agent   │  │   🤖 Agent   │  │   🤖 Agent   │              │
│  │   #1         │  │   #2         │  │   #N         │              │
│  │   (Docker)   │  │   (Docker)   │  │   (Docker)   │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
└─────────┼─────────────────┼─────────────────┼───────────────────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      SECURITY TOOLKIT                               │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │   🔍     │ │   📡     │ │   🌐     │ │   ⚡     │ │   🎯     │  │
│  │   nmap   │ │  whois   │ │   dig    │ │  nuclei  │ │  sqlmap  │  │
│  │          │ │          │ │          │ │          │ │          │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────────────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    ANALYSIS & REPORTING LAYER                       │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   📋         │  │   🗺️         │  │   🔗         │              │
│  │   Evidence   │  │   Attack     │  │   Chain of   │              │
│  │   Collection │  │   Path       │  │   Custody    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   📊         │  │   📄         │  │   🎯         │              │
│  │   Compliance │  │   Report     │  │   Risk       │              │
│  │   Mapping    │  │   Templates  │  │   Scoring    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────┬───────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         DATA LAYER                                  │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   🐘 Postgre │  │   ⚡ Redis   │  │   📁 File    │              │
│  │   SQL        │  │   Cache      │  │   Storage    │              │
│  │   (State)    │  │   (Queue)    │  │   (Reports)  │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘

🆕 New Features (2026)

Feature	Description	Status
📋 Evidence Collection	Tamper-proof evidence with cryptographic signatures	✅ Live
📊 Attack Path Analysis	Visual attack graphs from entry points to crown jewels	✅ Live
📄 Report Generator	Executive, Technical & Compliance reports (PDF/HTML/JSON)	✅ Live
🔗 Chain of Custody	Complete audit trail for legal proceedings	✅ Live
🧪 43,000+ Tests	Comprehensive test suite with CI/CD	✅ Passing
☁️ Cloudflare Pages	Global CDN deployment	✅ Live

🔄 CI/CD Pipeline

┌─────────────────────────────────────────────────────────────────────┐
│                      GITHUB ACTIONS WORKFLOW                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Push/PR ──► ┌──────────┐ ──► ┌──────────┐ ──► ┌──────────┐        │
│              │  Tests   │     │ Codecov │     │ Security │        │
│              └──────────┘     └──────────┘     └──────────┘        │
│              └──────────┘     └──────────┘     └──────────┘        │
│                                    │                                │
│                                    ▼                                │
│                            ┌──────────────┐                        │
│                            │ Codecov.io   │                        │
│                            │ Codecov     │                        │
│                            │ Reporting    │                        │
│                            └──────────────┘                        │
│                                                                     │
│  Frontend Build ──► ┌──────────────┐ ──► ┌──────────────────┐     │
│                     │ Cloudflare   │     │ Global Deploy    │     │
│                     │ Pages Build  │     │ zen-ai-pentest   │     │
│                     └──────────────┘     │ .pages.dev       │     │
│                                          └──────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘

📊 Coverage Reports: codecov.io/gh/SHAdd0WTAka/Zen-Ai-Pentest

For detailed architecture documentation, see docs/architecture.md.

📡 API Reference

API Documentation - Complete REST API reference
WebSocket API - Real-time updates
Authentication - Security and auth

📁 Project Structure

zen-ai-pentest/
├── api/                   # FastAPI Backend (main.py, auth.py, websocket.py)
├── agents/                # AI Agents (react_agent.py, react_agent_vm.py)
├── autonomous/            # ReAct Loop (agent_loop.py, exploit_validator.py, memory.py)
├── tools/                 # 72+ Security Tools
│   ├── Network: nmap, masscan, scapy, tshark, tcpdump, netdiscover, arp-scan
│   ├── Web: nuclei, sqlmap, nikto, zap, burpsuite, ffuf, gobuster, wafw00f, whatweb
│   ├── Recon: subfinder, amass, httpx, theharvester, subdomain_scan, unified_recon
│   ├── AD: bloodhound, netexec, responder, ldapsearch, enum4linux, rpcclient, smbclient
│   ├── OSINT: sherlock, scout, ignorant
│   ├── Secrets: trufflehog, gitleaks, trivy
│   ├── Wireless: aircrack-ng, airmon-ng, airodump-ng, aireplay-ng
│   ├── Brute Force: hydra, hashcat, john, ncrack
│   ├── Code: semgrep, bandit
│   ├── Cloud/Container: docker, kubectl
│   ├── AI/Kimi: kimi_cli, kimi_helper, update_personas
│   └── Core: tool_caller, tool_registry
├── risk_engine/           # Risk Analysis (cvss.py, epss.py, false_positive_engine.py)
├── benchmarks/            # Performance Testing
├── integrations/          # CI/CD (github, gitlab, slack, jira, jenkins)
├── database/              # PostgreSQL Models
├── gui/                   # React Dashboard
├── reports/               # PDF/HTML/JSON Generator
├── notifications/         # Alerts (slack, email)
├── docker/                # Deployment configs
├── docs/                  # Documentation (ARCHITECTURE.md, INSTALLATION.md, API.md, setup/)
├── tests/                 # Test Suite (43,000+ tests)
└── scripts/               # Setup Scripts

🔧 Configuration

Zen-AI-Pentest supports two approaches for managing configuration and secrets. Choose the one that fits your security requirements:

Approach	Best For	Security Level	Setup Complexity
🛡️ Obsidian Vault (Recommended)	Production, Teams	⭐⭐⭐⭐⭐ High	Medium
📄 .env File	Development, Quick Start	⭐⭐⭐ Medium	Easy

🛡️ Option 1: Obsidian Vault (Recommended)

Store secrets securely in an encrypted Obsidian vault with MCP integration. Secrets never touch your codebase.

# 1. Setup Obsidian Secrets Vault
bash mcp/obsidian/setup.sh

# 2. Edit your secrets
code ~/Documents/Obsidian\ Vault/Secrets/secrets.yaml

# 3. Reload VS Codium
Ctrl+Shift+P → Developer: Reload Window

Vault Structure:

# ~/Documents/Obsidian Vault/Secrets/secrets.yaml
kimi:
  api_key: "sk-your-kimi-api-key"

openai:
  api_key: "sk-your-openai-key"

database:
  url: "postgresql://postgres:pass@localhost:5432/zen_pentest"

notifications:
  slack_webhook: "https://hooks.slack.com/..."

Benefits:

🔐 Encrypted at rest (Obsidian encryption)
🚫 Never committed to Git
🤖 AI-assisted via MCP server
🔄 Hot-reload without restart
🔒 100% Local Processing - Secrets never leave your machine

🔑 Security Guarantees:

Your secrets are never sent to external servers. All operations happen exclusively on your local system.

We cannot access your secrets - the private key resides only on your system.

Open Source: You can audit the code at any time.

📖 Full Vault Docs: mcp/obsidian/README.md | Detailed Architecture

📄 Option 2: Environment Variables (.env)

Quick setup for development using a local .env file.

# 1. Copy example file
cp .env.example .env

# 2. Edit with your secrets
nano .env

# 3. Load environment
source .env

Example .env:

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/zen_pentest

# Security
SECRET_KEY=your-secret-key-here
JWT_EXPIRATION=3600

# AI Providers (Kimi AI recommended)
KIMI_API_KEY=your-kimi-api-key
DEFAULT_BACKEND=kimi
DEFAULT_MODEL=kimi-k2.5

# Alternative Backends (optional)
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# OPENROUTER_API_KEY=...

# Notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/...
SMTP_HOST=smtp.gmail.com

# Cloud Providers
AWS_ACCESS_KEY_ID=AKIA...
AZURE_SUBSCRIPTION_ID=...

⚠️ Important: Add .env to your .gitignore!

.env
.env.local
.env.*.local

See .env.example for all available options.

🔄 Switching Between Options

You can switch between Vault and .env at any time:

# Check current configuration
python3 -c "from core.config import settings; print(settings.secret_source)"

# Force reload from Vault
export USE_VAULT=true

# Force reload from .env
export USE_ENV_FILE=true

🔐 Secret Management

Zen-AI-Pentest uses Obsidian MCP Server for secure credential management. All secrets are stored locally in an encrypted Obsidian vault - never in the repository.

🚀 Quick Setup

# 1. Setup Obsidian Secrets Vault
bash mcp/obsidian/setup.sh

# 2. Edit your secrets
code ~/Documents/Obsidian\ Vault/Secrets/secrets.yaml

# 3. Reload VS Codium
Ctrl+Shift+P → Developer: Reload Window

🎯 Benefits

Feature	Benefit
Obsidian Encryption	Secrets remain secure even if laptop is stolen
No Secrets in Git	No panic when pushing to GitHub
Local MCP Server	No transmission to external servers
Separation of Concerns	Clean architecture - code vs credentials

📁 Supported Secrets

AI Providers: Kimi, OpenAI, Anthropic, Gemini, OpenRouter
Cloud: AWS, Azure, GCP credentials
Database: PostgreSQL, Redis passwords
Security: JWT secrets, encryption keys
Notifications: Slack, Discord, Email SMTP
VPN: ProtonVPN, OpenVPN, WireGuard

🔌 MCP Integration

Access secrets directly in chat:

{
  "mcpServers": {
    "obsidian-secrets": {
      "command": "python3",
      "args": ["mcp/obsidian/server.py"]
    }
  }
}

📖 Full Documentation: mcp/obsidian/README.md

⚠️ Important: Ensure your .gitignore includes:

.env
.env.load.sh
*.key
*.pem
secrets.yaml
secrets.json
.obsidian/  # If Obsidian config is also sensitive

🧪 Testing

📊 Test Suite Overview

Category	Count	Status
Total Test Files	1,145+	✅ Organized
Total Tests	43,000+	✅ Verified
Coverage	10%	⚠️ Improving
CI/CD	GitHub Actions	✅ Automated

🗂️ Test Structure

tests/
├── unit/                       # Unit tests for individual components
│   ├── core/                  # Core framework tests
│   ├── api/                   # API endpoint tests
│   ├── database/              # Database model tests
│   ├── tools/                 # Security tool integration tests
│   └── agents/                # Agent behavior tests
├── integration/               # Integration tests
├── security/                  # Security & DAST tests
├── test_working_final.py      # Core test suite
└── test_performance_100_agents.py      # Performance tests

📈 Coverage Highlights

Module	Coverage	Status
`core/orchestrator.py`	84.42%	✅
`database/models.py`	87.97%	✅
`api/main.py`	38%	⚠️ Improving
Total	10%	🎯 Target: 80%

🚀 Running Tests

# Run all tests
pytest tests/ -v

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

# Unit tests only
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# Security tests
pytest tests/security/ -v

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

# Frontend tests (React/Vite)
cd web_ui/frontend && npm test

📈 Codecov Report

HTML Report: htmlcov/index.html
Codecov Integration: codecov.io/gh/SHAdd0WTAka/zen-ai-pentest
CI Badge:

🐳 Docker Deployment

Quick Setup (WSL2 + Docker)

Wir empfehlen Docker in WSL2 (Ubuntu) für die beste Performance:

Option 1: Automatisches Setup

# Windows: Setup-Launcher starten
scripts\docker-setup.bat

# Oder direkt in Ubuntu WSL:
./scripts/setup_docker_wsl2.sh

Option 2: Docker Desktop (Windows)

# PowerShell als Administrator:
powershell -ExecutionPolicy Bypass -File scripts/setup_docker_windows.ps1

📖 Komplette Docker + WSL2 Anleitung - Detaillierte Schritte für beide Optionen

Full Stack Starten

# Nach Docker-Installation:
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f api

# Scale agents
docker-compose up -d --scale agent=3

Services

Service	Port	Description
API	8000	FastAPI server
PostgreSQL	5432	Database
Redis	6379	Cache
Agent	-	Pentest agent

📖 Complete Docker Guide

☁️ Cloudflare Pages Deployment

🚀 Live Deployment

Die React Frontend ist automatisch auf Cloudflare Pages deployed:

Environment	URL	Status
Production	https://dde4fab5.zen-ai-pentest.pages.dev	✅ Live
Dashboard	https://dde4fab5.zen-ai-pentest.pages.dev/dashboard	✅ Ready
Login	`/login`	✅ Demo Mode

🔄 Automated Deployment

Jeder Push auf main branch:

Build: Cloudflare Pages baut automatisch
Test: GitHub Actions laufen
Deploy: Global CDN deployment (200+ Edge Locations)
Live: ~2 Minuten nach Push

🛠️ Manual Deployment

# Frontend bauen
cd web_ui/frontend
npm install
npm run build

# Oder mit Wrangler CLI
npx wrangler pages deploy dist/

🌍 Global CDN

200+ Edge Locations weltweit
DDoS Protection durch Cloudflare
HTTPS by Default mit automatischen Zertifikaten
Instant Cache Invalidation

🛡️ Safety First

Default 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
✅ Rate Limiting - Prevents abuse

Risk Levels

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

⚠️ Always ensure you have authorization before scanning!

📚 Documentation

Document	Description
docs/DEPLOYMENT.md	Deployment guide
docs/BENCHMARK_STATUS.md	Benchmark results
docs/SECURITY_AUDIT.md	Security audit report
docs/PERFORMANCE.md	Performance characteristics
DOCKER.md	Docker deployment guide
GUARDRAILS.md	Security guardrails documentation
GUARDRAILS_INTEGRATION.md	Guardrails integration guide
VPN_INTEGRATION.md	VPN setup and usage
DEMO_E2E.md	End-to-end demo documentation
AGENTS.md	Agent development guide

🤝 Contributing

We welcome contributions! Please see:

CONTRIBUTING.md - Contribution guidelines
CODE_OF_CONDUCT.md - Community standards
CONTRIBUTORS.md - Our amazing contributors

Quick start:

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 Pull Request

🌐 Community & Support

Join our growing community!

Quick Links

Platform	Link	QR Code
💬 GitHub	github.com/SHAdd0WTAka/Zen-Ai-Pentest	📱 Scan
🎮 Discord	discord.gg/zJZUJwK9AC	📱 Scan
🌐 Website	zen-ai-pentest.pages.dev	📱 Scan
📊 Dashboard	pages.dev/dashboard	📱 Scan

📱 All QR Codes

View our complete QR code gallery: docs/qr_codes/index.html

💬 Discord Server "Zen-Ai"

Fully configured with 11 channels:

📢 #announcements
📜 #rules
💬 #general
👋 #introductions
📚 #knowledge-base
🤖 #tools-automation
🔒 #security-research
🧠 #ai-ml-discussion
🐛 #bug-reports
💡 #feature-requests
🆘 #support

📧 Support

📖 Documentation - Comprehensive guides
🐛 Issue Tracker - Bug reports
📧 Email - Direct contact

See SUPPORT.md for detailed support options.

⚠️ Disclaimer

IMPORTANT: This tool is for authorized security testing only. Always obtain proper permission before testing any system you do not own. Unauthorized access to computer systems is illegal.

Use only on systems you have explicit permission to test
Respect privacy and data protection laws
The authors assume no liability for misuse or damage

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

🙏 Acknowledgments

LangGraph - Agent framework
FastAPI - Web framework
Kali Linux - Penetration testing distribution
All open-source security tool creators

👥 Authors & Team

Core Development Team

_@SHAdd0WTAka
_{Project Founder & Lead Developer}
_{Security Architect}

_{Kimi AI}
_{AI Development Partner}
_{Architecture & Design}

AI Contributors

Kimi AI (Moonshot AI) - Primary AI development partner
- Led architecture design for autonomous agent loop
- Implemented Risk Engine with false-positive reduction
- Created CI/CD integration templates
- Developed benchmarking framework
- Co-authored documentation and roadmaps

Special Thanks

Grok (xAI) - Strategic analysis and competitive research
GitHub Copilot - Code assistance and suggestions
Agent Zero - Autonomous agent architecture inspiration and hierarchical agent patterns
Anthropic (Claude) - Advanced reasoning capabilities and safety research
Google (Gemini) - Multi-modal AI integration and context understanding
DeepSeek - Open-source LLM excellence and code generation capabilities
OpenAI (ChatGPT/GPT-4) - Foundation LLM research and tool use patterns
Security Community - Feedback, bug reports, and feature requests

🎨 Project Artwork

Hemisphere Sync

      🧠 GEHIRN
     ╱        ╲
    ╱  LINKS   ╲    ╱  RECHTS   ╲
   ╱  (Kimi)    ╲  ╱(Observer^^)╲
  ╱   Logik      ╲╱  Kreativität ╲
     Analytisch   ╳  Ganzheitlich
     Struktur     ╳     Vision
          ╲      ╱╲    ╱
           ╲    ╱  ╲  ╱
            ╲  ╱    ╲╱
             ╲╱    ╱
              ╲   ╱
               ╲ ╱
                ❤️
        HEMISPHERE_SYNC
   "Zwei Hälften - Ein Herz - Ein Team"

A fusion of human vision and AI capability

Left Brain (Kimi - Logik) + Right Brain (Observer^^ - Kreativität) = Hemisphere_Sync

Hemisphere	Zuständig für	Team
Left Brain	Logik, Struktur, Code, Analytik	Kimi 🤖
Right Brain	Kreativität, Vision, Design, Emotion	Observer^^ 🎨

Custom artwork by SHAdd0WTAka representing the fusion of human vision and AI capability.

🎥 Demo Video

📹 Demo Video (295MB)

Full demonstration of the Zen-AI-Pentest framework in action.

📸 Repository Images

All screenshots, diagrams and visual assets for this repository:

📁 View All Images

🤖 AI & Development

Image	Description
Battle of the AIs	Claude vs Codex - AI Unit Test Battle
Obsidian Vault Setup	Terminal: GitHub Token & MCP Server Setup

🎨 Branding & Artwork

Image	Description
Kimi AI Artwork	Custom AI-generated artwork

📊 Status & Metrics

Image	Description
Repo Status Card	Live repository status dashboard

🖥️ Screenshots

Image	Description
Main Dashboard	Framework main dashboard
Demo Screenshot	Live demo view
Activity Screenshot 1	GitHub Activity View
Activity Screenshot 2	GitHub Activity View 2
Activity Screenshot 3	GitHub Activity View 3
Must Have Features	Feature Requirements
Must Have Features 2	Feature Requirements 2

🤖 Agent Zero

Image	Description
Agent Zero 1	Agent Zero Interface
Agent Zero 2	Agent Zero Dashboard
Agent Zero 3	Agent Zero Tasks
Agent Zero 4	Agent Zero Settings

📱 QR Codes

Image	Description
GitHub Repo	GitHub Repository QR
Discord	Discord Community QR
Website	Website QR
Dashboard	Dashboard QR
Hemisphere Sync	Hemisphere Sync Artwork
QR Grid	QR Code Grid Preview

📑 Presentation Slides (1-13)


Slide 1	Slide 2	Slide 3	Slide 4	Slide 5	Slide 6	Slide 7
Slide 8	Slide 9	Slide 10	Slide 11	Slide 12	Slide 13

🎯 TAO = Zen-Alpha Dashboard

Live Dashboard mit 32+ installierten Security Tools (Nmap, SQLMap, Metasploit, BeEF, Empire, etc.)

Codecov Trigger

API v1 Routes (New)

The API has been refactored with a modular route structure:

api/routes/v1/
├── auth.py           # Authentication
├── scans.py          # Scan management
├── findings.py       # Findings
├── tools.py          # Tool execution
├── reports.py        # Reports
├── schedules.py      # Scheduled scans
├── settings.py       # Configuration
├── stats.py          # Analytics
├── notifications.py  # Notifications
├── health.py         # Health checks
└── websocket.py      # WebSockets

See docs/API_V1_ROUTES.md for full documentation.

Test Codecov

Current coverage: 10.19% (target: 80%)

Run tests:

# Unit tests
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# E2E tests
pytest tests/e2e/ -v

# With coverage
pytest tests/ --cov=core --cov-report=html

CI/CD Pipeline

The project includes an enhanced CI/CD pipeline:

Workflows

CI Enhanced (.github/workflows/ci-enhanced.yml)
- Runs on Python 3.9-3.13
- Unit tests with coverage
- Integration tests
- Performance tests
- Code formatting checks (black, isort)
- Linting (flake8)
- Security checks (bandit, safety)
API v1 Tests (.github/workflows/api-v1-tests.yml)
- Tests API v1 routes
- Tests frontend integration
- Triggered on API changes
Performance Tests (.github/workflows/performance-tests.yml)
- Runs daily at 2 AM
- Performance benchmarks
- Results uploaded as artifacts

Running Tests Locally

# Unit tests with coverage
pytest tests/unit/ -v --cov=core --cov-report=html

# Integration tests
pytest tests/integration/ -v

# Performance tests
pytest tests/performance/ -v

# E2E tests
pytest tests/e2e/ -v

# All tests
pytest tests/ -v

📚 Weitere Dokumentation

Codecov-Strategie

Coverage-Strategie PDF - Vollständige Strategie zur Steigerung der Code-Coverage von 10% auf 80%
COVERAGE_STRATEGY.md - Markdown-Version der Strategie
TEST_STATUS.md - Aktueller Test-Status

Codecov-Dashboards

Letzte Aktualisierung: 31.03.2026

Name		Name	Last commit message	Last commit date
Latest commit History 2,489 Commits
.agent-comm		.agent-comm
.agents/skills		.agents/skills
.analysis		.analysis
.claude		.claude
.devcontainer		.devcontainer
.git-rewrite		.git-rewrite
.github		.github
.idx		.idx
.kimi		.kimi
.skills		.skills
.vs		.vs
.vscode		.vscode
agent_comm		agent_comm
agent_spawning_poc		agent_spawning_poc
agents		agents
alembic		alembic
analysis		analysis
analysis_bot		analysis_bot
api		api
app		app
assets		assets
audit		audit
auth		auth
autonomous		autonomous
backends		backends
benchmark_results		benchmark_results
benchmarks		benchmarks
ci_cd		ci_cd
cli		cli
cloudflare		cloudflare
config		config
core		core
custom_plugins		custom_plugins
dashboard		dashboard
data		data
database		database
demo		demo
docker		docker
docs		docs
evidence		evidence
examples		examples
extensions/browser_extension		extensions/browser_extension
github_app		github_app
github_mcp		github_mcp
grafana		grafana
guardrails		guardrails
gui		gui
helm/zen-pentest-operator		helm/zen-pentest-operator
infrastructure		infrastructure
integration		integration
integrations		integrations
isms_documentation		isms_documentation
jenkins		jenkins
k8s-production		k8s-production
k8s		k8s
kubernetes		kubernetes
logs		logs
mcp/obsidian		mcp/obsidian
memory		memory
mobile		mobile
models		models
modules		modules
monitoring		monitoring
native		native
nginx		nginx
notifications		notifications
observability		observability
orchestrator		orchestrator
p2p		p2p
performance		performance
plugins/example_plugin		plugins/example_plugin
poc		poc
postman		postman
prometheus		prometheus
references		references
reports		reports
requirements-deprecated		requirements-deprecated
risk		risk
risk_engine		risk_engine
safety		safety
scalable_architecture		scalable_architecture
scheduler		scheduler
screenshots		screenshots
scripts		scripts
security		security
tasks		tasks
templates		templates
terraform		terraform
test_targets		test_targets
tests		tests
tools		tools
ui		ui
utils		utils
virtualization		virtualization
vpn		vpn
web_ui		web_ui
websocket_scaling		websocket_scaling
wiki		wiki
zen_ai_pentest		zen_ai_pentest
zen_security		zen_security

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Zen-AI-Pentest

🌐 Live Demo

🚀 Modern API & Backend

📊 Reporting & Notifications

🐳 Easy Deployment

🆕 New in v3.0 (2026)

🎯 Real Data Execution - No Mocks!

🧪 Comprehensive Test Suite

Test Categories

Quick Test Commands

🚀 Quick Start

📚 Table of Contents

🎯 Overview

Key Highlights

✨ Features

🤖 Autonomous AI Agent

🎯 Risk Engine

🔒 Exploit Validation

📊 Benchmarking

🔗 CI/CD Integration

🧠 AI Persona System

📋 Evidence & Chain of Custody

📄 Report Generation

🗺️ Attack Path Analysis

🛡️ Security Guardrails

🤖 Multi-Agent System

🔒 VPN Integration (Optional)

🐳 Docker Ready

🛠️ 72+ Integrated Tools (v3.0)

🔍 Subdomain Scanner

🤖 For AI Agents

🔔 Notifications & Integrations

☁️ Multi-Cloud & Virtualization

🚀 Quick Start

Option 1: Docker (Recommended)

Option 2: Local Installation

Option 3: AI Personas Quick Start

Option 4: VirtualBox VM Setup

📖 Installation

💻 Usage

Python API

REST API

WebSocket (Real-Time)

🏗️ System Architecture

🆕 New Features (2026)

🔄 CI/CD Pipeline

📡 API Reference

📁 Project Structure

🔧 Configuration

🛡️ Option 1: Obsidian Vault (Recommended)

📄 Option 2: Environment Variables (.env)

🔄 Switching Between Options

🔐 Secret Management

🚀 Quick Setup

🎯 Benefits

📁 Supported Secrets

🔌 MCP Integration

🧪 Testing

📊 Test Suite Overview

🗂️ Test Structure

📈 Coverage Highlights

🚀 Running Tests

📈 Codecov Report

🐳 Docker Deployment

Quick Setup (WSL2 + Docker)

Full Stack Starten

Services

☁️ Cloudflare Pages Deployment

🚀 Live Deployment

🔄 Automated Deployment

🛠️ Manual Deployment

🌍 Global CDN

🛡️ Safety First

Default Protections

Risk Levels

Packages