🛡️ 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

• 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)

• 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

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

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

• 🔐 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

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

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

⚠️ 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.

# 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

• 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

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

• 🤖 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!}

• 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

• 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

• 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

• 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

• 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

• 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)

• 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

• 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

• 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

• 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

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

• 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

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

• 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

• 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

• 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

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

# 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

# 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

# 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

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

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

For detailed installation instructions, see:

• Docker Installation
• Local Installation
• Production Deployment
• VirtualBox Setup

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))

# 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"}'

const ws = new WebSocket("ws://localhost:8000/ws/scans/1");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Scan update:", data);
};

┌─────────────────────────────────────────────────────────────────────┐
│                         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)  │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                      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 Documentation - Complete REST API reference
• WebSocket API - Real-time updates
• Authentication - Security and auth

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

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

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

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.

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

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.

# 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

• 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

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

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

# 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

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

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

# 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

📖 Complete Docker Guide

Die React Frontend ist automatisch auf Cloudflare Pages deployed:

Jeder Push auf main branch:

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

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

# Oder mit Wrangler CLI
npx wrangler pages deploy dist/

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

• ✅ 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

⚠️ Always ensure you have authorization before scanning!

We welcome contributions! Please see:

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

Quick start:

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

Join our growing community!

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

Fully configured with 11 channels:

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

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

See SUPPORT.md for detailed support options.

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

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

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

@SHAdd0WTAka Project Founder & Lead Developer Security Architect

AI Contributors minimax (minimax-m2.5-free) - AI coding assistant Voice-driven AI interaction via WhatsApp Bumblebee Radio audio-only system Hermes Gateway integration Voice transcription with faster-whisper Coverage improvements and quality assurance Security testing and validation Integration testing with Bumblebee Radio 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 minimax - AI coding assistant (minimax-m2.5-free) Voice-driven AI interaction via WhatsApp Bumblebee Radio audio-only system Hermes Gateway integration 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. Made with ❤️ for the security community © 2026 Zen-AI-Pentest. All rights reserved. 🎥 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 Coveralls Codecov Letzte Aktualisierung: 31.03.2026 Release History Version Changes Urgency Date v3.0.0 # Zen-AI-Pentest v3.0.0 - Release Notes **Release Date:** February 19, 2026 **Status:** Production Ready **Codename:** "Kimi Agent 100 Integration" --- ## 🎉 Major Release v3.0.0 Dieses Release integriert die komplette Kimi Agent 100 Analysis und bringt Zen-AI-Pentest auf Enterprise-Level. --- ## ✨ New Features ### 🤖 Multi-Agent System (ACP v1.1) - **Agent Coordinator** - Autonome Agenten-Koordination - **ACP Protocol** - Agent Communication Protocol v1.1 - **Messa Low 2/19/2026 v2.3.9 ## Release v2.3.9 ### Features - feat: add automated release notes and changelog (6f752ce) - feat: Implement cache system with Redis support, auth flow, and API enhancements (8d4b42b) ### Security - security: Extend Bandit configuration for pentesting tool (cd1cfd1) - security: Configure Bandit for pentesting tool requirements (7c1d22d) - security: Fix npm vulnerabilities (jsonpath, webpack-dev-server) (de5f0dd) - security: Fix 8 Dependabot alerts - Update dependencies (fcace3d) ### Documenta Low 2/6/2026 v2.3.8 ## Release v2.3.8 ### Features - feat: add automated release notes and changelog (6f752ce) - feat: Implement cache system with Redis support, auth flow, and API enhancements (8d4b42b) ### Security - security: Extend Bandit configuration for pentesting tool (cd1cfd1) - security: Configure Bandit for pentesting tool requirements (7c1d22d) - security: Fix npm vulnerabilities (jsonpath, webpack-dev-server) (de5f0dd) - security: Fix 8 Dependabot alerts - Update dependencies (fcace3d) ### Documenta Low 2/6/2026 v2.3.5 Release v2.3.5 Low 2/6/2026 v2.3.1 Release v2.3.1 Low 2/5/2026 v2.3.0 ## 🛡️ Zen AI Pentest - GitHub Action AI-powered security scanning for your CI/CD pipelines. ### ✨ Features - 🔍 AI-powered vulnerability detection - 📊 SARIF output for GitHub Security tab - 🚀 Multiple scan modes (full, recon, vuln, stealth) - ⚡ Fast and efficient scanning - 🔒 100% Open Source & Free ### 📖 Usage ```yaml - uses: SHAdd0WTAka/Zen-Ai-Pentest@v2.3.0 with: target: 'https://your-app.com' fail-on: 'critical' 📚 Document Low 2/5/2026 v2.0.3 ## Zen AI Pentest v2.0.3 ### Changes - Fixed invalid PyPI classifier (removed 'Topic :: Security :: Pentesting') - Bumped version to 2.0.3 for proper PyPI release - Successfully published to PyPI ### Installation ```bash pip install zen-ai-pentest ``` ### Links - PyPI: https://pypi.org/project/zen-ai-pentest/2.0.3/ - Documentation: https://github.com/SHAdd0WTAka/zen-ai-pentest/blob/master/README.md Low 2/4/2026 v2.0.2 ## Zen AI Pentest v2.0.2 ### Changes - Fixed invalid PyPI classifier (removed 'Topic :: Security :: Pentesting') - Successfully published to PyPI ### Installation ```bash pip install zen-ai-pentest ``` ### Links - PyPI: https://pypi.org/project/zen-ai-pentest/ - Documentation: https://github.com/SHAdd0WTAka/zen-ai-pentest/blob/master/README.md Low 2/4/2026 v1.0.0 ## Zen AI Pentest v1.0.0 First stable release! ### Included - Core Agent Framework - ReAct Reasoning Loop - Tool Calling Framework - Windows AsyncIO Fix - Security Fixes (CVE-2025-68664, CVE-2024-33663) - PR Templates - Security Policy - Architecture Decision Records (ADR) ### Health Score Improved from 68/100 to ~85/100 ### Next (v1.1.0) - Test Suite 70% Coverage (#22) - Memory System with LangGraph (#20) - Hallucination Protection (#23) Low 1/31/2026 Dependencies & License Audit Loading dependencies... Similar Packages redamonAn AI-powered agentic red team framework that automates offensive security operations, from reconnaissance to exploitation to post-exploitation, with zero human intervention.v4.0.0 Auto-Pentest-LLM🔍 Automate penetration testing with an intelligent agent that organizes security assessments, leveraging local LLMs and Kali Linux for effective exploitation.main@2026-06-08 langchainThe agent engineering platformlangchain-core==1.4.1 opentulpaSelf-hosted personal AI agent that lives in your DMs. Describe any workflow: triage Gmail, pull a Giphy feed, build a Slack bot, monitor markets. It writes the code, runs it, schedules it, and saves imain@2026-06-05 langgraphBuild resilient language agents as graphs.1.2.4 More in Frameworks agateA data analysis library that is optimized for humans instead of machines. pytest-aiohttpPytest plugin for aiohttp support aiohttpAsync http client/server framework (asyncio) imbalanced-learnToolbox for imbalanced dataset in machine learning