# nealbridges/vulnhunter architecture

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

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

## Overview

VulnHunter is an agentic source-code security auditing tool, with a separate fix/verification-support package and a local batch harness. The principal workflow is to configure and clone a target, run a harness skill scan, extract findings, then manage issues and adversarial verification; findings can also be audited and published. The README describes portable harness operation and planned sandboxed exploit validation and measured-impact PoCs, but the supplied tree does not expose the skill prompts or a sandbox runtime implementation. Edges reflect shown imports/references and documented capabilities; unsampled internals are not inferred.

Main entry points: [`vulnhunter-agent/agent/__main__.py`](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/__main__.py) (Agent CLI), [`vulnhunter-agent/agent/runner.py`](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/runner.py) (Scan runner), [`vulnhunter-agent/agent/issues.py`](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/issues.py) (Issue workflow), [`vulnhunter-agent/agent/publish.py`](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/publish.py) (Report publishing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent workflow"]
  node_entry["Agent CLI<br/>[__main__.py]"]
  node_config["Agent config<br/>[config.py]"]
  node_clone["Repository clone<br/>[clone.py]"]
  node_runner["Scan runner<br/>[runner.py]"]
  node_audit["Audit records<br/>[audit.py]"]
  node_extract["Audit extraction<br/>[audit_extract.py]"]
  node_issues["Issue workflow<br/>[issues.py]"]
  node_verify["Finding verification<br/>[verify.py]"]
  node_verify_support["Verification stages<br/>[verify_extract.py]"]
end

subgraph group_github["GitHub and model"]
  node_properties["Repository metadata<br/>[repo_properties.py]"]
  node_auth["Model authentication<br/>[auth.py]"]
  node_llm["LLM client<br/>[_llm.py]"]
  node_github_helpers["GitHub helpers<br/>[_github.py]"]
  node_token["GitHub token client<br/>[token_client.py]"]
  node_publish["Report publishing<br/>[publish.py]"]
end

subgraph group_harness["Local harness"]
  node_harness_batch["Batch benchmark runner<br/>[run.py]"]
  node_harness_clone["Harness cloning<br/>[clone.py]"]
  node_harness_scan["Harness scan<br/>[scan.py]"]
  node_harness_config["Harness configuration<br/>[config.py]"]
end

subgraph group_fix["Fix support"]
  node_graph_build["Graph builder<br/>[build.py]"]
  node_graph_config["Graph configuration<br/>[config.py]"]
  node_graph_fallback["Fallback graph<br/>[fallback.py]"]
  node_graph_query["Graph queries<br/>[query.py]"]
  node_graph_schema["Graph schema<br/>[schema.py]"]
  node_delivery["Fix delivery<br/>[delivery.py]"]
end

node_operator(("Operator"))
node_github["GitHub"]
node_model["Model service"]

node_operator -->|"invokes"| node_entry
node_entry -->|"loads"| node_config
node_entry -->|"dispatches"| node_clone
node_entry -->|"dispatches"| node_runner
node_entry -->|"dispatches"| node_issues
node_entry -->|"dispatches"| node_verify
node_entry -->|"emits records"| node_audit
node_entry -->|"resolves metadata"| node_properties
node_entry -->|"dispatches"| node_publish
node_entry -->|"uses"| node_token
node_runner -->|"uses"| node_auth
node_runner -->|"records scan"| node_audit
node_runner -->|"uses"| node_extract
node_runner -.->|"starts session"| node_model
node_issues -->|"uses"| node_llm
node_issues -->|"uses"| node_github_helpers
node_issues -->|"uses"| node_token
node_verify -->|"uses"| node_verify_support
node_verify -->|"records decisions"| node_audit
node_properties -->|"authenticates requests"| node_token
node_properties -->|"fetches properties"| node_github
node_publish -->|"uses"| node_github_helpers
node_publish -->|"uses"| node_token
node_publish -->|"publishes reports"| node_github
node_harness_batch -->|"uses"| node_harness_clone
node_harness_batch -->|"runs scans"| node_harness_scan
node_harness_batch -->|"loads settings"| node_harness_config
node_harness_scan -->|"reads settings"| node_harness_config
node_graph_build -->|"uses"| node_graph_config
node_graph_build -->|"uses fallback"| node_graph_fallback
node_graph_build -->|"builds document"| node_graph_schema
node_graph_query -->|"queries fallback"| node_graph_fallback
node_graph_query -->|"uses document"| node_graph_schema

click node_entry "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/__main__.py"
click node_config "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/config.py"
click node_clone "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/clone.py"
click node_runner "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/runner.py"
click node_audit "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/audit.py"
click node_extract "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/audit_extract.py"
click node_issues "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/issues.py"
click node_verify "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/verify.py"
click node_verify_support "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/verify_extract.py"
click node_properties "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/repo_properties.py"
click node_auth "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/auth.py"
click node_llm "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/_llm.py"
click node_github_helpers "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/_github.py"
click node_token "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/token_client.py"
click node_publish "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/publish.py"
click node_harness_batch "https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/batch/run.py"
click node_harness_clone "https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/clone.py"
click node_harness_scan "https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/scan.py"
click node_harness_config "https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/config.py"
click node_graph_build "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/build.py"
click node_graph_config "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/config.py"
click node_graph_fallback "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/fallback.py"
click node_graph_query "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/query.py"
click node_graph_schema "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/schema.py"
click node_delivery "https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/delivery.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_entry,node_config,node_clone,node_runner,node_audit,node_extract,node_issues,node_verify,node_verify_support toneBlue
class node_properties,node_auth,node_llm,node_github_helpers,node_token,node_publish toneAmber
class node_harness_batch,node_harness_clone,node_harness_scan,node_harness_config toneMint
class node_graph_build,node_graph_config,node_graph_fallback,node_graph_query,node_graph_schema,node_delivery toneRose
class node_operator,node_github,node_model toneIndigo
```

## Components

### Agent workflow

- [Agent CLI](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/__main__.py): `vulnhunter-agent/agent/__main__.py`
- [Agent config](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/config.py): `vulnhunter-agent/agent/config.py`
- [Repository clone](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/clone.py): `vulnhunter-agent/agent/clone.py`
- [Scan runner](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/runner.py): `vulnhunter-agent/agent/runner.py`
- [Audit records](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/audit.py): `vulnhunter-agent/agent/audit.py`
- [Audit extraction](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/audit_extract.py): `vulnhunter-agent/agent/audit_extract.py`
- [Issue workflow](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/issues.py): `vulnhunter-agent/agent/issues.py`
- [Finding verification](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/verify.py): `vulnhunter-agent/agent/verify.py`
- [Verification stages](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/verify_extract.py): `vulnhunter-agent/agent/verify_extract.py`

### GitHub and model

- [Repository metadata](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/repo_properties.py): `vulnhunter-agent/agent/repo_properties.py`
- [Model authentication](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/auth.py): `vulnhunter-agent/agent/auth.py`
- [LLM client](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/_llm.py): `vulnhunter-agent/agent/_llm.py`
- [GitHub helpers](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/_github.py): `vulnhunter-agent/agent/_github.py`
- [GitHub token client](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/token_client.py): `vulnhunter-agent/agent/token_client.py`
- [Report publishing](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-agent/agent/publish.py): `vulnhunter-agent/agent/publish.py`

### Local harness

- [Batch benchmark runner](https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/batch/run.py): `harness/local_harness/batch/run.py`
- [Harness cloning](https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/clone.py): `harness/local_harness/clone.py`
- [Harness scan](https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/scan.py): `harness/local_harness/scan.py`
- [Harness configuration](https://github.com/nealbridges/vulnhunter/blob/main/harness/local_harness/config.py): `harness/local_harness/config.py`

### Fix support

- [Graph builder](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/build.py): `vulnhunter-fix/vulnhunter_fix/graph/build.py`
- [Graph configuration](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/config.py): `vulnhunter-fix/vulnhunter_fix/graph/config.py`
- [Fallback graph](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/fallback.py): `vulnhunter-fix/vulnhunter_fix/graph/fallback.py`
- [Graph queries](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/query.py): `vulnhunter-fix/vulnhunter_fix/graph/query.py`
- [Graph schema](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/graph/schema.py): `vulnhunter-fix/vulnhunter_fix/graph/schema.py`
- [Fix delivery](https://github.com/nealbridges/vulnhunter/blob/main/vulnhunter-fix/vulnhunter_fix/delivery.py): `vulnhunter-fix/vulnhunter_fix/delivery.py`

### Other components

- **Operator**
- **GitHub**
- **Model service**

## Connections

- Operator → Agent CLI: invokes (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Agent config: loads (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Repository clone: dispatches (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Scan runner: dispatches (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Issue workflow: dispatches (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Finding verification: dispatches (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Audit records: emits records (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Repository metadata: resolves metadata (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → Report publishing: dispatches (evidence: `vulnhunter-agent/agent/__main__.py`)
- Agent CLI → GitHub token client: uses (evidence: `vulnhunter-agent/agent/__main__.py`)
- Scan runner → Model authentication: uses (evidence: `vulnhunter-agent/agent/runner.py`)
- Scan runner → Audit records: records scan (evidence: `vulnhunter-agent/agent/runner.py`)
- Scan runner → Audit extraction: uses (evidence: `vulnhunter-agent/agent/runner.py`)
- Scan runner → Model service: starts session
- Issue workflow → LLM client: uses (evidence: `vulnhunter-agent/agent/issues.py`)
- Issue workflow → GitHub helpers: uses (evidence: `vulnhunter-agent/agent/issues.py`)
- Issue workflow → GitHub token client: uses (evidence: `vulnhunter-agent/agent/issues.py`)
- Finding verification → Verification stages: uses (evidence: `vulnhunter-agent/agent/verify.py`)
- Finding verification → Audit records: records decisions (evidence: `vulnhunter-agent/agent/verify.py`)
- Repository metadata → GitHub token client: authenticates requests (evidence: `vulnhunter-agent/agent/repo_properties.py`)
- Repository metadata → GitHub: fetches properties (evidence: `vulnhunter-agent/agent/repo_properties.py`)
- Report publishing → GitHub helpers: uses (evidence: `vulnhunter-agent/agent/publish.py`)
- Report publishing → GitHub token client: uses (evidence: `vulnhunter-agent/agent/publish.py`)
- Report publishing → GitHub: publishes reports (evidence: `vulnhunter-agent/agent/publish.py`)
- Batch benchmark runner → Harness cloning: uses (evidence: `harness/local_harness/batch/run.py`)
- Batch benchmark runner → Harness scan: runs scans (evidence: `harness/local_harness/batch/run.py`)
- Batch benchmark runner → Harness configuration: loads settings (evidence: `harness/local_harness/batch/run.py`)
- Harness scan → Harness configuration: reads settings (evidence: `harness/local_harness/scan.py`)
- Graph builder → Graph configuration: uses (evidence: `vulnhunter-fix/vulnhunter_fix/graph/build.py`)
- Graph builder → Fallback graph: uses fallback (evidence: `vulnhunter-fix/vulnhunter_fix/graph/build.py`)
- Graph builder → Graph schema: builds document (evidence: `vulnhunter-fix/vulnhunter_fix/graph/build.py`)
- Graph queries → Fallback graph: queries fallback (evidence: `vulnhunter-fix/vulnhunter_fix/graph/query.py`)
- Graph queries → Graph schema: uses document (evidence: `vulnhunter-fix/vulnhunter_fix/graph/query.py`)
