Skip to main content

Advanced AI-Powered Penetration Testing Framework with Multi-Agent Orchestration

Project description

Zen-AI-Pentest

Repository Status

๐Ÿ›ก๏ธ Professional AI-Powered Penetration Testing Framework

Python

  • Guest Control: Execute tools inside isolated VMs

๐Ÿš€ 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

๐ŸŽฏ Real Data Execution - No Mocks!

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

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

๐Ÿ“– Enhanced Tools: README_ENHANCED_TOOLS.md

All tools run with safety controls:

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

๐Ÿ“– Details: IMPLEMENTATION_SUMMARY.md


๐Ÿš€ Quick Start

Version Python License Commits Phase

PyPI Docker Tests CI Security codecov

Discord Docs Roadmap OpenSSF Marketplace Authors


๐Ÿ“š Table of Contents


๐ŸŽฏ Overview

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

  graph TB
      subgraph "Client Interface"
          WebUI[๐ŸŒ Web UI]
          CLI[๐Ÿ’ป CLI]
          API_Client[๐Ÿ”Œ REST API]
      end

      subgraph "API Gateway"
          FastAPI[FastAPI + WebSocket]
          Auth[๐Ÿ” JWT/RBAC]
          AgentMgr[๐Ÿค– Agent Manager]
      end

      subgraph "Workflow Orchestrator"
          Guardrails[๐Ÿ›ก๏ธ Guardrails]
          TaskQueue[๐Ÿ“Š Task Queue]
          RiskLevels[โš ๏ธ Risk Levels 0-3]
          VPN[๐Ÿ”’ VPN Check]
          State[๐Ÿ“ˆ State Machine]
      end

      subgraph "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 "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 --> Postgres
      Whois --> Redis
      SQLMap --> Storage

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: 40+ integrated security tools
  • ๐Ÿ”ง 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

QR Codes
โ˜๏ธ 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 20+ 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

๐Ÿ›ก๏ธ 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 accidental DoS

๐Ÿค– 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

๐Ÿ› ๏ธ 40+ Integrated Tools

Category Tools
Network Nmap, Masscan, Scapy, Tshark
Web BurpSuite, SQLMap, Gobuster, OWASP ZAP
Exploitation Metasploit Framework
Brute Force Hydra, Hashcat
Reconnaissance Amass, Nuclei, TheHarvester, Subdomain Scanner
Active Directory BloodHound, CrackMapExec, Responder
Wireless Aircrack-ng Suite

๐Ÿ” Subdomain Scanner

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

๐Ÿค– For AI Agents

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

๐Ÿ”” Notifications & Integrations

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

โ˜๏ธ Multi-Cloud & Virtualization

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

Option 1: Docker (Recommended)

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

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

# Start full stack
docker-compose up -d

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

Option 2: Local Installation

# Install dependencies
pip install -r requirements.txt

# Initialize database
python database/models.py

# Start API server
python api/main.py

# Run subdomain scan
python scan_target_subdomains.py

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

Option 3: AI Personas Quick Start

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

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

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

Option 4: VirtualBox VM Setup

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

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

๐Ÿ“– Installation

For detailed installation instructions, see:


๐Ÿ’ป Usage

Python API

from agents.react_agent import ReActAgent, ReActAgentConfig

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

# Create agent
agent = ReActAgent(config)

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

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

REST API

# Authentication
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Create scan
curl -X POST http://localhost:8000/scans \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Network Scan","target":"192.168.1.0/24","scan_type":"network","config":{"ports":"top-1000"}}'

# Execute tool
curl -X POST http://localhost:8000/tools/execute \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"tool_name":"nmap_scan","target":"scanme.nmap.org","parameters":{"ports":"22,80,443"}}'

# Generate report
curl -X POST http://localhost:8000/reports \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"scan_id":1,"format":"pdf","template":"default"}'

WebSocket (Real-Time)

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

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

๐Ÿ—๏ธ System Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                         CLIENT INTERFACE                            โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”              โ”‚
โ”‚  โ”‚   ๐ŸŒ Web UI  โ”‚  โ”‚   ๐Ÿ’ป CLI     โ”‚  โ”‚   ๐Ÿ”Œ API     โ”‚              โ”‚
โ”‚  โ”‚   (React)    โ”‚  โ”‚   (Python)   โ”‚  โ”‚   (REST)     โ”‚              โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜              โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
          โ”‚                 โ”‚                 โ”‚
          โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                            โ”‚ 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  โ”‚  โ”‚
โ”‚  โ”‚          โ”‚ โ”‚          โ”‚ โ”‚          โ”‚ โ”‚          โ”‚ โ”‚          โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                          โ”‚
                          โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                         DATA LAYER                                  โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”              โ”‚
โ”‚  โ”‚   ๐Ÿ˜ Postgre โ”‚  โ”‚   โšก Redis   โ”‚  โ”‚   ๐Ÿ“ File    โ”‚              โ”‚
โ”‚  โ”‚   SQL        โ”‚  โ”‚   Cache      โ”‚  โ”‚   Storage    โ”‚              โ”‚
โ”‚  โ”‚   (State)    โ”‚  โ”‚   (Queue)    โ”‚  โ”‚   (Reports)  โ”‚              โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜              โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

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


๐Ÿ“ก API Reference


๐Ÿ“ 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/                 # 40+ Security Tools
โ”‚   โ”œโ”€โ”€ Network: nmap, masscan, scapy, tshark
โ”‚   โ”œโ”€โ”€ Web: nuclei, sqlmap, nikto, zap, burpsuite, ffuf, gobuster
โ”‚   โ”œโ”€โ”€ Recon: subfinder, amass, httpx, whatweb, wafw00f, subdomain_scan, unified_recon
โ”‚   โ”œโ”€โ”€ AD: bloodhound, crackmapexec, responder
โ”‚   โ”œโ”€โ”€ OSINT: sherlock, scout, ignorant
โ”‚   โ”œโ”€โ”€ Secrets: trufflehog, trivy
โ”‚   โ”œโ”€โ”€ Wireless: aircrack
โ”‚   โ”œโ”€โ”€ Code: semgrep
โ”‚   โ”œโ”€โ”€ 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
โ””โ”€โ”€ scripts/               # Setup Scripts

๐Ÿ”ง Configuration

Environment Variables

# 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=...

See .env.example for all options.


๐Ÿงช Testing

# Run all tests
pytest

# With coverage
pytest --cov=. --cov-report=html

# Specific test file
pytest tests/test_react_agent.py -v

# Integration tests
pytest tests/integration/ -v

๐Ÿณ Docker Deployment

Quick Setup (WSL2 + Docker)

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

Option 1: Automatisches Setup

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

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

Option 2: Docker Desktop (Windows)

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

๐Ÿ“– Komplette Docker + WSL2 Anleitung - Detaillierte Schritte fรผr beide Optionen

Full Stack Starten

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

# Check status
docker-compose ps

# View logs
docker-compose logs -f api

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

Services

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

๐Ÿ“– Complete Docker Guide


๐Ÿ›ก๏ธ 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
DOCKER.md Docker deployment guide
GUARDRAILS.md Security guardrails documentation
GUARDRAILS_INTEGRATION.md Guardrails integration guide
VPN_INTEGRATION.md VPN setup and usage
DEMO_E2E.md End-to-end demo documentation
AGENTS.md Agent development guide

๐Ÿค Contributing

We welcome contributions! Please see:

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
๐ŸŽฎ Discord discord.gg/zJZUJwK9AC ๐Ÿ“ฑ Scan
๐Ÿ’ฌ GitHub Discussions SHAdd0WTAka/zen-ai-pentest/discussions ๐Ÿ“ฑ Scan
๐Ÿ“ฆ PyPI Package pypi.org/project/zen-ai-pentest ๐Ÿ“ฑ Scan

๐Ÿ“ฑ All QR Codes

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

๐Ÿ’ฌ Discord Server "Zen-Ai"

Fully configured with 11 channels:

  • ๐Ÿ“ข #announcements
  • ๐Ÿ“œ #rules
  • ๐Ÿ’ฌ #general
  • ๐Ÿ‘‹ #introductions
  • ๐Ÿ“š #knowledge-base
  • ๐Ÿค– #tools-automation
  • ๐Ÿ”’ #security-research
  • ๐Ÿง  #ai-ml-discussion
  • ๐Ÿ› #bug-reports
  • ๐Ÿ’ก #feature-requests
  • ๐Ÿ†˜ #support

๐Ÿ“ง Support

See SUPPORT.md for detailed support options.


โš ๏ธ Disclaimer

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

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

๐Ÿ“„ License

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


๐Ÿ™ Acknowledgments

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

๐Ÿ‘ฅ Authors & Team

Core Development Team

SHAdd0WTAka
@SHAdd0WTAka

Project Founder & Lead Developer
Security Architect
Kimi AI
Kimi AI

AI Development Partner
Architecture & Design

AI Contributors

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

Special Thanks

  • Grok (xAI) - Strategic analysis and competitive research
  • GitHub Copilot - Code assistance and suggestions
  • Security Community - Feedback, bug reports, and feature requests

๐ŸŽจ Project Artwork

Hemisphere Sync

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

zen_ai_pentest-3.0.0.tar.gz (2.6 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

zen_ai_pentest-3.0.0-py3-none-any.whl (436.6 kB view details)

Uploaded Python 3

File details

Details for the file zen_ai_pentest-3.0.0.tar.gz.

File metadata

  • Download URL: zen_ai_pentest-3.0.0.tar.gz
  • Upload date:
  • Size: 2.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.12

File hashes

Hashes for zen_ai_pentest-3.0.0.tar.gz
Algorithm Hash digest
SHA256 8dfc8005f52d48bc35b3db5a8116b6a1d4a2686e07a7549fb524f99664972207
MD5 121f7b5c7415eb86ca6f9f9acc3a2c90
BLAKE2b-256 d33ea5bf57b21d84b27deb464a97b8c68ef417f8f92338c6d21ca3e548440321

See more details on using hashes here.

File details

Details for the file zen_ai_pentest-3.0.0-py3-none-any.whl.

File metadata

  • Download URL: zen_ai_pentest-3.0.0-py3-none-any.whl
  • Upload date:
  • Size: 436.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.12

File hashes

Hashes for zen_ai_pentest-3.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 b0e81468873185e74d65b6743857f06a8216556259aa7922d887e78d17df2e82
MD5 12d6f566d805f23bed174ced26f3a86b
BLAKE2b-256 2c0a922d4648e785bdc7522d07d296b354383a7df5e12e1c11bb6ec1bbd44c22

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page