# exael74/diagramspentestai architecture

> Architecture diagram of the GitHub repository exael74/diagramspentestai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exael74/diagramspentestai
- Repository: https://github.com/exael74/diagramspentestai

## Overview

PentestAI is a research prototype for authorized, scope-bounded penetration testing. The operator configures an engagement in the terminal interface; the Technical Agent proposes actions across reconnaissance, scanning, web analysis, and exploitation. The deterministic policy gate and human checkpoints govern execution through tool adapters. The Validation Agent filters untrusted output into evidence, which feeds later decisions and the Reporting Agent. The README documents these principal relationships; sampled orchestrator code confirms adapter dispatch, while unsampled orchestration details are represented only where the README supports them.

Main entry points: [`src/pentestai/orchestration/orchestrator.py`](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/orchestrator.py) (Orchestrator), [`src/pentestai/adapters/base.py`](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/base.py) (Adapter Boundary), [`src/pentestai/agents/technical.py`](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/technical.py) (Technical Agent), [`src/pentestai/interface/cli.py`](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Operator Interface"]
  node_cli["CLI<br/>[cli.py]"]
  node_wizard["Setup Wizard<br/>[wizard.py]"]
  node_approval["Human Approval<br/>[approval.py]"]
  node_theme["Terminal Theme<br/>[theme.py]"]
end

subgraph group_coordination["Assessment Coordination"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
  node_action["Proposed Action<br/>[action.py]"]
  node_policy["Policy Engine<br/>[policy.py]"]
  node_scope["Engagement Scope<br/>[scope.py]"]
  node_control["Control Decisions<br/>[control.py]"]
end

subgraph group_agents["Agent Layer"]
  node_technical["Technical Agent<br/>[technical.py]"]
  node_validation["Validation Agent<br/>[validation.py]"]
  node_reporting["Reporting Agent<br/>[reporting.py]"]
  node_guardrails["Agent Guardrails<br/>[guardrails.py]"]
  node_llm["LLM Client<br/>[llm.py]"]
  node_providers["LLM Providers<br/>[providers.py]"]
end

subgraph group_execution["Tools and Evidence"]
  node_adapterbase["Adapter Boundary<br/>[base.py]"]
  node_nmap["Nmap Adapter<br/>[nmap_adapter.py]"]
  node_nuclei["Nuclei Adapter<br/>[nuclei_adapter.py]"]
  node_zap["ZAP Adapter<br/>[zap_adapter.py]"]
  node_sqlmap["sqlmap Adapter<br/>[sqlmap_adapter.py]"]
  node_evidence["Evidence Model<br/>[model.py]"]
  node_repository[("Evidence and Audit<br/>[repository.py]")]
  node_lab["Vulnerable Lab<br/>[app.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts assessment"| node_cli
node_cli -->|"launches setup"| node_wizard
node_operator -->|"configures engagement"| node_wizard
node_operator -->|"reviews actions"| node_approval
node_cli -->|"starts run"| node_orchestrator
node_wizard -->|"configures scope"| node_scope
node_wizard -->|"configures policy"| node_policy
node_orchestrator -->|"requests proposals"| node_technical
node_technical -->|"requests decisions"| node_llm
node_validation -->|"requests analysis"| node_llm
node_reporting -->|"requests report"| node_llm
node_llm -->|"delegates calls"| node_providers
node_technical -->|"proposes action"| node_action
node_orchestrator -->|"evaluates action"| node_policy
node_policy -->|"checks authorization"| node_scope
node_orchestrator -->|"requests approval"| node_approval
node_approval -->|"returns choice"| node_control
node_orchestrator -->|"applies controls"| node_control
node_orchestrator -->|"dispatches action"| node_adapterbase
node_adapterbase -->|"executes tool"| node_nmap
node_adapterbase -->|"executes tool"| node_nuclei
node_adapterbase -->|"executes tool"| node_zap
node_adapterbase -->|"executes tool"| node_sqlmap
node_validation -->|"creates records"| node_evidence
node_orchestrator -->|"filters tool output"| node_validation
node_orchestrator -->|"stores validated records"| node_repository
node_orchestrator -->|"records audit events"| node_repository
node_orchestrator -->|"feeds evidence back"| node_technical
node_orchestrator -->|"requests final report"| node_reporting
node_reporting -->|"reads validated evidence"| node_repository
node_orchestrator -->|"assesses controlled target"| node_lab
node_technical -->|"uses constrained outputs"| node_guardrails
node_validation -->|"uses constrained outputs"| node_guardrails
node_cli -->|"renders interface"| node_theme

click node_cli "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/cli.py"
click node_wizard "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/wizard.py"
click node_approval "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/approval.py"
click node_theme "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/theme.py"
click node_orchestrator "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/orchestrator.py"
click node_action "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/action.py"
click node_policy "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/policy.py"
click node_scope "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/scope.py"
click node_control "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/control.py"
click node_technical "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/technical.py"
click node_validation "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/validation.py"
click node_reporting "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/reporting.py"
click node_guardrails "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/guardrails.py"
click node_llm "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/llm.py"
click node_providers "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/providers.py"
click node_adapterbase "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/base.py"
click node_nmap "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/nmap_adapter.py"
click node_nuclei "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/nuclei_adapter.py"
click node_zap "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/zap_adapter.py"
click node_sqlmap "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/sqlmap_adapter.py"
click node_evidence "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/evidence/model.py"
click node_repository "https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/evidence/repository.py"
click node_lab "https://github.com/exael74/diagramspentestai/blob/main/lab/vulnmart/app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_wizard,node_approval,node_theme toneBlue
class node_orchestrator,node_action,node_policy,node_scope,node_control toneAmber
class node_technical,node_validation,node_reporting,node_guardrails,node_llm,node_providers toneMint
class node_adapterbase,node_nmap,node_nuclei,node_zap,node_sqlmap,node_evidence,node_repository,node_lab toneRose
class node_operator toneIndigo
```

## Components

### Operator Interface

- [CLI](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/cli.py): `src/pentestai/interface/cli.py`
- [Setup Wizard](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/wizard.py): `src/pentestai/interface/wizard.py`
- [Human Approval](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/approval.py): `src/pentestai/interface/approval.py`
- [Terminal Theme](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/interface/theme.py): `src/pentestai/interface/theme.py`

### Assessment Coordination

- [Orchestrator](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/orchestrator.py): `src/pentestai/orchestration/orchestrator.py`
- [Proposed Action](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/action.py): `src/pentestai/orchestration/action.py`
- [Policy Engine](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/policy.py): `src/pentestai/orchestration/policy.py`
- [Engagement Scope](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/scope.py): `src/pentestai/orchestration/scope.py`
- [Control Decisions](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/orchestration/control.py): `src/pentestai/orchestration/control.py`

### Agent Layer

- [Technical Agent](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/technical.py): `src/pentestai/agents/technical.py`
- [Validation Agent](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/validation.py): `src/pentestai/agents/validation.py`
- [Reporting Agent](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/reporting.py): `src/pentestai/agents/reporting.py`
- [Agent Guardrails](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/guardrails.py): `src/pentestai/agents/guardrails.py`
- [LLM Client](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/llm.py): `src/pentestai/agents/llm.py`
- [LLM Providers](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/agents/providers.py): `src/pentestai/agents/providers.py`

### Tools and Evidence

- [Adapter Boundary](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/base.py): `src/pentestai/adapters/base.py`
- [Nmap Adapter](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/nmap_adapter.py): `src/pentestai/adapters/nmap_adapter.py`
- [Nuclei Adapter](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/nuclei_adapter.py): `src/pentestai/adapters/nuclei_adapter.py`
- [ZAP Adapter](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/zap_adapter.py): `src/pentestai/adapters/zap_adapter.py`
- [sqlmap Adapter](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/adapters/sqlmap_adapter.py): `src/pentestai/adapters/sqlmap_adapter.py`
- [Evidence Model](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/evidence/model.py): `src/pentestai/evidence/model.py`
- [Evidence and Audit](https://github.com/exael74/diagramspentestai/blob/main/src/pentestai/evidence/repository.py): `src/pentestai/evidence/repository.py`
- [Vulnerable Lab](https://github.com/exael74/diagramspentestai/blob/main/lab/vulnmart/app.py): `lab/vulnmart/app.py`

### Other components

- **Operator**

## Connections

- Operator → CLI: starts assessment (evidence: `README.md`)
- CLI → Setup Wizard: launches setup (evidence: `src/pentestai/interface/cli.py`)
- Operator → Setup Wizard: configures engagement (evidence: `README.md`)
- Operator → Human Approval: reviews actions (evidence: `README.md`)
- CLI → Orchestrator: starts run (evidence: `src/pentestai/interface/cli.py`)
- Setup Wizard → Engagement Scope: configures scope (evidence: `README.md`)
- Setup Wizard → Policy Engine: configures policy (evidence: `README.md`)
- Orchestrator → Technical Agent: requests proposals (evidence: `README.md`)
- Technical Agent → LLM Client: requests decisions (evidence: `src/pentestai/agents/technical.py`)
- Validation Agent → LLM Client: requests analysis (evidence: `src/pentestai/agents/validation.py`)
- Reporting Agent → LLM Client: requests report (evidence: `src/pentestai/agents/reporting.py`)
- LLM Client → LLM Providers: delegates calls (evidence: `src/pentestai/agents/llm.py`)
- Technical Agent → Proposed Action: proposes action (evidence: `README.md`)
- Orchestrator → Policy Engine: evaluates action (evidence: `README.md`)
- Policy Engine → Engagement Scope: checks authorization (evidence: `src/pentestai/orchestration/policy.py`)
- Orchestrator → Human Approval: requests approval (evidence: `README.md`)
- Human Approval → Control Decisions: returns choice (evidence: `src/pentestai/interface/approval.py`)
- Orchestrator → Control Decisions: applies controls (evidence: `README.md`)
- Orchestrator → Adapter Boundary: dispatches action (evidence: `src/pentestai/orchestration/orchestrator.py`)
- Adapter Boundary → Nmap Adapter: executes tool (evidence: `src/pentestai/adapters/__init__.py`)
- Adapter Boundary → Nuclei Adapter: executes tool (evidence: `src/pentestai/adapters/__init__.py`)
- Adapter Boundary → ZAP Adapter: executes tool (evidence: `src/pentestai/adapters/__init__.py`)
- Adapter Boundary → sqlmap Adapter: executes tool (evidence: `src/pentestai/adapters/__init__.py`)
- Validation Agent → Evidence Model: creates records (evidence: `src/pentestai/agents/validation.py`)
- Orchestrator → Validation Agent: filters tool output (evidence: `README.md`)
- Orchestrator → Evidence and Audit: stores validated records (evidence: `src/pentestai/orchestration/orchestrator.py`)
- Orchestrator → Evidence and Audit: records audit events (evidence: `src/pentestai/evidence/repository.py`)
- Orchestrator → Technical Agent: feeds evidence back (evidence: `README.md`)
- Orchestrator → Reporting Agent: requests final report (evidence: `README.md`)
- Reporting Agent → Evidence and Audit: reads validated evidence (evidence: `README.md`)
- Orchestrator → Vulnerable Lab: assesses controlled target (evidence: `README.md`)
- Technical Agent → Agent Guardrails: uses constrained outputs (evidence: `src/pentestai/agents/technical.py`)
- Validation Agent → Agent Guardrails: uses constrained outputs (evidence: `src/pentestai/agents/validation.py`)
- CLI → Terminal Theme: renders interface (evidence: `src/pentestai/interface/cli.py`)
