# 2696791698/vulnhunter architecture

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

- Interactive diagram: https://gitdiagram.com/2696791698/vulnhunter
- Repository: https://github.com/2696791698/vulnhunter

## Overview

VulnHunter is an AI-assisted code-vulnerability auditing tool with a Vue dashboard. The main workflow submits a repository URL and commit (or a function snippet), queues an audit, checks out the target, runs the agent, and presents its verdict. The dashboard also exposes environment checks, trace/span inspection, and token-usage analytics. The README documents MCP integrations and dataset extraction; source excerpts are partial, so uncertain internal call wiring is omitted.

Main entry points: [`web/server/main.py`](https://github.com/2696791698/vulnhunter/blob/main/web/server/main.py) (Bridge service), [`web/src/lib/api.ts`](https://github.com/2696791698/vulnhunter/blob/main/web/src/lib/api.ts) (Dashboard API client), [`audit_agent.py`](https://github.com/2696791698/vulnhunter/blob/main/audit_agent.py) (Audit agent), [`web/src/pages/AuditPage.vue`](https://github.com/2696791698/vulnhunter/blob/main/web/src/pages/AuditPage.vue) (Audit submission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audit["Audit workflow"]
  node_checkout["Repository checkout<br/>[main.py]"]
  node_agent["Audit agent<br/>[audit_agent.py]"]
  node_agent_base["Agent framework<br/>[base_agent.py]"]
  node_model["Model configuration<br/>[create_model.py]"]
end

subgraph group_dashboard["Dashboard and bridge"]
  node_audit_ui["Audit submission<br/>[AuditPage.vue]"]
  node_task_state["Task polling<br/>[useAuditTasks.ts]"]
  node_api["Dashboard API client<br/>[api.ts]"]
  node_bridge["Bridge service<br/>[main.py]"]
  node_verdict_ui["Audit verdict details<br/>[AuditTaskSheet.vue]"]
  node_environment_ui["Environment dashboard<br/>[useEnvironment.ts]"]
  node_environment_check["Environment checks"]
end

subgraph group_observability["Agent observability"]
  node_tracing["Trace instrumentation<br/>[agent_tracing.py]"]
  node_trace_ui["Trace explorer<br/>[useAgentTraces.ts]"]
  node_usage_ui["Token usage<br/>[useTokenUsage.ts]"]
end

subgraph group_data["Dataset extraction"]
  node_dataset["PyVul dataset extraction"]
end

node_operator(("Security engineer"))
node_mcp_tools{{"MCP analysis tools"}}
node_target_repo[("Target repository")]
node_pyvul[("PyVul advisories")]

node_operator -->|"submits audit"| node_audit_ui
node_audit_ui -->|"submits task"| node_task_state
node_task_state -->|"calls API"| node_api
node_api -->|"HTTP requests"| node_bridge
node_bridge -->|"queues task"| node_checkout
node_checkout -->|"clones commit"| node_target_repo
node_checkout -->|"starts audit"| node_agent
node_agent -->|"uses framework"| node_agent_base
node_agent -->|"creates model"| node_model
node_agent -.->|"uses tools"| node_mcp_tools
node_bridge -->|"serves task result"| node_verdict_ui
node_operator -->|"requests checks"| node_environment_ui
node_environment_ui -->|"calls API"| node_api
node_bridge -->|"runs checks"| node_environment_check
node_tracing -->|"posts span events"| node_bridge
node_trace_ui -->|"requests traces"| node_api
node_usage_ui -->|"requests usage"| node_api
node_dataset -->|"reads advisories"| node_pyvul

click node_audit_ui "https://github.com/2696791698/vulnhunter/blob/main/web/src/pages/AuditPage.vue"
click node_task_state "https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useAuditTasks.ts"
click node_api "https://github.com/2696791698/vulnhunter/blob/main/web/src/lib/api.ts"
click node_bridge "https://github.com/2696791698/vulnhunter/blob/main/web/server/main.py"
click node_checkout "https://github.com/2696791698/vulnhunter/blob/main/web/server/main.py"
click node_agent "https://github.com/2696791698/vulnhunter/blob/main/audit_agent.py"
click node_agent_base "https://github.com/2696791698/vulnhunter/blob/main/base_agent.py"
click node_model "https://github.com/2696791698/vulnhunter/blob/main/create_model.py"
click node_verdict_ui "https://github.com/2696791698/vulnhunter/blob/main/web/src/components/dashboard/AuditTaskSheet.vue"
click node_environment_ui "https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useEnvironment.ts"
click node_environment_check "https://github.com/2696791698/vulnhunter/blob/main/check_environment.py"
click node_tracing "https://github.com/2696791698/vulnhunter/blob/main/agent_tracing.py"
click node_trace_ui "https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useAgentTraces.ts"
click node_usage_ui "https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useTokenUsage.ts"
click node_dataset "https://github.com/2696791698/vulnhunter/blob/main/extract_pyvul_dataset.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_checkout,node_agent,node_agent_base,node_model toneBlue
class node_audit_ui,node_task_state,node_api,node_bridge,node_verdict_ui,node_environment_ui,node_environment_check,node_target_repo,node_pyvul toneAmber
class node_tracing,node_trace_ui,node_usage_ui toneMint
class node_dataset toneRose
class node_operator,node_mcp_tools toneIndigo
```

## Components

### Audit workflow

- [Repository checkout](https://github.com/2696791698/vulnhunter/blob/main/web/server/main.py): `web/server/main.py`
- [Audit agent](https://github.com/2696791698/vulnhunter/blob/main/audit_agent.py): `audit_agent.py`
- [Agent framework](https://github.com/2696791698/vulnhunter/blob/main/base_agent.py): `base_agent.py`
- [Model configuration](https://github.com/2696791698/vulnhunter/blob/main/create_model.py): `create_model.py`

### Dashboard and bridge

- [Audit submission](https://github.com/2696791698/vulnhunter/blob/main/web/src/pages/AuditPage.vue): `web/src/pages/AuditPage.vue`
- [Task polling](https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useAuditTasks.ts): `web/src/composables/useAuditTasks.ts`
- [Dashboard API client](https://github.com/2696791698/vulnhunter/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Bridge service](https://github.com/2696791698/vulnhunter/blob/main/web/server/main.py): `web/server/main.py`
- [Audit verdict details](https://github.com/2696791698/vulnhunter/blob/main/web/src/components/dashboard/AuditTaskSheet.vue): `web/src/components/dashboard/AuditTaskSheet.vue`
- [Environment dashboard](https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useEnvironment.ts): `web/src/composables/useEnvironment.ts`
- [Environment checks](https://github.com/2696791698/vulnhunter/blob/main/check_environment.py): `check_environment.py`

### Agent observability

- [Trace instrumentation](https://github.com/2696791698/vulnhunter/blob/main/agent_tracing.py): `agent_tracing.py`
- [Trace explorer](https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useAgentTraces.ts): `web/src/composables/useAgentTraces.ts`
- [Token usage](https://github.com/2696791698/vulnhunter/blob/main/web/src/composables/useTokenUsage.ts): `web/src/composables/useTokenUsage.ts`

### Dataset extraction

- [PyVul dataset extraction](https://github.com/2696791698/vulnhunter/blob/main/extract_pyvul_dataset.py): `extract_pyvul_dataset.py`

### Other components

- **Security engineer**
- **MCP analysis tools**
- **Target repository**
- **PyVul advisories**

## Connections

- Security engineer → Audit submission: submits audit
- Audit submission → Task polling: submits task
- Task polling → Dashboard API client: calls API
- Dashboard API client → Bridge service: HTTP requests
- Bridge service → Repository checkout: queues task
- Repository checkout → Target repository: clones commit
- Repository checkout → Audit agent: starts audit
- Audit agent → Agent framework: uses framework
- Audit agent → Model configuration: creates model
- Audit agent → MCP analysis tools: uses tools
- Bridge service → Audit verdict details: serves task result
- Security engineer → Environment dashboard: requests checks
- Environment dashboard → Dashboard API client: calls API
- Bridge service → Environment checks: runs checks
- Trace instrumentation → Bridge service: posts span events
- Trace explorer → Dashboard API client: requests traces
- Token usage → Dashboard API client: requests usage
- PyVul dataset extraction → PyVul advisories: reads advisories