Zen-AI-Pentest Architecture Documentation

Version: 3.0.0
Last Updated: 2026-03-31

System Overview
Component Architecture
Data Flow
Deployment Architecture
Security Architecture
Technology Stack

System Overview

Zen-AI-Pentest is a distributed, microservices-oriented penetration testing platform built for enterprise scalability and security. The architecture follows clean design principles with clear separation of concerns.

High-Level Architecture

%%{init: {'theme': 'base', 'themeVariables': {'background': '#0d1117', 'primaryTextColor': '#ffffff', 'primaryColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#58a6ff', 'secondaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'mainBkg': '#0d1117', 'nodeBorder': '#58a6ff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff'}}}%%
graph TB
    subgraph CLIENT_LAYER["CLIENT LAYER"]
        WebUI["Web UI (React)"]
        CLI["CLI (Python)"]
        Mobile["Mobile (PWA)"]
        ThirdParty["Third-party (Burp, etc)"]
    end

    subgraph GATEWAY_LAYER["GATEWAY LAYER"]
        Nginx["Nginx / Cloudflare / Traefik"]
        RateLimit["Rate Limit"]
        WAF["WAF Rules (OWASP CRS)"]
        TLS["SSL/TLS Termination"]
    end

    subgraph API_LAYER["API LAYER"]
        FastAPI["FastAPI (Async)"]
        REST["REST API (/api/v1/*)"]
        WS["WebSocket (/ws/*)"]
        Health["Health Checks"]
        JWT["JWT Auth"]
        RateM["Rate Limiter"]
        CSRF["CSRF Protection"]
        CORS["CORS Handler"]
        Logging["Request Logging"]
        SecHeaders["Security Headers"]
    end

    subgraph CORE_LAYER["CORE LAYER"]
        TaskMgr["Task Manager"]
        EventBus["Event Bus"]
        StateMgr["State Manager"]
        Scheduler["Scan Scheduler"]
        Dashboard["Dashboard"]
        AuditLogger["Audit Logger"]
        AnalysisBot["Analysis Bot"]
    end

    subgraph AGENT_LAYER["AGENT LAYER"]
        Reasoning["Reasoning"]
        Planning["Planning"]
        Execution["Execution"]
        Researcher["Researcher Agent"]
        Analyst["Analyst Agent"]
        Exploiter["Exploiter Agent"]
    end

    subgraph SECURITY_LAYER["SECURITY LAYER"]
        IPValidator["IP Validator"]
        DomainFilter["Domain Filter"]
        RiskEnforcer["Risk Enforcer"]
        DockerSandbox["Docker Sandbox"]
        RiskEngine["Risk Engine"]
    end

    subgraph TOOLS_LAYER["TOOLS LAYER (72+)"]
        Nmap["Nmap"]
        Nuclei["Nuclei"]
        SQLMap["SQLMap"]
        FFuF["FFuF"]
        Subfinder["Subfinder"]
        HTTPX["HTTPX"]
        ZAP["ZAP"]
        Amass["Amass"]
        Metasploit["Metasploit"]
    end

    subgraph DATA_LAYER["DATA LAYER"]
        PostgreSQL["PostgreSQL"]
        Redis["Redis"]
        MinIO["MinIO / S3"]
        Elastic["Elasticsearch"]
    end

    CLIENT_LAYER --> GATEWAY_LAYER
    GATEWAY_LAYER --> API_LAYER
    API_LAYER --> CORE_LAYER
    CORE_LAYER --> AGENT_LAYER
    AGENT_LAYER --> SECURITY_LAYER
    SECURITY_LAYER --> TOOLS_LAYER
    CORE_LAYER --> DATA_LAYER

Component Architecture

Core Components

1. ZenOrchestrator

The central coordination hub managing all system components.

Responsibilities:

Task lifecycle management (submit → queue → execute → monitor → complete)
Event propagation via EventBus
State management across distributed components
Integration with Analysis Bot and Audit Logger

Key Classes:

class ZenOrchestrator:
    """Central coordination hub."""

    async def submit_task(self, task: Task) -> TaskId:
        """Submit a new task to the queue."""

    async def execute_task(self, task_id: TaskId) -> Result:
        """Execute a task with worker pool."""

    def publish_event(self, event: Event) -> None:
        """Publish event to subscribed handlers."""

2. ReAct Agent Framework

Advanced reasoning and action loop for autonomous penetration testing.

Components:

Reasoner: Analyzes current state and decides next actions
Planner: Sequences tools and strategies
Executor: Runs tools safely with guardrails
Memory: Maintains context across operations

┌─────────────────────────────────────────────────────────┐
│                    ReAct Loop                           │
│                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────┐ │
│  │   Thought    │───▶│    Action    │───▶│ Observation│ │
│  │  (Reasoning) │    │  (Tool Exec) │    │ (Result)  │ │
│  └──────────────┘    └──────────────┘    └─────┬─────┘ │
│        ▲─────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────┘

3. Analysis Bot

AI-powered vulnerability analysis and risk assessment.

Pipeline:

Raw Tool Output → Parser → Analyzer → Risk Scorer → Recommendation Engine
                     ↓           ↓           ↓              ↓
                Structured   Vuln Class   CVSS/EPSS    Remediation
                 Data        Detection     Score         Advice

4. Guardrails System

Multi-layer security protection.

┌─────────────────────────────────────────────────────────┐
│                    Request Flow                         │
│                                                         │
│  Input → IP Validator → Domain Filter → Risk Enforcer  │
│            ↓                  ↓              ↓          │
│         Block: 10.x         Block: .local  Block: L3   │
│         Block: 192.168      Block: loc     Check: Perms│
│                                                         │
│  → Docker Sandbox → Tool Executor → Output Validator    │
│         ↓                ↓                  ↓          │
│    Containerized     Timeout Limits    Sanitize Output │
│    Resource Caps     Network Isolate   Strip Secrets   │
└─────────────────────────────────────────────────────────┘

Data Flow

Scan Execution Flow

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#58a6ff', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#58a6ff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
sequenceDiagram
    participant User
    participant API as FastAPI
    participant Orch as Orchestrator
    participant Guard as Guardrails
    participant Agent as ReAct Agent
    participant Tool as Security Tool
    participant DB as PostgreSQL
    participant Redis as Redis

    User->>API: POST /api/v1/scans
    API->>Guard: Validate Target
    Guard-->>API: ✓ Valid (Public IP)
    API->>Orch: submit_task()
    Orch->>Redis: Queue Task
    Orch-->>API: task_id
    API-->>User: 202 Accepted

    loop Worker Processing
        Orch->>Redis: dequeue_task()
        Orch->>Agent: execute_scan()

        loop Tool Execution
            Agent->>Agent: Reason → Action
            Agent->>Guard: Check Risk Level
            Guard-->>Agent: ✓ Approved
            Agent->>Tool: Execute (Docker)
            Tool-->>Agent: Raw Output
            Agent->>Agent: Parse & Analyze
        end

        Agent->>DB: Save Findings
        Orch->>Redis: Publish Progress
    end

    Orch-->>User: WebSocket: Complete

Real-time Update Flow

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#0d1117', 'primaryColor': '#58a6ff', 'secondaryColor': '#161b22', 'tertiaryColor': '#0d1117', 'primaryBorderColor': '#58a6ff', 'secondaryBorderColor': '#30363d', 'tertiaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'fontSize': '14px', 'fontFamily': '-apple-system,BlinkMacSystemFont,Segoe UI,Noto Sans,Helvetica,Arial,sans-serif', 'textColor': '#ffffff', 'primaryTextColor': '#ffffff', 'secondaryTextColor': '#ffffff', 'tertiaryTextColor': '#ffffff', 'mainBkg': '#0d1117', 'nodeBorder': '#58a6ff', 'clusterBorder': '#30363d', 'clusterBkg': '#161b22', 'titleColor': '#ffffff' }}}%%
sequenceDiagram
    participant Client
    participant WS as WebSocket Gateway
    participant Redis as Redis Pub/Sub
    participant Orch as Orchestrator
    participant Agent as Agent

    Client->>WS: WS Connect + JWT Auth
    WS-->>Client: Connection Accepted

    Orch->>Redis: Publish scan_update
    Redis->>WS: Broadcast
    WS->>Client: {type: "scan_update", ...}

    Agent->>Redis: Publish finding
    Redis->>WS: Broadcast
    WS->>Client: {type: "finding", ...}

Deployment Architecture

Docker Compose (Development)

# docker-compose.yml
version: '3.8'

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/zen_pentest
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  worker:
    build: .
    command: celery -A celery_app worker --loglevel=info
    depends_on:
      - redis
      - db

  frontend:
    build: ./web_ui
    ports:
      - "3000:80"
    depends_on:
      - api

Kubernetes (Production)

# k8s/ deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: zen-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: zen-api
  template:
    spec:
      containers:
      - name: api
        image: zen-ai-pentest:v3.0.0
        ports:
        - containerPort: 8000
        envFrom:
        - secretRef:
            name: zen-secrets
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000

High Availability Architecture

┌─────────────────────────────────────────────────────────┐
│                     CDN / WAF                            │
│                   (Cloudflare/AWS)                       │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│              Load Balancer (Nginx/ALB)                   │
│                 TLS Termination                          │
└─────────────────────────┬───────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
┌───────▼──────┐ ┌────────▼────────┐ ┌──────▼───────┐
│   API Pod 1  │ │    API Pod 2    │ │   API Pod 3  │
│  (FastAPI)   │ │   (FastAPI)     │ │  (FastAPI)   │
└───────┬──────┘ └────────┬────────┘ └──────┬───────┘
        │                 │                 │
        └─────────────────┼─────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
┌───────▼──────┐ ┌────────▼────────┐ ┌──────▼───────┐
│  Worker Pod 1│ │   Worker Pod 2  │ │  Worker Pod 3│
│   (Celery)   │ │    (Celery)     │ │   (Celery)   │
└──────────────┘ └─────────────────┘ └──────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
┌───────▼──────┐ ┌────────▼────────┐ ┌──────▼───────┐
│  PostgreSQL  │ │     Redis       │ │    MinIO     │
│   (Primary)  │ │   (Cluster)     │ │   (S3 API)   │
└──────────────┘ └─────────────────┘ └──────────────┘

Security Architecture

Defense in Depth

┌─────────────────────────────────────────────────────────┐
│  Layer 7: Application Security                           │
│  ├─ Input Validation & Sanitization                     │
│  ├─ Parameterized Queries (SQL Injection Prevention)    │
│  ├─ Output Encoding (XSS Prevention)                    │
│  └─ CSRF Tokens                                         │
├─────────────────────────────────────────────────────────┤
│  Layer 6: Authentication & Authorization                │
│  ├─ JWT with Short Expiry                               │
│  ├─ RBAC with Principle of Least Privilege              │
│  ├─ MFA Support                                         │
│  └─ Session Management                                  │
├─────────────────────────────────────────────────────────┤
│  Layer 5: API Security                                  │
│  ├─ Rate Limiting (100 req/min default)                 │
│  ├─ Request Size Limits                                 │
│  ├─ Timeout Controls                                    │
│  └─ CORS Configuration                                  │
├─────────────────────────────────────────────────────────┤
│  Layer 4: Network Security                              │
│  ├─ TLS 1.3 Only                                        │
│  ├─ HSTS Headers                                        │
│  ├─ Private IP Blocking                                 │
│  └─ WAF Rules (OWASP CRS)                               │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Container Security                            │
│  ├─ Non-root User Execution                             │
│  ├─ Read-only Root Filesystem                           │
│  ├─ Resource Limits (CPU/Memory)                        │
│  └─ Network Policies                                    │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Tool Execution Security                       │
│  ├─ Docker Sandbox                                      │
│  ├─ Timeout Enforcement                                 │
│  ├─ Output Sanitization                                 │
│  └─ Risk Level Enforcement                              │
├─────────────────────────────────────────────────────────┤
│  Layer 1: Infrastructure Security                       │
│  ├─ Secret Management (Vault/K8s Secrets)               │
│  ├─ Encrypted Database at Rest                          │
│  ├─ Encrypted Network Traffic                           │
│  └─ Audit Logging                                       │
└─────────────────────────────────────────────────────────┘

Secret Management

┌─────────────────────────────────────────────────────────┐
│                  Secret Lifecycle                       │
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│  │ Generate │───▶│  Store   │───▶│  Inject  │          │
│  │ (Vault)  │    │ (Vault)  │    │ (K8s)    │          │
│  └──────────┘    └────┬─────┘    └────┬─────┘          │
│                       │              │                  │
│                       ▼              ▼                  │
│                 ┌──────────┐    ┌──────────┐           │
│                 │ Rotate   │    │  Revoke  │           │
│                 │ (Auto)   │    │ (On Comp)│           │
│                 └──────────┘    └──────────┘           │
└─────────────────────────────────────────────────────────┘

Technology Stack

Core Stack

Component	Technology	Version	Purpose
Language	Python	3.11+	Application code
Web Framework	FastAPI	0.116.2+	REST API
Validation	Pydantic	2.0+	Data models
Database	PostgreSQL	15+	Primary data store
ORM	SQLAlchemy	2.0+	Database abstraction
Cache	Redis	7+	Caching & queuing
Task Queue	Celery	5.3+	Background tasks
Auth	JWT/PyJWT	2.11+	Authentication

AI/LLM Stack

Component	Technology	Purpose
Primary Backend	Kimi AI	Default LLM provider
Alternative	OpenAI GPT	Fallback option
Alternative	Anthropic Claude	Analysis tasks
Local	Ollama	On-premise deployment

Security Tools

Category	Tools
Network Scanning	Nmap, Masscan, Zmap
Web Scanning	Nuclei, ZAP, Nikto, FFuF
Vulnerability	SQLMap, Nuclei
Reconnaissance	Subfinder, Amass, HTTPX
OSINT	Sherlock, WhatWeb, WAFW00F

Infrastructure

Component	Technology
Container Runtime	Docker
Orchestration	Kubernetes
Package Manager	Helm
Service Mesh	Istio (optional)
Monitoring	Prometheus + Grafana
Logging	ELK Stack / Loki
Tracing	Jaeger

Scaling Considerations

Horizontal Scaling

┌─────────────────────────────────────────────────────────┐
│                    Load Balancer                         │
└─────────────────────────┬───────────────────────────────┘
                          │
    ┌─────────────────────┼─────────────────────┐
    │                     │                     │
┌───▼────┐          ┌────▼────┐          ┌────▼────┐
│ API-1  │          │  API-2  │          │  API-3  │
└───┬────┘          └────┬────┘          └────┬────┘
    │                    │                    │
    └────────────────────┼────────────────────┘
                         │
              ┌──────────▼──────────┐
              │   Redis Cluster     │
              │  (Shared State)     │
              └─────────────────────┘

Database Scaling

Read Replicas: For reporting and analytics queries
Connection Pooling: PgBouncer for connection management
Partitioning: Time-based partitioning for audit logs
Archival: Old scan data archived to cold storage

Worker Scaling

# HPA Configuration
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: zen-worker-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: zen-worker
  minReplicas: 3
  maxReplicas: 50
  metrics:
  - type: External
    external:
      metric:
        name: redis_queue_length
      target:
        type: AverageValue
        averageValue: "10"

Navigation Menu

Uh oh!

Zen-AI-Pentest Architecture Documentation

Table of Contents

System Overview

High-Level Architecture

Component Architecture

Core Components

1. ZenOrchestrator

2. ReAct Agent Framework

3. Analysis Bot

4. Guardrails System

Data Flow

Scan Execution Flow

Real-time Update Flow

Deployment Architecture

Docker Compose (Development)

Kubernetes (Production)

High Availability Architecture

Security Architecture

Defense in Depth

Secret Management

Technology Stack

Core Stack

AI/LLM Stack

Security Tools

Infrastructure

Scaling Considerations

Horizontal Scaling

Database Scaling

Worker Scaling

Related Documentation

Uh oh!

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Zen-AI-Pentest Architecture Documentation

Table of Contents

System Overview

High-Level Architecture

Component Architecture

Core Components

1. ZenOrchestrator

2. ReAct Agent Framework

3. Analysis Bot

4. Guardrails System

Data Flow

Scan Execution Flow

Real-time Update Flow

Deployment Architecture

Docker Compose (Development)

Kubernetes (Production)

High Availability Architecture

Security Architecture

Defense in Depth

Secret Management

Technology Stack

Core Stack

AI/LLM Stack

Security Tools

Infrastructure

Scaling Considerations

Horizontal Scaling

Database Scaling

Worker Scaling

Related Documentation