https://github.com/SHAdd0WTAka/Zen-Ai-Pentest
🛡⚔️AI-Powered Penetration Testing Framework with automated vulnerability scanning, multi-agent system, and compliance reporting🛡⚔️
https://github.com/SHAdd0WTAka/Zen-Ai-Pentest
ai automation compliance cybersecurity ethical-hacking framework penetration-testing pentesting python security security-tools vulnerability-scanner
Last synced: 9 days ago
JSON representation
🛡⚔️AI-Powered Penetration Testing Framework with automated vulnerability scanning, multi-agent system, and compliance reporting🛡⚔️
- Host: GitHub
- URL: https://github.com/SHAdd0WTAka/Zen-Ai-Pentest
- Owner: SHAdd0WTAka
- License: mit
- Created: 2026-01-29T17:54:27.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-20T08:38:36.000Z (23 days ago)
- Last Synced: 2026-04-20T09:35:49.280Z (23 days ago)
- Topics: ai, automation, compliance, cybersecurity, ethical-hacking, framework, penetration-testing, pentesting, python, security, security-tools, vulnerability-scanner
- Language: Python
- Homepage: https://shadd0wtaka.github.io/Zen-Ai-Pentest/
- Size: 87.9 MB
- Stars: 353
- Watchers: 5
- Forks: 51
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: audit/__init__.py
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Governance: GOVERNANCE.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
- Dco: DCO.md
Awesome Lists containing this project
- awesome-ai-security - Zen-AI-Pentest - _AI-Powered Penetration Testing Framework with automated vulnerability scanning, multi-agent system, and compliance reporting. 72+ security tools, Docker sandbox, ReAct agents, attack path analysis._ (Attack Techniques & Red Teaming / AI-Assisted Offensive Security)
- awesome-ai-offensive-security - Zen-Ai-Pentest - An AI-Powered Penetration Testing Framework with automated vulnerability scanning, multi-agent system, and compliance reporting. (Pentest & Red Teaming Agents)
README
# Zen-AI-Pentest
> 🛡️ **Professional AI-Powered Penetration Testing Framework**
[](https://github.com/SHAdd0WTAka/Zen-Ai-Pentest/actions)
[](./COVERAGE_CORRECTION.md)
[](https://coveralls.io/github/SHAdd0WTAka/Zen-Ai-Pentest?branch=main)
[](./TESTING_MASSIVE_SCALE.md)
[](./SECURITY_AUDIT_REPORT_2026-03-20.md)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://zen-ai-pentest.pages.dev/)
[](https://www.bestpractices.dev/projects/11957)
- **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](https://zen-ai-pentest.pages.dev/) - React Dashboard
- **API**: [https://zen-ai-pentest.workers.dev](https://zen-ai-pentest.workers.dev/) - Cloudflare Workers API
- **Health Check**: [https://zen-ai-health.aydinatakan.workers.dev/health](https://zen-ai-health.aydinatakan.workers.dev/health) - Worker Health Monitor
- **Alpha Dashboard**: [https://03c8d80c.zen-alpha-pentest.pages.dev](https://03c8d80c.zen-alpha-pentest.pages.dev/) - Zen Alpha Pentest
- **AI Analysis**: [https://v2-0.zen-ai-pentest.pages.dev/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](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](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](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
```bash
# 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](TESTING_MASSIVE_SCALE.md) | [docs/TESTING.md](docs/TESTING.md)
---
## 🚀 Quick Start
[](https://github.com/SHAdd0WTAka/zen-ai-pentest/releases)
[](https://python.org)
[](docker/)
[](https://github.com/SHAdd0WTAka/Zen-Ai-Pentest/actions)
[](SECURITY_AUDIT_REPORT_2026-03-20.md)
[](https://discord.gg/BSmCqjhY)
[](docs/)
[](ROADMAP_2026.md)
---
## 📚 Table of Contents
- [Overview](#-overview)
- [Features](#-features)
- [For AI Agents](#-for-ai-agents)
- [Quick Start](#-quick-start)
- [Installation](#-installation)
- [Usage](#-usage)
- [Architecture](#-architecture)
- [API Reference](#-api-reference)
- [Project Structure](#-project-structure)
- [Configuration](#-configuration)
- [Secret Management](#-secret-management)
- [Testing](#-testing)
- [Docker Deployment](#-docker-deployment)
- [Safety First](#-safety-first)
- [Documentation](#-documentation)
- [Contributing](#-contributing)
- [Community & Support](#-community--support)
- [License](#-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.
```mermaid
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](docs/TOOLS_INVENTORY.md))
- 🔧 **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](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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Automated Kali Linux setup
python scripts/setup_vms.py --kali
# Manual setup
# See docs/setup/VIRTUALBOX_SETUP.md
```
---
## 📖 Installation
For detailed installation instructions, see:
- **[Docker Installation](docs/INSTALLATION.md#quick-start-docker)**
- **[Local Installation](docs/INSTALLATION.md#local-installation)**
- **[Production Deployment](docs/INSTALLATION.md#production-deployment)**
- **[VirtualBox Setup](docs/setup/VIRTUALBOX_SETUP.md)**
---
## 💻 Usage
### Python API
```python
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
```bash
# 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)
```javascript
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](https://codecov.io/gh/SHAdd0WTAka/Zen-Ai-Pentest)
For detailed architecture documentation, see [docs/architecture.md](docs/architecture.md).
---
## 📡 API Reference
- **[API Documentation](docs/API.md)** - Complete REST API reference
- **[WebSocket API](docs/API.md#websocket)** - Real-time updates
- **[Authentication](docs/API.md#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.
```bash
# 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:**
```yaml
# ~/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](mcp/obsidian/README.md) | [Detailed Architecture](docs/SECRETS_ARCHITECTURE.md)
---
### 📄 Option 2: Environment Variables (.env)
Quick setup for development using a local `.env` file.
```bash
# 1. Copy example file
cp .env.example .env
# 2. Edit with your secrets
nano .env
# 3. Load environment
source .env
```
**Example `.env`:**
```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`!
```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:
```bash
# 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
```bash
# 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:
```json
{
"mcpServers": {
"obsidian-secrets": {
"command": "python3",
"args": ["mcp/obsidian/server.py"]
}
}
}
```
📖 **Full Documentation**: [mcp/obsidian/README.md](mcp/obsidian/README.md)
---
⚠️ **Important**: Ensure your `.gitignore` includes:
```gitignore
.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
```bash
# 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](https://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**
```bash
# Windows: Setup-Launcher starten
scripts\docker-setup.bat
# Oder direkt in Ubuntu WSL:
./scripts/setup_docker_wsl2.sh
```
**Option 2: Docker Desktop (Windows)**
```powershell
# PowerShell als Administrator:
powershell -ExecutionPolicy Bypass -File scripts/setup_docker_windows.ps1
```
📖 **[Komplette Docker + WSL2 Anleitung](DOCKER_WSL2_SETUP.md)** - Detaillierte Schritte für beide Optionen
### Full Stack Starten
```bash
# 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](DOCKER.md)**
---
## ☁️ 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](https://dde4fab5.zen-ai-pentest.pages.dev/) | ✅ Live |
| **Dashboard** | [https://dde4fab5.zen-ai-pentest.pages.dev/dashboard](https://dde4fab5.zen-ai-pentest.pages.dev/dashboard) | ✅ Ready |
| **Login** | `/login` | ✅ Demo Mode |
### 🔄 Automated Deployment
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
### 🛠️ Manual Deployment
```bash
# 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](docs/DEPLOYMENT.md) | Deployment guide |
| [docs/BENCHMARK_STATUS.md](docs/BENCHMARK_STATUS.md) | Benchmark results |
| [docs/SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md) | Security audit report |
| [docs/PERFORMANCE.md](docs/PERFORMANCE.md) | Performance characteristics |
| [DOCKER.md](DOCKER.md) | Docker deployment guide |
| [GUARDRAILS.md](GUARDRAILS.md) | Security guardrails documentation |
| [GUARDRAILS_INTEGRATION.md](GUARDRAILS_INTEGRATION.md) | Guardrails integration guide |
| [VPN_INTEGRATION.md](VPN_INTEGRATION.md) | VPN setup and usage |
| [DEMO_E2E.md](DEMO_E2E.md) | End-to-end demo documentation |
| [AGENTS.md](AGENTS.md) | Agent development guide |
---
## 🤝 Contributing
We welcome contributions! Please see:
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community standards
- **[CONTRIBUTORS.md](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
---
## 🌐 Community & Support
Join our growing community!
### Quick Links
| Platform | Link | QR Code |
|----------|------|---------|
| 💬 **GitHub** | [github.com/SHAdd0WTAka/Zen-Ai-Pentest](https://github.com/SHAdd0WTAka/Zen-Ai-Pentest) | [📱 Scan](docs/qr_codes/01_github_repo.png) |
| 🎮 **Discord** | [discord.gg/zJZUJwK9AC](https://discord.gg/zJZUJwK9AC) | [📱 Scan](docs/qr_codes/02_discord.png) |
| 🌐 **Website** | [zen-ai-pentest.pages.dev](https://dde4fab5.zen-ai-pentest.pages.dev/) | [📱 Scan](docs/qr_codes/03_website.png) |
| 📊 **Dashboard** | [pages.dev/dashboard](https://dde4fab5.zen-ai-pentest.pages.dev/dashboard) | [📱 Scan](docs/qr_codes/04_dashboard.png) |
### 📱 All QR Codes
View our complete QR code gallery: [docs/qr_codes/index.html](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](docs/)** - Comprehensive guides
- 🐛 **[Issue Tracker](https://github.com/SHAdd0WTAka/zen-ai-pentest/issues)** - Bug reports
- 📧 **[Email](mailto:support@zen-ai-pentest.dev)** - Direct contact
See [SUPPORT.md](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](LICENSE) file for details.
---
## 🙏 Acknowledgments
- [LangGraph](https://github.com/langchain-ai/langgraph) - Agent framework
- [FastAPI](https://fastapi.tiangolo.com/) - Web framework
- [Kali Linux](https://www.kali.org/) - 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
- **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)](assets/videos/demo-video.mp4)**
Full demonstration of the Zen-AI-Pentest framework in action.
---
## 📸 Repository Images
All screenshots, diagrams and visual assets for this repository:
📁 **[View All Images](assets/images/)**
### 🤖 AI & Development
| Image | Description |
|-------|-------------|
| [Battle of the AIs](assets/images/battle_of_the_ais.png) | Claude vs Codex - AI Unit Test Battle |
| [Obsidian Vault Setup](assets/images/obsidian_vault_setup.png) | Terminal: GitHub Token & MCP Server Setup |
### 🎨 Branding & Artwork
| Image | Description |
|-------|-------------|
| [Kimi AI Artwork](assets/images/branding/kimi-ai-artwork.jpeg) | Custom AI-generated artwork |
### 📊 Status & Metrics
| Image | Description |
|-------|-------------|
| [Repo Status Card](assets/images/status/repo_status_card.png) | Live repository status dashboard |
### 🖥️ Screenshots
| Image | Description |
|-------|-------------|
| [Main Dashboard](assets/images/screenshot_20260219_092020.png) | Framework main dashboard |
| [Demo Screenshot](assets/images/screenshots/demo_screenshot.png) | Live demo view |
| [Activity Screenshot 1](assets/images/screenshots/Screenshot%202026-02-14%20at%2016-46-09%20Activity%20%C2%B7%20SHAdd0WTAka_Zen-Ai-Pentest.png) | GitHub Activity View |
| [Activity Screenshot 2](assets/images/screenshots/Screenshot%202026-02-14%20at%2017-01-33%20Activity%20%C2%B7%20SHAdd0WTAka_Zen-Ai-Pentest.png) | GitHub Activity View 2 |
| [Activity Screenshot 3](assets/images/screenshots/Screenshot%202026-02-14%20at%2017-31-13%20Activity%20%C2%B7%20SHAdd0WTAka_Zen-Ai-Pentest.png) | GitHub Activity View 3 |
| [Must Have Features](assets/images/screenshots/MUSTHAVE.png) | Feature Requirements |
| [Must Have Features 2](assets/images/screenshots/MUSTHAVE_2.png) | Feature Requirements 2 |
### 🤖 Agent Zero
| Image | Description |
|-------|-------------|
| [Agent Zero 1](assets/images/agent-zero/Screenshot%202026-03-05%20at%2021-53-13%20Agent%20Zero_78e803.png) | Agent Zero Interface |
| [Agent Zero 2](assets/images/agent-zero/Screenshot%202026-03-05%20at%2021-53-44%20Agent%20Zero_631d87.png) | Agent Zero Dashboard |
| [Agent Zero 3](assets/images/agent-zero/Screenshot%202026-03-05%20at%2021-54-14%20Agent%20Zero_a1633f.png) | Agent Zero Tasks |
| [Agent Zero 4](assets/images/agent-zero/Screenshot%202026-03-05%20at%2021-55-24%20Agent%20Zero_fca218.png) | Agent Zero Settings |
### 📱 QR Codes
| Image | Description |
|-------|-------------|
| [GitHub Repo](assets/images/qr-codes/01_github_repo.png) | GitHub Repository QR |
| [Discord](assets/images/qr-codes/02_discord.png) | Discord Community QR |
| [Website](assets/images/qr-codes/03_website.png) | Website QR |
| [Dashboard](assets/images/qr-codes/04_dashboard.png) | Dashboard QR |
| [Hemisphere Sync](assets/images/qr-codes/hemisphere_sync.png) | Hemisphere Sync Artwork |
| [QR Grid](assets/images/qr-codes/qr_grid_preview.png) | QR Code Grid Preview |
### 📑 Presentation Slides (1-13)
| | | | | | | |
|---|---|---|---|---|---|---|
| [Slide 1](assets/images/presentation/1.png) | [Slide 2](assets/images/presentation/2.png) | [Slide 3](assets/images/presentation/3.png) | [Slide 4](assets/images/presentation/4.png) | [Slide 5](assets/images/presentation/5.png) | [Slide 6](assets/images/presentation/6.png) | [Slide 7](assets/images/presentation/7.png) |
| [Slide 8](assets/images/presentation/8.png) | [Slide 9](assets/images/presentation/9.png) | [Slide 10](assets/images/presentation/10.png) | [Slide 11](assets/images/presentation/11.png) | [Slide 12](assets/images/presentation/12.png) | [Slide 13](assets/images/presentation/13.png) | |
### 🎯 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:
```python
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](docs/API_V1_ROUTES.md) for full documentation.
## Test Codecov
Current coverage: **10.19%** (target: 80%)
Run tests:
```bash
# 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
```bash
# 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](docs/Coverage-Strategie-80-Prozent.pdf)** - Vollständige Strategie zur Steigerung der Code-Coverage von 10% auf 80%
- **[COVERAGE_STRATEGY.md](COVERAGE_STRATEGY.md)** - Markdown-Version der Strategie
- **[TEST_STATUS.md](TEST_STATUS.md)** - Aktueller Test-Status
### Codecov-Dashboards
- [Coveralls](https://coveralls.io/github/SHAdd0WTAka/Zen-Ai-Pentest)
- [Codecov](https://codecov.io/gh/SHAdd0WTAka/Zen-Ai-Pentest)
---
*Letzte Aktualisierung: 31.03.2026*