Zen-AI-Pentest

Overview#

Zen-AI-Pentest is a professional AI-powered penetration testing framework designed to address the challenges of traditional penetration testing: heavy reliance on manual expertise, fragmented tools, long testing cycles, and high false positive rates. Through autonomous AI agent orchestration, it achieves end-to-end automation from reconnaissance to reporting.

Core Capabilities#

ReAct Autonomous Agent#

• Reasoning Loop: Reason → Act → Observe → Reflect pattern
• State Machine: IDLE → PLANNING → EXECUTING → OBSERVING → REFLECTING → COMPLETED
• Memory System: Short-term, long-term, and context window management
• Self-Correction: Retry logic and adaptive planning
• Human-in-the-Loop: Optional pause on critical decisions

11 AI Personas System#

Integrated Security Tools (40+)#

• Network: Nmap, Masscan, Scapy, Tshark
• Web: Nuclei, SQLMap, Nikto, OWASP ZAP, BurpSuite, FFuF, Gobuster
• Recon: Subfinder, Amass, HTTPX, WhatWeb, WAFW00F
• AD: BloodHound, CrackMapExec, Responder
• OSINT: Sherlock, Scout, Ignorant
• Secrets: TruffleHog, Trivy, Semgrep

Risk Engine#

• Multi-factor validation + Bayesian filtering for false positive reduction
• CVSS/EPSS scoring support
• Business impact analysis (financial, compliance, reputation risks)
• Automated finding prioritization

Safety Mechanisms#

• IP Validation: Blocks private network scanning (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Domain Filtering: Prevents .local, .internal, localhost scanning
• 4-Tier Risk Control: SAFE(0) → NORMAL(1) → ELEVATED(2) → AGGRESSIVE(3)
• Rate Limiting: Abuse prevention

System Architecture#

Client Layer (React Web UI / Python CLI / REST API)
    ↓ HTTPS / JWT
Gateway Layer (FastAPI + WebSocket, Auth, Workflow API)
    ↓
Orchestration Layer (Guardrails, Task Queue, Risk Levels)
    ↓ WebSocket
Agent Layer (Docker-containerized Agent Pool)
    ↓
Tool Layer (40+ Security Tools)
    ↓
Data Layer (PostgreSQL + Redis + File Storage)

Deployment#

Docker (Recommended)#

git clone https://github.com/SHAdd0WTAka/zen-ai-pentest.git
cd zen-ai-pentest
cp .env.example .env
docker-compose up -d
# Dashboard: http://localhost:3000
# API Docs: http://localhost:8000/docs

Local Installation#

pip install -r requirements.txt
python database/models.py
python api/main.py

Usage Examples#

Python API#

from agents.react_agent import ReActAgent, ReActAgentConfig

config = ReActAgentConfig(max_iterations=10, use_vm=True, vm_name="kali-pentest")
agent = ReActAgent(config)
result = agent.run(target="example.com", objective="Comprehensive security assessment")
print(agent.generate_report(result))

REST API#

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

curl -X POST http://localhost:8000/scans \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Network Scan","target":"192.168.1.0/24","scan_type":"network"}'

Use Cases#

• Automated penetration testing workflows
• Network and web vulnerability scanning
• Compliance report generation (PDF/HTML)
• CI/CD security integration (GitHub Actions, GitLab CI, Jenkins)
• Bug bounty vulnerability hunting
• Enterprise security asset assessment

Project Activity#

• 926+ commits
• 9 releases
• MIT License
• Actively maintained

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.