# shivraste23/vulnclaw architecture

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

- Interactive diagram: https://gitdiagram.com/shivraste23/vulnclaw
- Repository: https://github.com/shivraste23/vulnclaw

## Overview

VulnClaw is an AI-assisted penetration-testing agent with CLI, terminal-workbench, and Web UI entry points. The documented main workflow takes a natural-language objective through reconnaissance, vulnerability discovery, exploitation/verification, and report generation. The graph also preserves the product’s MCP, plugin, traffic-evidence, skills, and knowledge-base capabilities. Relationships follow README claims and sampled entry-point/tool-management code; several unsampled subsystem connections are intentionally left unspecified.

Main entry points: [`vulnclaw/agent/tool_call_manager.py`](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/tool_call_manager.py) (Tool Dispatch), [`vulnclaw/agent/loop_controller.py`](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/loop_controller.py) (Solve and Loop), [`vulnclaw/orchestrator.py`](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/orchestrator.py) (Run Orchestrator), [`vulnclaw/intel/findings.py`](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/intel/findings.py) (Finding Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI and REPL<br/>[main.py]"]
  node_tui["Terminal Workbench<br/>[app.rs]"]
  node_webui["Web UI<br/>[App.tsx]"]
  node_webapi["Web API<br/>[app.py]"]
  node_tasks["Web Task Manager<br/>[task_manager.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_orchestrator["Run Orchestrator<br/>[orchestrator.py]"]
  node_agentcore["Autonomous Agent<br/>[core.py]"]
  node_solve["Solve and Loop<br/>[loop_controller.py]"]
  node_llm["LLM Client<br/>[llm_client.py]"]
  node_tools["Tool Dispatch"]
end

subgraph group_capabilities["Security Capabilities"]
  node_recon["Reconnaissance<br/>[recon_tools.py]"]
  node_intel["Vulnerability Intelligence<br/>[tools.py]"]
  node_plugins["Detection Plugins<br/>[runtime.py]"]
  node_skills["Skills and Knowledge<br/>[dispatcher.py]"]
end

subgraph group_evidence["Evidence and Reports"]
  node_traffic[("Traffic Evidence<br/>[store.py]")]
  node_findings["Finding Analysis<br/>[findings.py]"]
  node_report["Report and PoC<br/>[generator.py]"]
  node_reportui["Report Export<br/>[pdf_exporter.py]"]
end

subgraph group_integrations["Integrations and State"]
  node_mcp["MCP Services<br/>[router.py]"]
  node_externaltools{{"External MCP Tools"}}
  node_provider{{"Model Provider"}}
  node_state[("Run and Target State<br/>[store.py]")]
  node_kb[("Knowledge Base<br/>[retriever.py]")]
end

node_user(("Operator"))
node_target(("Authorized Target"))

node_user -->|"submits objective"| node_cli
node_user -->|"submits objective"| node_tui
node_user -->|"submits objective"| node_webui
node_webui -->|"calls API"| node_webapi
node_webapi -->|"starts task"| node_tasks
node_cli -->|"starts run"| node_orchestrator
node_tasks -->|"runs task"| node_orchestrator
node_tui -->|"executes command"| node_orchestrator
node_orchestrator -->|"creates agent"| node_agentcore
node_agentcore -->|"solves objective"| node_solve
node_solve -->|"requests reasoning"| node_llm
node_llm -->|"sends completion request"| node_provider
node_solve -->|"dispatches tool calls"| node_tools
node_tools -->|"executes MCP tool"| node_mcp
node_mcp -.->|"dispatches requests"| node_externaltools
node_tools -->|"invokes tools"| node_recon
node_tools -->|"invokes tools"| node_intel
node_tools -->|"runs plugins"| node_plugins
node_tools -->|"loads references"| node_skills
node_tools -->|"records traffic evidence"| node_traffic
node_traffic -->|"serves evidence queries"| node_tools
node_tools -->|"records run state"| node_state
node_solve -->|"parses findings"| node_findings
node_findings -->|"supplies findings"| node_report
node_orchestrator -->|"generates reports"| node_report
node_report -.->|"exports PDF"| node_reportui
node_solve -.->|"retrieves context"| node_kb
node_recon -->|"probes target"| node_target
node_intel -->|"analyzes target evidence"| node_target
node_plugins -->|"contributes results"| node_findings

click node_cli "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/cli/main.py"
click node_tui "https://github.com/shivraste23/vulnclaw/blob/main/tui/src/app.rs"
click node_webui "https://github.com/shivraste23/vulnclaw/blob/main/frontend/src/App.tsx"
click node_webapi "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/web/app.py"
click node_tasks "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/web/task_manager.py"
click node_orchestrator "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/orchestrator.py"
click node_agentcore "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/core.py"
click node_solve "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/loop_controller.py"
click node_llm "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/llm_client.py"
click node_tools "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/tool_call_manager.py"
click node_recon "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/recon_tools.py"
click node_intel "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/intel/tools.py"
click node_plugins "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/plugins/runtime.py"
click node_skills "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/skills/dispatcher.py"
click node_mcp "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/mcp/router.py"
click node_state "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/target_state/store.py"
click node_traffic "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/traffic/store.py"
click node_findings "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/intel/findings.py"
click node_report "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/report/generator.py"
click node_reportui "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/report/pdf_exporter.py"
click node_kb "https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/kb/retriever.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_tui,node_webui,node_webapi,node_tasks toneBlue
class node_orchestrator,node_agentcore,node_solve,node_llm,node_tools toneAmber
class node_recon,node_intel,node_plugins,node_skills toneMint
class node_traffic,node_findings,node_report,node_reportui toneRose
class node_mcp,node_externaltools,node_provider,node_state,node_kb,node_user,node_target toneIndigo
```

## Components

### User Interfaces

- [CLI and REPL](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/cli/main.py): `vulnclaw/cli/main.py`
- [Terminal Workbench](https://github.com/shivraste23/vulnclaw/blob/main/tui/src/app.rs): `tui/src/app.rs`
- [Web UI](https://github.com/shivraste23/vulnclaw/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Web API](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/web/app.py): `vulnclaw/web/app.py`
- [Web Task Manager](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/web/task_manager.py): `vulnclaw/web/task_manager.py`

### Agent Runtime

- [Run Orchestrator](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/orchestrator.py): `vulnclaw/orchestrator.py`
- [Autonomous Agent](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/core.py): `vulnclaw/agent/core.py`
- [Solve and Loop](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/loop_controller.py): `vulnclaw/agent/loop_controller.py`
- [LLM Client](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/llm_client.py): `vulnclaw/agent/llm_client.py`
- [Tool Dispatch](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/tool_call_manager.py): `vulnclaw/agent/tool_call_manager.py`

### Security Capabilities

- [Reconnaissance](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/agent/recon_tools.py): `vulnclaw/agent/recon_tools.py`
- [Vulnerability Intelligence](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/intel/tools.py): `vulnclaw/intel/tools.py`
- [Detection Plugins](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/plugins/runtime.py): `vulnclaw/plugins/runtime.py`
- [Skills and Knowledge](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/skills/dispatcher.py): `vulnclaw/skills/dispatcher.py`

### Evidence and Reports

- [Traffic Evidence](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/traffic/store.py): `vulnclaw/traffic/store.py`
- [Finding Analysis](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/intel/findings.py): `vulnclaw/intel/findings.py`
- [Report and PoC](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/report/generator.py): `vulnclaw/report/generator.py`
- [Report Export](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/report/pdf_exporter.py): `vulnclaw/report/pdf_exporter.py`

### Integrations and State

- [MCP Services](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/mcp/router.py): `vulnclaw/mcp/router.py`
- **External MCP Tools**
- **Model Provider**
- [Run and Target State](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/target_state/store.py): `vulnclaw/target_state/store.py`
- [Knowledge Base](https://github.com/shivraste23/vulnclaw/blob/main/vulnclaw/kb/retriever.py): `vulnclaw/kb/retriever.py`

### Other components

- **Operator**
- **Authorized Target**

## Connections

- Operator → CLI and REPL: submits objective
- Operator → Terminal Workbench: submits objective
- Operator → Web UI: submits objective
- Web UI → Web API: calls API
- Web API → Web Task Manager: starts task
- CLI and REPL → Run Orchestrator: starts run
- Web Task Manager → Run Orchestrator: runs task
- Terminal Workbench → Run Orchestrator: executes command
- Run Orchestrator → Autonomous Agent: creates agent
- Autonomous Agent → Solve and Loop: solves objective
- Solve and Loop → LLM Client: requests reasoning
- LLM Client → Model Provider: sends completion request
- Solve and Loop → Tool Dispatch: dispatches tool calls
- Tool Dispatch → MCP Services: executes MCP tool
- MCP Services → External MCP Tools: dispatches requests
- Tool Dispatch → Reconnaissance: invokes tools
- Tool Dispatch → Vulnerability Intelligence: invokes tools
- Tool Dispatch → Detection Plugins: runs plugins
- Tool Dispatch → Skills and Knowledge: loads references
- Tool Dispatch → Traffic Evidence: records traffic evidence
- Traffic Evidence → Tool Dispatch: serves evidence queries
- Tool Dispatch → Run and Target State: records run state
- Solve and Loop → Finding Analysis: parses findings
- Finding Analysis → Report and PoC: supplies findings
- Run Orchestrator → Report and PoC: generates reports
- Report and PoC → Report Export: exports PDF
- Solve and Loop → Knowledge Base: retrieves context
- Reconnaissance → Authorized Target: probes target
- Vulnerability Intelligence → Authorized Target: analyzes target evidence
- Detection Plugins → Finding Analysis: contributes results