# unclecheng-li/vulnclaw architecture

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

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

## Overview

VulnClaw is an AI-assisted penetration-testing product with CLI, terminal-workbench and Web UI entry points. Its principal workflow accepts a target and task, orchestrates an agent-led reconnaissance/discovery/exploitation loop with tool-backed evidence, then produces a report; target state supports resumption. The README also documents local code scanning, plugins, MCP integrations, traffic evidence, skills and a knowledge base. Edges use README statements or SOURCE INDEX references; unsampled subsystem connections are omitted where not established.

Main entry points: [`vulnclaw/agent/core.py`](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/core.py) (Agent Engine), [`vulnclaw/web/app.py`](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/web/app.py) (Web API), [`vulnclaw/task_service.py`](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/task_service.py) (Task Service), [`vulnclaw/cli/main.py`](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/cli/main.py) (CLI Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

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

subgraph group_execution["Task Execution"]
  node_taskservice["Task Service<br/>[task_service.py]"]
  node_orchestrator["Run Orchestrator<br/>[orchestrator.py]"]
  node_targetstate[("Target State<br/>[store.py]")]
  node_config["Configuration<br/>[settings.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_agentcore["Agent Engine<br/>[core.py]"]
  node_agentcontext["Session Context<br/>[context.py]"]
  node_llm["LLM Client<br/>[llm_client.py]"]
  node_toolcalls["Tool Dispatch"]
end

subgraph group_evidence["Evidence and Results"]
  node_traffic[("Traffic Evidence<br/>[store.py]")]
  node_report["Report Generator<br/>[generator.py]"]
  node_codescan["Source Scanner<br/>[scanner.py]"]
end

subgraph group_extensions["Integrations and Knowledge"]
  node_mcp["MCP Lifecycle<br/>[lifecycle.py]"]
  node_plugins["Detection Plugins<br/>[runtime.py]"]
  node_skills["Skill References<br/>[loader.py]"]
  node_knowledge[("Knowledge Base<br/>[retriever.py]")]
end

node_user(("Operator"))

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_webui
node_user -->|"submits task"| node_tui
node_webui -.->|"requests tasks"| node_webapi
node_tui -->|"initializes backend"| node_webapi
node_cli -->|"dispatches task"| node_taskservice
node_webapi -->|"starts tasks"| node_taskservice
node_taskservice -->|"runs task"| node_orchestrator
node_orchestrator -->|"invokes agent"| node_agentcore
node_orchestrator -->|"loads and saves"| node_targetstate
node_taskservice -->|"uses target state"| node_targetstate
node_taskservice -->|"runs code scan"| node_codescan
node_agentcore -->|"uses context"| node_agentcontext
node_agentcore -->|"requests completions"| node_llm
node_agentcore -->|"dispatches calls"| node_toolcalls
node_toolcalls -->|"executes tools"| node_mcp
node_agentcore -->|"generates reports"| node_report
node_webapi -->|"serves reports"| node_report
node_agentcore -.->|"records traffic"| node_traffic
node_agentcore -.->|"uses plugins"| node_plugins
node_agentcore -.->|"loads references"| node_skills
node_agentcore -.->|"retrieves knowledge"| node_knowledge
node_cli -->|"loads settings"| node_config
node_webapi -->|"configures services"| node_config

click node_cli "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/cli/main.py"
click node_webui "https://github.com/unclecheng-li/vulnclaw/blob/main/frontend/src/App.tsx"
click node_webapi "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/web/app.py"
click node_tui "https://github.com/unclecheng-li/vulnclaw/blob/main/tui/src/app.rs"
click node_taskservice "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/task_service.py"
click node_orchestrator "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/orchestrator.py"
click node_targetstate "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/target_state/store.py"
click node_agentcore "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/core.py"
click node_agentcontext "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/context.py"
click node_llm "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/llm_client.py"
click node_toolcalls "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/tool_call_manager.py"
click node_mcp "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/mcp/lifecycle.py"
click node_traffic "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/traffic/store.py"
click node_report "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/report/generator.py"
click node_codescan "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/codescan/scanner.py"
click node_plugins "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/plugins/runtime.py"
click node_skills "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/skills/loader.py"
click node_knowledge "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/kb/retriever.py"
click node_config "https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/config/settings.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_webui,node_webapi,node_tui toneBlue
class node_taskservice,node_orchestrator,node_targetstate,node_config toneAmber
class node_agentcore,node_agentcontext,node_llm,node_toolcalls toneMint
class node_traffic,node_report,node_codescan toneRose
class node_mcp,node_plugins,node_skills,node_knowledge,node_user toneIndigo
```

## Components

### User Interfaces

- [CLI Commands](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/cli/main.py): `vulnclaw/cli/main.py`
- [Web UI](https://github.com/unclecheng-li/vulnclaw/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Web API](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/web/app.py): `vulnclaw/web/app.py`
- [Terminal Workbench](https://github.com/unclecheng-li/vulnclaw/blob/main/tui/src/app.rs): `tui/src/app.rs`

### Task Execution

- [Task Service](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/task_service.py): `vulnclaw/task_service.py`
- [Run Orchestrator](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/orchestrator.py): `vulnclaw/orchestrator.py`
- [Target State](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/target_state/store.py): `vulnclaw/target_state/store.py`
- [Configuration](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/config/settings.py): `vulnclaw/config/settings.py`

### Agent Runtime

- [Agent Engine](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/core.py): `vulnclaw/agent/core.py`
- [Session Context](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/context.py): `vulnclaw/agent/context.py`
- [LLM Client](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/llm_client.py): `vulnclaw/agent/llm_client.py`
- [Tool Dispatch](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/agent/tool_call_manager.py): `vulnclaw/agent/tool_call_manager.py`

### Evidence and Results

- [Traffic Evidence](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/traffic/store.py): `vulnclaw/traffic/store.py`
- [Report Generator](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/report/generator.py): `vulnclaw/report/generator.py`
- [Source Scanner](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/codescan/scanner.py): `vulnclaw/codescan/scanner.py`

### Integrations and Knowledge

- [MCP Lifecycle](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/mcp/lifecycle.py): `vulnclaw/mcp/lifecycle.py`
- [Detection Plugins](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/plugins/runtime.py): `vulnclaw/plugins/runtime.py`
- [Skill References](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/skills/loader.py): `vulnclaw/skills/loader.py`
- [Knowledge Base](https://github.com/unclecheng-li/vulnclaw/blob/main/vulnclaw/kb/retriever.py): `vulnclaw/kb/retriever.py`

### Other components

- **Operator**

## Connections

- Operator → CLI Commands: submits task
- Operator → Web UI: submits task
- Operator → Terminal Workbench: submits task
- Web UI → Web API: requests tasks
- Terminal Workbench → Web API: initializes backend (evidence: `tui/src/app.rs`)
- CLI Commands → Task Service: dispatches task (evidence: `vulnclaw/cli/main.py`)
- Web API → Task Service: starts tasks (evidence: `vulnclaw/web/app.py`)
- Task Service → Run Orchestrator: runs task (evidence: `vulnclaw/task_service.py`)
- Run Orchestrator → Agent Engine: invokes agent (evidence: `vulnclaw/orchestrator.py`)
- Run Orchestrator → Target State: loads and saves (evidence: `vulnclaw/orchestrator.py`)
- Task Service → Target State: uses target state (evidence: `vulnclaw/task_service.py`)
- Task Service → Source Scanner: runs code scan (evidence: `vulnclaw/task_service.py`)
- Agent Engine → Session Context: uses context (evidence: `vulnclaw/agent/core.py`)
- Agent Engine → LLM Client: requests completions (evidence: `vulnclaw/agent/core.py`)
- Agent Engine → Tool Dispatch: dispatches calls (evidence: `vulnclaw/agent/core.py`)
- Tool Dispatch → MCP Lifecycle: executes tools (evidence: `vulnclaw/agent/tool_call_manager.py`)
- Agent Engine → Report Generator: generates reports
- Web API → Report Generator: serves reports (evidence: `vulnclaw/web/app.py`)
- Agent Engine → Traffic Evidence: records traffic
- Agent Engine → Detection Plugins: uses plugins
- Agent Engine → Skill References: loads references
- Agent Engine → Knowledge Base: retrieves knowledge (evidence: `vulnclaw/agent/core.py`)
- CLI Commands → Configuration: loads settings (evidence: `vulnclaw/cli/main.py`)
- Web API → Configuration: configures services (evidence: `vulnclaw/web/app.py`)