Architecture Overview¶

PenLocal-AI uses a microservices architecture with strict network isolation to safely run autonomous security testing agents.

System Architecture¶

flowchart TB
    subgraph Host["Host Machine (127.0.0.1)"]
        Browser["Browser"]
    end

    subgraph PublicNet["public-services Network"]
        n8nProxy["n8n Proxy<br/>:443"]
        WebappProxy["Webapp Proxy<br/>:8000"]
        MinioProxy["MinIO API Proxy"]
    end

    subgraph InternalNet["internal-services (10.150.0.0/16)"]
        n8n["n8n Workflow Engine"]
        Webapp["Pentest Manager"]
        Postgres[(PostgreSQL)]
        Qdrant[(Qdrant Vector DB)]
        Ollama["Ollama LLM"]
        Vault["Credential Vault"]
        MinioAPI["MinIO API"]
        Minio[(MinIO Storage)]
    end

    subgraph KaliNet["kali-network (10.151.0.0/16)"]
        Kali["Kali Linux Agent"]
    end

    Browser --> n8nProxy
    Browser --> WebappProxy

    n8nProxy --> n8n
    WebappProxy --> Webapp

    n8n --> Postgres
    n8n --> Qdrant
    n8n --> Ollama
    n8n --> Vault
    n8n --> MinioAPI
    n8n -.->|SSH| Kali

    Webapp --> Postgres

    MinioAPI --> Minio
    MinioProxy --> MinioAPI

Network Segmentation¶

Three-Tier Network Model¶

Network	Subnet	Purpose	Internet Access
`public-services`	Dynamic	Exposed proxies	Yes
`internal-services`	`10.150.0.0/16`	Backend services	Yes
`kali-network`	`10.151.0.0/16`	Isolated Kali agent	Yes (outbound)

Isolation Mechanics¶

n8n Dual-Homing¶

n8n connects to both internal-services and kali-network:

n8n:
  networks:
    internal-services:
      ipv4_address: 10.150.0.250  # Listens here only
    kali-network:                  # SSH outbound only

Web UI: Only accessible via 10.150.0.250:5678
Kali Access: n8n can SSH to Kali, but Kali cannot reach n8n's web interface

Kali Containment¶

graph LR
    subgraph KaliNet["kali-network"]
        Kali["Kali Linux"]
    end

    subgraph InternalNet["internal-services"]
        Postgres[(PostgreSQL)]
        Vault["Credential Vault"]
        n8n["n8n"]
    end

    Kali -.->|BLOCKED| Postgres
    Kali -.->|BLOCKED| Vault
    Kali -.->|BLOCKED| n8n
    Kali -->|Allowed| Internet((Internet))

Kali Linux: - Cannot reach PostgreSQL, Qdrant, Vault, or other internal services - Cannot access n8n web interface (different network) - Can access the internet for tools (apt, git, etc.) - Can attack targets on public-services network

Component Overview¶

Core Services¶

Service	Image	Purpose
`n8n`	Custom (patched)	Workflow orchestration
`pentest-webapp`	Custom Flask	Management UI & API
`postgres`	`postgres:16-alpine`	Primary database
`qdrant`	`qdrant/qdrant`	Vector embeddings
`ollama`	`ollama/ollama`	Local LLM inference

Storage Services¶

Service	Image	Purpose
`minio`	`minio/minio`	S3-compatible object storage
`minio-api`	Custom FastAPI	Secure file operations
`credential-vault`	Custom	Encrypted secret storage

Proxy Services¶

Proxy	Backend	Port	Auth
`n8n-proxy`	n8n:5678	443	Session
`webapp-proxy`	webapp:8000	8000	Session + MFA
`ollama-proxy`	ollama:11434	11434	Bearer token
`minio-api-proxy`	minio-api:8080	-	API keys

Security Services¶

Service	Purpose
`credential-vault`	Encrypted credential storage
`ssl-cert-generator`	Self-signed certificate generation
`ssh-key-generator`	SSH keypair for Kali access
`credential-initializer`	Initial secret injection

Data Flow¶

Pentest Execution Flow¶

sequenceDiagram
    participant User
    participant Webapp
    participant n8n
    participant Ollama
    participant Qdrant
    participant Kali
    participant Target

    User->>Webapp: Start Pentest
    Webapp->>n8n: Trigger Workflow
    n8n->>Ollama: Analyze Target
    Ollama->>Qdrant: Retrieve Knowledge
    Qdrant-->>Ollama: Relevant Context
    Ollama-->>n8n: Attack Plan
    n8n->>Kali: Execute Commands (SSH)
    Kali->>Target: Run Exploits
    Target-->>Kali: Results
    Kali-->>n8n: Command Output
    n8n->>Webapp: Update Status
    n8n->>Ollama: Analyze Findings
    Ollama-->>n8n: Vulnerability Report
    n8n->>Webapp: Store Vulnerabilities
    Webapp-->>User: Display Results

Authentication Flow¶

sequenceDiagram
    participant User
    participant Webapp
    participant Database

    User->>Webapp: Login (username/password)
    Webapp->>Database: Validate Credentials
    Database-->>Webapp: User Record

    alt MFA Enabled
        Webapp-->>User: Request TOTP
        User->>Webapp: Enter TOTP Code
        Webapp->>Webapp: Verify TOTP
    end

    Webapp->>Webapp: Create Session
    Webapp-->>User: Redirect to Dashboard

Database Schema¶

PostgreSQL Databases¶

Database	Purpose
`n8n_db`	n8n workflows, credentials, executions
`pentest_db`	Pentests, users, vulnerabilities

Key Tables (pentest_db)¶

erDiagram
    users ||--o{ pentests : owns
    users ||--o{ ollama_connections : has
    pentests ||--o{ vulnerabilities : contains
    pentests ||--o{ retests : has
    teams ||--o{ team_members : contains

    users {
        string username PK
        string password
        boolean is_admin
        string mfa_secret
        string api_key
    }

    pentests {
        uuid id PK
        string target
        string status
        jsonb credentials
        jsonb commands
        jsonb report
    }

    vulnerabilities {
        int id PK
        uuid pentest_id FK
        string title
        string severity
        float cvss_score
    }

Encryption Architecture¶

Data at Rest¶

Data	Encryption	Key Source
API Keys	Fernet (AES-128)	`VAULT_MASTER_KEY`
Credentials	Fernet (AES-128)	`VAULT_MASTER_KEY`
Passwords	PBKDF2	Per-user salt

Data in Transit¶

Connection	Protocol	Certificate
Browser ↔ Proxies	TLS 1.2/1.3	Self-signed
Service ↔ Service	TLS 1.2/1.3	Self-signed
n8n ↔ Kali	SSH	Ed25519 keypair

Scaling Considerations¶

Queue Management¶

PenLocal uses a FIFO queue per Ollama connection:

┌─────────────────────────────────────────┐
│ Ollama Connection: "Local GPU"          │
├─────────────────────────────────────────┤
│ Running: Pentest A, Pentest B           │
│ Queued:  Pentest C → Pentest D → ...    │
│ Max Concurrent: 2 (configurable)        │
└─────────────────────────────────────────┘

Task types tracked: - Pentests - Report generation - Retests - Vulnerability imports

Resource Limits¶

Configure in Admin → Settings:

Setting	Default	Description
Max concurrent per Ollama	2	Parallel task limit
Max upload size	50 MB	File upload limit
Allow private IPs	No	SSRF protection