🛡️ 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 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 MeowKitProduction ready. AI Agent Workflow System for Claude Codev2.10.2 More in Frameworks spec_driven_developSpec-Driven Develop is a platform-agnostic AI agent skill that automates the pre-development workflow for large-scale complex tasks. It is not a framework, not a runtime, not a package manager — it is deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of ta simBuild, deploy, and orchestrate AI agents. Sim is the central intelligence layer for your AI workforce. ctranslate2Fast inference engine for Transformer models