# khenryaegis/vulnbot architecture

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

- Interactive diagram: https://gitdiagram.com/khenryaegis/vulnbot
- Repository: https://github.com/khenryaegis/vulnbot

## Overview

VulnBot is an LLM-driven penetration-testing framework with a multi-agent assessment workflow and a separately exposed knowledge-base/chat capability. The documented user flow starts a VulnBot run; its role layer plans and executes assessment work, including remote shell operations, while chat and knowledge-base interfaces support retrieval and administration. The graph preserves the major documented RAG and agent subsystems. Some implementation files were not sampled, so uncertain links are omitted; cited source-index references and README statements support the relationships shown.

Main entry points: [`roles/role.py`](https://github.com/khenryaegis/vulnbot/blob/main/roles/role.py) (Role orchestrator), [`rag/kb/service/milvus_kb_service.py`](https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/service/milvus_kb_service.py) (Milvus KB service), [`server/chat/chat.py`](https://github.com/khenryaegis/vulnbot/blob/main/server/chat/chat.py) (Chat service), [`actions/planner.py`](https://github.com/khenryaegis/vulnbot/blob/main/actions/planner.py) (Assessment planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_chat["Chat service<br/>[chat.py]"]
  node_kb_routes["KB API routes<br/>[kb_route.py]"]
  node_kb_ui["Knowledge UI<br/>[knowledge_base.py]"]
end

subgraph group_assessment["Pentest Agents"]
  node_role["Role orchestrator<br/>[role.py]"]
  node_collector["Collector agent<br/>[collector.py]"]
  node_scanner["Scanner agent<br/>[scanner.py]"]
  node_exploiter["Exploiter agent<br/>[exploiter.py]"]
  node_planner["Assessment planner<br/>[planner.py]"]
  node_plan_writer["Plan updates<br/>[write_plan.py]"]
  node_plan_summary["Plan summary<br/>[plan_summary.py]"]
  node_code_writer["Command generation<br/>[write_code.py]"]
  node_task_executor["Task execution<br/>[execute_task.py]"]
  node_shell["Remote shell<br/>[remote_shell.py]"]
  node_prompts["Agent prompts<br/>[prompt.py]"]
end

subgraph group_rag["Knowledge Retrieval"]
  node_kb_docs["Document API<br/>[kb_doc_api.py]"]
  node_kb_base["KB service layer<br/>[base.py]"]
  node_milvus_service["Milvus KB service"]
  node_kb_utils["Load and split files<br/>[kb_utils.py]"]
  node_embedding["Embedding provider<br/>[embedding.py]"]
  node_vector_retriever["Vector retriever"]
  node_reranker["Document reranker<br/>[reranker.py]"]
end

subgraph group_state["State and Configuration"]
  node_mysql[("MySQL database")]
  node_session["DB session layer<br/>[session.py]"]
  node_message_repo["Message repository"]
  node_plan_repo["Plan repository<br/>[plan_repository.py]"]
  node_plan_model["Plan model<br/>[plan_model.py]"]
  node_task_model["Task model<br/>[task_model.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_operator(("Operator"))
node_llm["LLM provider"]
node_target(("Assessment target"))
node_milvus[("Milvus vector store")]

node_operator -->|"starts run"| node_cli
node_operator -.->|"submits query"| node_chat
node_operator -.->|"manages knowledge"| node_kb_ui
node_cli -.->|"runs assessment"| node_role
node_role -->|"plans tasks"| node_planner
node_role -->|"summarizes plan"| node_plan_summary
node_role -->|"requests commands"| node_code_writer
node_role -->|"loads and saves plans"| node_plan_repo
node_role -->|"uses prompts"| node_prompts
node_planner -->|"writes plan"| node_plan_writer
node_planner -->|"uses prompts"| node_prompts
node_planner -->|"creates tasks"| node_task_model
node_code_writer -->|"dispatches code"| node_task_executor
node_code_writer -->|"uses prompts"| node_prompts
node_task_executor -.->|"executes assessment"| node_target
node_shell -.->|"connects remotely"| node_target
node_chat -->|"requests completion"| node_llm
node_chat -->|"searches documents"| node_kb_docs
node_chat -->|"uses reranker"| node_reranker
node_chat -->|"loads and saves messages"| node_message_repo
node_kb_routes -->|"routes requests"| node_kb_docs
node_kb_ui -->|"uses KB service"| node_kb_base
node_kb_docs -->|"manages documents"| node_kb_base
node_kb_docs -->|"uses file utilities"| node_kb_utils
node_kb_base -->|"delegates vector work"| node_milvus_service
node_milvus_service -->|"creates embeddings"| node_embedding
node_milvus_service -->|"searches vectors"| node_vector_retriever
node_milvus_service -->|"reads and writes vectors"| node_milvus
node_milvus_service -->|"uses file metadata"| node_kb_utils
node_message_repo -->|"opens DB session"| node_session
node_session -->|"commits transactions"| node_mysql
node_plan_repo -->|"loads and stores plans"| node_plan_model
node_plan_model -->|"contains tasks"| node_task_model
node_plan_repo -->|"uses DB session"| node_session
node_config -->|"configures database"| node_session
node_config -->|"configures vector store"| node_milvus_service

click node_cli "https://github.com/khenryaegis/vulnbot/blob/main/cli.py"
click node_chat "https://github.com/khenryaegis/vulnbot/blob/main/server/chat/chat.py"
click node_kb_routes "https://github.com/khenryaegis/vulnbot/blob/main/server/api/kb_route.py"
click node_kb_ui "https://github.com/khenryaegis/vulnbot/blob/main/web/knowledge_base/knowledge_base.py"
click node_role "https://github.com/khenryaegis/vulnbot/blob/main/roles/role.py"
click node_collector "https://github.com/khenryaegis/vulnbot/blob/main/roles/collector.py"
click node_scanner "https://github.com/khenryaegis/vulnbot/blob/main/roles/scanner.py"
click node_exploiter "https://github.com/khenryaegis/vulnbot/blob/main/roles/exploiter.py"
click node_planner "https://github.com/khenryaegis/vulnbot/blob/main/actions/planner.py"
click node_plan_writer "https://github.com/khenryaegis/vulnbot/blob/main/actions/write_plan.py"
click node_plan_summary "https://github.com/khenryaegis/vulnbot/blob/main/actions/plan_summary.py"
click node_code_writer "https://github.com/khenryaegis/vulnbot/blob/main/actions/write_code.py"
click node_task_executor "https://github.com/khenryaegis/vulnbot/blob/main/actions/execute_task.py"
click node_shell "https://github.com/khenryaegis/vulnbot/blob/main/actions/remote_shell.py"
click node_prompts "https://github.com/khenryaegis/vulnbot/blob/main/prompts/prompt.py"
click node_kb_docs "https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/api/kb_doc_api.py"
click node_kb_base "https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/base.py"
click node_milvus_service "https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/service/milvus_kb_service.py"
click node_kb_utils "https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/utils/kb_utils.py"
click node_embedding "https://github.com/khenryaegis/vulnbot/blob/main/rag/embedding/embedding.py"
click node_vector_retriever "https://github.com/khenryaegis/vulnbot/blob/main/rag/retriever/milvus_vectorstore.py"
click node_reranker "https://github.com/khenryaegis/vulnbot/blob/main/rag/reranker/reranker.py"
click node_session "https://github.com/khenryaegis/vulnbot/blob/main/utils/session.py"
click node_message_repo "https://github.com/khenryaegis/vulnbot/blob/main/db/repository/message_repository.py"
click node_plan_repo "https://github.com/khenryaegis/vulnbot/blob/main/db/repository/plan_repository.py"
click node_plan_model "https://github.com/khenryaegis/vulnbot/blob/main/db/models/plan_model.py"
click node_task_model "https://github.com/khenryaegis/vulnbot/blob/main/db/models/task_model.py"
click node_config "https://github.com/khenryaegis/vulnbot/blob/main/config/config.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_chat,node_kb_routes,node_kb_ui toneBlue
class node_role,node_collector,node_scanner,node_exploiter,node_planner,node_plan_writer,node_plan_summary,node_code_writer,node_task_executor,node_shell,node_prompts,node_milvus toneAmber
class node_kb_docs,node_kb_base,node_milvus_service,node_kb_utils,node_embedding,node_vector_retriever,node_reranker toneMint
class node_mysql,node_session,node_message_repo,node_plan_repo,node_plan_model,node_task_model,node_config toneRose
class node_operator,node_llm,node_target toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/khenryaegis/vulnbot/blob/main/cli.py): `cli.py`
- [Chat service](https://github.com/khenryaegis/vulnbot/blob/main/server/chat/chat.py): `server/chat/chat.py`
- [KB API routes](https://github.com/khenryaegis/vulnbot/blob/main/server/api/kb_route.py): `server/api/kb_route.py`
- [Knowledge UI](https://github.com/khenryaegis/vulnbot/blob/main/web/knowledge_base/knowledge_base.py): `web/knowledge_base/knowledge_base.py`

### Pentest Agents

- [Role orchestrator](https://github.com/khenryaegis/vulnbot/blob/main/roles/role.py): `roles/role.py`
- [Collector agent](https://github.com/khenryaegis/vulnbot/blob/main/roles/collector.py): `roles/collector.py`
- [Scanner agent](https://github.com/khenryaegis/vulnbot/blob/main/roles/scanner.py): `roles/scanner.py`
- [Exploiter agent](https://github.com/khenryaegis/vulnbot/blob/main/roles/exploiter.py): `roles/exploiter.py`
- [Assessment planner](https://github.com/khenryaegis/vulnbot/blob/main/actions/planner.py): `actions/planner.py`
- [Plan updates](https://github.com/khenryaegis/vulnbot/blob/main/actions/write_plan.py): `actions/write_plan.py`
- [Plan summary](https://github.com/khenryaegis/vulnbot/blob/main/actions/plan_summary.py): `actions/plan_summary.py`
- [Command generation](https://github.com/khenryaegis/vulnbot/blob/main/actions/write_code.py): `actions/write_code.py`
- [Task execution](https://github.com/khenryaegis/vulnbot/blob/main/actions/execute_task.py): `actions/execute_task.py`
- [Remote shell](https://github.com/khenryaegis/vulnbot/blob/main/actions/remote_shell.py): `actions/remote_shell.py`
- [Agent prompts](https://github.com/khenryaegis/vulnbot/blob/main/prompts/prompt.py): `prompts/prompt.py`

### Knowledge Retrieval

- [Document API](https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/api/kb_doc_api.py): `rag/kb/api/kb_doc_api.py`
- [KB service layer](https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/base.py): `rag/kb/base.py`
- [Milvus KB service](https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/service/milvus_kb_service.py): `rag/kb/service/milvus_kb_service.py`
- [Load and split files](https://github.com/khenryaegis/vulnbot/blob/main/rag/kb/utils/kb_utils.py): `rag/kb/utils/kb_utils.py`
- [Embedding provider](https://github.com/khenryaegis/vulnbot/blob/main/rag/embedding/embedding.py): `rag/embedding/embedding.py`
- [Vector retriever](https://github.com/khenryaegis/vulnbot/blob/main/rag/retriever/milvus_vectorstore.py): `rag/retriever/milvus_vectorstore.py`
- [Document reranker](https://github.com/khenryaegis/vulnbot/blob/main/rag/reranker/reranker.py): `rag/reranker/reranker.py`

### State and Configuration

- **MySQL database**
- [DB session layer](https://github.com/khenryaegis/vulnbot/blob/main/utils/session.py): `utils/session.py`
- [Message repository](https://github.com/khenryaegis/vulnbot/blob/main/db/repository/message_repository.py): `db/repository/message_repository.py`
- [Plan repository](https://github.com/khenryaegis/vulnbot/blob/main/db/repository/plan_repository.py): `db/repository/plan_repository.py`
- [Plan model](https://github.com/khenryaegis/vulnbot/blob/main/db/models/plan_model.py): `db/models/plan_model.py`
- [Task model](https://github.com/khenryaegis/vulnbot/blob/main/db/models/task_model.py): `db/models/task_model.py`
- [Runtime configuration](https://github.com/khenryaegis/vulnbot/blob/main/config/config.py): `config/config.py`

### Other components

- **Operator**
- **LLM provider**
- **Assessment target**
- **Milvus vector store**

## Connections

- Operator → CLI: starts run
- Operator → Chat service: submits query
- Operator → Knowledge UI: manages knowledge
- CLI → Role orchestrator: runs assessment
- Role orchestrator → Assessment planner: plans tasks (evidence: `roles/role.py`)
- Role orchestrator → Plan summary: summarizes plan (evidence: `roles/role.py`)
- Role orchestrator → Command generation: requests commands (evidence: `roles/role.py`)
- Role orchestrator → Plan repository: loads and saves plans (evidence: `roles/role.py`)
- Role orchestrator → Agent prompts: uses prompts (evidence: `roles/role.py`)
- Assessment planner → Plan updates: writes plan (evidence: `actions/planner.py`)
- Assessment planner → Agent prompts: uses prompts (evidence: `actions/planner.py`)
- Assessment planner → Task model: creates tasks (evidence: `actions/planner.py`)
- Command generation → Task execution: dispatches code (evidence: `actions/write_code.py`)
- Command generation → Agent prompts: uses prompts (evidence: `actions/write_code.py`)
- Task execution → Assessment target: executes assessment
- Remote shell → Assessment target: connects remotely
- Chat service → LLM provider: requests completion (evidence: `server/chat/chat.py`)
- Chat service → Document API: searches documents (evidence: `server/chat/chat.py`)
- Chat service → Document reranker: uses reranker (evidence: `server/chat/chat.py`)
- Chat service → Message repository: loads and saves messages (evidence: `server/chat/chat.py`)
- KB API routes → Document API: routes requests (evidence: `server/api/kb_route.py`)
- Knowledge UI → KB service layer: uses KB service (evidence: `web/knowledge_base/knowledge_base.py`)
- Document API → KB service layer: manages documents (evidence: `rag/kb/api/kb_doc_api.py`)
- Document API → Load and split files: uses file utilities (evidence: `rag/kb/api/kb_doc_api.py`)
- KB service layer → Milvus KB service: delegates vector work (evidence: `rag/kb/base.py`)
- Milvus KB service → Embedding provider: creates embeddings (evidence: `rag/kb/service/milvus_kb_service.py`)
- Milvus KB service → Vector retriever: searches vectors (evidence: `rag/kb/service/milvus_kb_service.py`)
- Milvus KB service → Milvus vector store: reads and writes vectors (evidence: `rag/kb/service/milvus_kb_service.py`)
- Milvus KB service → Load and split files: uses file metadata (evidence: `rag/kb/service/milvus_kb_service.py`)
- Message repository → DB session layer: opens DB session (evidence: `db/repository/message_repository.py`)
- DB session layer → MySQL database: commits transactions (evidence: `utils/session.py`)
- Plan repository → Plan model: loads and stores plans (evidence: `db/repository/plan_repository.py`)
- Plan model → Task model: contains tasks (evidence: `db/models/plan_model.py`)
- Plan repository → DB session layer: uses DB session (evidence: `db/repository/plan_repository.py`)
- Runtime configuration → DB session layer: configures database (evidence: `utils/session.py`)
- Runtime configuration → Milvus KB service: configures vector store (evidence: `rag/kb/service/milvus_kb_service.py`)
