# krockodog/cyber-pentest-swarm-ai architecture

> Architecture diagram of the GitHub repository krockodog/cyber-pentest-swarm-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krockodog/cyber-pentest-swarm-ai
- Repository: https://github.com/krockodog/cyber-pentest-swarm-ai

## Overview

Cyber Pentest Swarm AI is an AI-assisted penetration-testing platform with CLI and web interfaces, a Go API, specialist agents, security tools, and report generation. Its principal documented scan workflow runs reconnaissance, vulnerability classification, exploitation, and reporting, with agents sharing findings through a PostgreSQL-backed blackboard. The README also documents bug-bounty scanning, OSINT, voice/TTS, and integrations. Several links below are documented by the README or source index; unsampled implementation details are not inferred.

Main entry points: [`swarm-agents/bughunter/engine.py`](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/engine.py) (Bug-bounty workflow), [`internal/swarm/coordinator.go`](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/swarm/coordinator.go) (Swarm coordinator), [`internal/api/server.go`](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/api/server.go) (REST API), [`internal/engine/runner.go`](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/engine/runner.go) (Scan engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[root.go]"]
  node_web["Web dashboard<br/>[page.tsx]"]
end

subgraph group_control["API and orchestration"]
  node_api["REST API<br/>[server.go]"]
  node_engine["Scan engine<br/>[runner.go]"]
  node_swarm["Swarm coordinator<br/>[coordinator.go]"]
  node_blackboard[("Finding blackboard<br/>[board.go]")]
  node_pythonbase["Python agent framework<br/>[agent_base.py]"]
end

subgraph group_assessment["Assessment workflow"]
  node_scope["Scope controls<br/>[validator.go]"]
  node_recon["Recon agents<br/>[main.py]"]
  node_classifier["Finding classifier<br/>[agent.go]"]
  node_exploit["Exploit agents<br/>[main.py]"]
  node_bughunter["Bug-bounty workflow<br/>[engine.py]"]
  node_tooling["Security tools<br/>[coordinator.go]"]
  node_bugscope["Bug-bounty scope<br/>[scope.py]"]
  node_bugrecon["Bug-bounty recon<br/>[recon.py]"]
  node_bugosint["Bug-bounty OSINT<br/>[osint.py]"]
  node_bugranker["Finding ranker<br/>[ranker.py]"]
  node_bugprobe["Target probe<br/>[probe.py]"]
  node_bugagent["Bug-bounty agent<br/>[agent.py]"]
  node_skillmap["Skill map<br/>[skill_map.py]"]
end

subgraph group_findings["Findings and reporting"]
  node_reports["Report generation<br/>[agent.go]"]
  node_reportformats["Report renderers<br/>[renderer.go]"]
  node_db[("Campaign storage<br/>[postgres.go]")]
  node_bugstate["Engagement state<br/>[state.py]"]
end

subgraph group_support["Platform capabilities"]
  node_llm["LLM providers<br/>[provider.go]"]
  node_voice["Voice and TTS<br/>[service.go]"]
  node_integrations["External integrations"]
end

node_analyst(("Analyst"))

node_analyst -->|"runs scans"| node_cli
node_analyst -->|"uses dashboard"| node_web
node_cli -.->|"starts scans"| node_engine
node_web -->|"REST requests"| node_api
node_cli -->|"starts server"| node_api
node_api -->|"invokes"| node_engine
node_engine -.->|"runs swarm"| node_swarm
node_swarm -->|"shares findings"| node_blackboard
node_engine -.->|"checks scope"| node_scope
node_swarm -->|"dispatches"| node_recon
node_swarm -->|"dispatches"| node_classifier
node_swarm -->|"dispatches"| node_exploit
node_swarm -->|"dispatches"| node_reports
node_recon -->|"findings flow"| node_classifier
node_classifier -->|"findings flow"| node_exploit
node_exploit -->|"results flow"| node_reports
node_swarm -.->|"uses tools"| node_tooling
node_reports -.->|"renders reports"| node_reportformats
node_api -->|"reads campaigns"| node_db
node_api -->|"reads findings"| node_reports
node_swarm -.->|"uses models"| node_llm
node_api -->|"serves voice routes"| node_voice
node_api -->|"uses integrations"| node_integrations
node_pythonbase -.->|"framework for"| node_bugagent
node_bughunter -->|"imports scope"| node_bugscope
node_bughunter -->|"imports recon"| node_bugrecon
node_bughunter -->|"imports OSINT"| node_bugosint
node_bughunter -->|"imports ranker"| node_bugranker
node_bughunter -->|"imports probe"| node_bugprobe
node_bughunter -->|"imports state"| node_bugstate
node_bughunter -->|"imports agent"| node_bugagent
node_bughunter -->|"imports skills"| node_skillmap

click node_cli "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/cli/root.go"
click node_web "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/web/src/app/page.tsx"
click node_api "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/api/server.go"
click node_engine "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/engine/runner.go"
click node_swarm "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/swarm/coordinator.go"
click node_blackboard "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/swarm/blackboard/board.go"
click node_scope "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/scope/validator.go"
click node_recon "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/recon/src/main.py"
click node_classifier "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/agent/classifier/agent.go"
click node_exploit "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/exploit/src/main.py"
click node_bughunter "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/engine.py"
click node_tooling "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/tools/coordinator.go"
click node_reports "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/agent/report/agent.go"
click node_reportformats "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/agent/report/renderer.go"
click node_db "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/db/postgres.go"
click node_llm "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/llm/provider.go"
click node_voice "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/voice/service.go"
click node_integrations "https://github.com/krockodog/cyber-pentest-swarm-ai/tree/main/internal/integrations"
click node_pythonbase "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bb/src/agent_base.py"
click node_bugscope "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/scope.py"
click node_bugrecon "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/recon.py"
click node_bugosint "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/osint.py"
click node_bugranker "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/ranker.py"
click node_bugprobe "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/probe.py"
click node_bugstate "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/state.py"
click node_bugagent "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/agent.py"
click node_skillmap "https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/skill_map.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_web toneBlue
class node_api,node_engine,node_swarm,node_blackboard,node_pythonbase toneAmber
class node_scope,node_recon,node_classifier,node_exploit,node_bughunter,node_tooling,node_bugscope,node_bugrecon,node_bugosint,node_bugranker,node_bugprobe,node_bugagent,node_skillmap toneMint
class node_reports,node_reportformats,node_db,node_bugstate toneRose
class node_llm,node_voice,node_integrations,node_analyst toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/cli/root.go): `cli/root.go`
- [Web dashboard](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`

### API and orchestration

- [REST API](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/api/server.go): `internal/api/server.go`
- [Scan engine](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/engine/runner.go): `internal/engine/runner.go`
- [Swarm coordinator](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/swarm/coordinator.go): `internal/swarm/coordinator.go`
- [Finding blackboard](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/swarm/blackboard/board.go): `internal/swarm/blackboard/board.go`
- [Python agent framework](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bb/src/agent_base.py): `swarm-agents/bb/src/agent_base.py`

### Assessment workflow

- [Scope controls](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/scope/validator.go): `internal/scope/validator.go`
- [Recon agents](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/recon/src/main.py): `swarm-agents/recon/src/main.py`
- [Finding classifier](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/agent/classifier/agent.go): `internal/agent/classifier/agent.go`
- [Exploit agents](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/exploit/src/main.py): `swarm-agents/exploit/src/main.py`
- [Bug-bounty workflow](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/engine.py): `swarm-agents/bughunter/engine.py`
- [Security tools](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/tools/coordinator.go): `internal/tools/coordinator.go`
- [Bug-bounty scope](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/scope.py): `swarm-agents/bughunter/scope.py`
- [Bug-bounty recon](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/recon.py): `swarm-agents/bughunter/recon.py`
- [Bug-bounty OSINT](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/osint.py): `swarm-agents/bughunter/osint.py`
- [Finding ranker](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/ranker.py): `swarm-agents/bughunter/ranker.py`
- [Target probe](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/probe.py): `swarm-agents/bughunter/probe.py`
- [Bug-bounty agent](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/agent.py): `swarm-agents/bughunter/agent.py`
- [Skill map](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/skill_map.py): `swarm-agents/bughunter/skill_map.py`

### Findings and reporting

- [Report generation](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/agent/report/agent.go): `internal/agent/report/agent.go`
- [Report renderers](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/agent/report/renderer.go): `internal/agent/report/renderer.go`
- [Campaign storage](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/db/postgres.go): `internal/db/postgres.go`
- [Engagement state](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/swarm-agents/bughunter/state.py): `swarm-agents/bughunter/state.py`

### Platform capabilities

- [LLM providers](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/llm/provider.go): `internal/llm/provider.go`
- [Voice and TTS](https://github.com/krockodog/cyber-pentest-swarm-ai/blob/main/internal/voice/service.go): `internal/voice/service.go`
- [External integrations](https://github.com/krockodog/cyber-pentest-swarm-ai/tree/main/internal/integrations): `internal/integrations`

### Other components

- **Analyst**

## Connections

- Analyst → CLI: runs scans
- Analyst → Web dashboard: uses dashboard
- CLI → Scan engine: starts scans
- Web dashboard → REST API: REST requests
- CLI → REST API: starts server
- REST API → Scan engine: invokes (evidence: `internal/api/server.go`)
- Scan engine → Swarm coordinator: runs swarm
- Swarm coordinator → Finding blackboard: shares findings
- Scan engine → Scope controls: checks scope
- Swarm coordinator → Recon agents: dispatches
- Swarm coordinator → Finding classifier: dispatches
- Swarm coordinator → Exploit agents: dispatches
- Swarm coordinator → Report generation: dispatches
- Recon agents → Finding classifier: findings flow
- Finding classifier → Exploit agents: findings flow
- Exploit agents → Report generation: results flow
- Swarm coordinator → Security tools: uses tools
- Report generation → Report renderers: renders reports
- REST API → Campaign storage: reads campaigns (evidence: `internal/api/server.go`)
- REST API → Report generation: reads findings (evidence: `internal/api/server.go`)
- Swarm coordinator → LLM providers: uses models
- REST API → Voice and TTS: serves voice routes (evidence: `internal/api/server.go`)
- REST API → External integrations: uses integrations (evidence: `internal/api/server.go`)
- Python agent framework → Bug-bounty agent: framework for
- Bug-bounty workflow → Bug-bounty scope: imports scope (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Bug-bounty recon: imports recon (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Bug-bounty OSINT: imports OSINT (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Finding ranker: imports ranker (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Target probe: imports probe (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Engagement state: imports state (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Bug-bounty agent: imports agent (evidence: `swarm-agents/bughunter/engine.py`)
- Bug-bounty workflow → Skill map: imports skills (evidence: `swarm-agents/bughunter/engine.py`)
