# buseclab/cve-genie architecture

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

- Interactive diagram: https://gitdiagram.com/buseclab/cve-genie
- Repository: https://github.com/buseclab/cve-genie

## Overview

CVE-Genie extracts or accepts vulnerability context, then coordinates repository preparation, exploit development, and verification to produce a reproduction run. Its agent library supplies planning, model access, parsing, persistence, tool execution, and a conversation console; VM utilities provide an alternate execution environment, while the visualizer inspects completed runs. The README documents these product stages and capabilities. Some subsystem connections are documented only at a high level; unsampled implementation details are not inferred.

Main entry points: [`src/agentlib/agentlib/lib/agents/agent.py`](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/agent.py) (Agent execution), [`src/main.py`](https://github.com/buseclab/cve-genie/blob/main/src/main.py) (Run orchestrator), [`src/agents/repoBuilder.py`](https://github.com/buseclab/cve-genie/blob/main/src/agents/repoBuilder.py) (Repository builder), [`vm_library/run_cve.py`](https://github.com/buseclab/cve-genie/blob/main/vm_library/run_cve.py) (VM execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CVE reproduction"]
  node_cve_data["CVE extraction<br/>[cve_data.py]"]
  node_data_processing["Context processing"]
  node_orchestrator["Run orchestrator<br/>[main.py]"]
end

subgraph group_agents["Agent workflows"]
  node_repo_builder["Repository builder<br/>[repoBuilder.py]"]
  node_repo_critic["Repository critic<br/>[repoCritic.py]"]
  node_prereq_builder["Prerequisite builder<br/>[preReqBuilder.py]"]
  node_knowledge_builder["Knowledge builder"]
  node_exploiter["Exploit agent<br/>[exploiter.py]"]
  node_exploit_critic["Exploit critic<br/>[exploitCritic.py]"]
  node_verifier["CTF verifier<br/>[ctfVerifier.py]"]
  node_sanity["Sanity checks<br/>[sanityGuy.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_core["Agent execution<br/>[agent.py]"]
  node_planning["Plan execution<br/>[planning.py]"]
  node_critics["Agent review<br/>[critic.py]"]
  node_model_access["Model access<br/>[llm_api.py]"]
  node_model_registry["Model registry<br/>[available_llms.py]"]
  node_parsers["Output parsing<br/>[parsers.py]"]
  node_object_store[("Persistent objects<br/>[object.py]")]
  node_common_base["Runtime callbacks<br/>[base.py]"]
  node_code_support["Code handling<br/>[code.py]"]
  node_tooling["Agent tools<br/>[tool_wrapper.py]"]
  node_console["Agent console<br/>[web_console.py]"]
  node_llm_store[("LLM records<br/>[store.py]")]
end

subgraph group_operations["Execution and inspection"]
  node_command_tools["Shell operations<br/>[command_ops.py]"]
  node_tool_registry["Tool collection<br/>[tools.py]"]
  node_vm_runner["VM execution<br/>[run_cve.py]"]
  node_vm_snapshots["Snapshot runs"]
  node_qemu["QEMU utilities<br/>[qemu_utils.py]"]
  node_ssh["SSH utilities<br/>[ssh_utils.py]"]
  node_visualizer["Run visualizer<br/>[serve.py]"]
  node_log_parser["Log parsing<br/>[log-parser.js]"]
  node_data_loader["Run data loader<br/>[data-loader.js]"]
  node_visual_ui["Visualizer UI<br/>[ui.js]"]
end

node_engineer(("Engineer"))

node_engineer -->|"extracts context"| node_cve_data
node_engineer -->|"starts reproduction"| node_orchestrator
node_cve_data -.->|"prepares context"| node_data_processing
node_orchestrator -->|"processes context"| node_data_processing
node_orchestrator -->|"invokes build"| node_repo_builder
node_orchestrator -->|"invokes exploit"| node_exploiter
node_orchestrator -->|"invokes verify"| node_verifier
node_orchestrator -.->|"reviews repository"| node_repo_critic
node_orchestrator -->|"reviews exploit"| node_exploit_critic
node_orchestrator -.->|"builds prerequisites"| node_prereq_builder
node_orchestrator -.->|"builds knowledge"| node_knowledge_builder
node_orchestrator -.->|"checks run"| node_sanity
node_repo_builder -.->|"uses agent framework"| node_agent_core
node_exploiter -->|"uses agent framework"| node_agent_core
node_exploit_critic -->|"uses agent framework"| node_agent_core
node_sanity -->|"uses agent framework"| node_agent_core
node_agent_core -->|"calls model API"| node_model_access
node_agent_core -->|"selects model"| node_model_registry
node_agent_core -->|"parses responses"| node_parsers
node_agent_core -->|"dispatches tools"| node_tooling
node_agent_core -->|"persists objects"| node_object_store
node_agent_core -->|"uses callbacks"| node_common_base
node_planning -->|"extends execution"| node_agent_core
node_planning -->|"requests review"| node_critics
node_parsers -->|"extracts code"| node_code_support
node_repo_builder -.->|"uses tools"| node_tool_registry
node_tool_registry -->|"includes commands"| node_command_tools
node_engineer -->|"runs in VM"| node_vm_runner
node_vm_runner -->|"manages VM"| node_qemu
node_vm_runner -->|"connects by SSH"| node_ssh
node_vm_snapshots -->|"manages snapshots"| node_qemu
node_vm_snapshots -->|"connects by SSH"| node_ssh
node_engineer -->|"opens visualizer"| node_visualizer
node_visualizer -->|"serves interface"| node_visual_ui
node_visual_ui -->|"loads run"| node_data_loader
node_data_loader -->|"parses logs"| node_log_parser
node_agent_core -->|"records activity"| node_console
node_console -.->|"stores records"| node_llm_store

click node_cve_data "https://github.com/buseclab/cve-genie/blob/main/src/data/scripts/cve_data.py"
click node_data_processing "https://github.com/buseclab/cve-genie/blob/main/src/toolbox/cve_data_processor.py"
click node_orchestrator "https://github.com/buseclab/cve-genie/blob/main/src/main.py"
click node_repo_builder "https://github.com/buseclab/cve-genie/blob/main/src/agents/repoBuilder.py"
click node_repo_critic "https://github.com/buseclab/cve-genie/blob/main/src/agents/repoCritic.py"
click node_prereq_builder "https://github.com/buseclab/cve-genie/blob/main/src/agents/preReqBuilder.py"
click node_knowledge_builder "https://github.com/buseclab/cve-genie/blob/main/src/agents/knowledgeBuilder.py"
click node_exploiter "https://github.com/buseclab/cve-genie/blob/main/src/agents/exploiter.py"
click node_exploit_critic "https://github.com/buseclab/cve-genie/blob/main/src/agents/exploitCritic.py"
click node_verifier "https://github.com/buseclab/cve-genie/blob/main/src/agents/ctfVerifier.py"
click node_sanity "https://github.com/buseclab/cve-genie/blob/main/src/agents/sanityGuy.py"
click node_agent_core "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/agent.py"
click node_planning "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/planning.py"
click node_critics "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/critic.py"
click node_model_access "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/llm_api.py"
click node_model_registry "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/available_llms.py"
click node_parsers "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/parsers.py"
click node_object_store "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/object.py"
click node_common_base "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/base.py"
click node_code_support "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/code.py"
click node_tooling "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/tools/tool_wrapper.py"
click node_command_tools "https://github.com/buseclab/cve-genie/blob/main/src/toolbox/command_ops.py"
click node_tool_registry "https://github.com/buseclab/cve-genie/blob/main/src/toolbox/tools.py"
click node_vm_runner "https://github.com/buseclab/cve-genie/blob/main/vm_library/run_cve.py"
click node_vm_snapshots "https://github.com/buseclab/cve-genie/blob/main/vm_library/run_cve_with_snaps.py"
click node_qemu "https://github.com/buseclab/cve-genie/blob/main/vm_library/qemu_utils.py"
click node_ssh "https://github.com/buseclab/cve-genie/blob/main/vm_library/ssh_utils.py"
click node_visualizer "https://github.com/buseclab/cve-genie/blob/main/visualizer/serve.py"
click node_log_parser "https://github.com/buseclab/cve-genie/blob/main/visualizer/log-parser.js"
click node_data_loader "https://github.com/buseclab/cve-genie/blob/main/visualizer/data-loader.js"
click node_visual_ui "https://github.com/buseclab/cve-genie/blob/main/visualizer/ui.js"
click node_console "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/web_console.py"
click node_llm_store "https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/store.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_cve_data,node_data_processing,node_orchestrator toneBlue
class node_repo_builder,node_repo_critic,node_prereq_builder,node_knowledge_builder,node_exploiter,node_exploit_critic,node_verifier,node_sanity toneAmber
class node_agent_core,node_planning,node_critics,node_model_access,node_model_registry,node_parsers,node_object_store,node_common_base,node_code_support,node_tooling,node_console,node_llm_store toneMint
class node_command_tools,node_tool_registry,node_vm_runner,node_vm_snapshots,node_qemu,node_ssh,node_visualizer,node_log_parser,node_data_loader,node_visual_ui toneRose
class node_engineer toneIndigo
```

## Components

### CVE reproduction

- [CVE extraction](https://github.com/buseclab/cve-genie/blob/main/src/data/scripts/cve_data.py): `src/data/scripts/cve_data.py`
- [Context processing](https://github.com/buseclab/cve-genie/blob/main/src/toolbox/cve_data_processor.py): `src/toolbox/cve_data_processor.py`
- [Run orchestrator](https://github.com/buseclab/cve-genie/blob/main/src/main.py): `src/main.py`

### Agent workflows

- [Repository builder](https://github.com/buseclab/cve-genie/blob/main/src/agents/repoBuilder.py): `src/agents/repoBuilder.py`
- [Repository critic](https://github.com/buseclab/cve-genie/blob/main/src/agents/repoCritic.py): `src/agents/repoCritic.py`
- [Prerequisite builder](https://github.com/buseclab/cve-genie/blob/main/src/agents/preReqBuilder.py): `src/agents/preReqBuilder.py`
- [Knowledge builder](https://github.com/buseclab/cve-genie/blob/main/src/agents/knowledgeBuilder.py): `src/agents/knowledgeBuilder.py`
- [Exploit agent](https://github.com/buseclab/cve-genie/blob/main/src/agents/exploiter.py): `src/agents/exploiter.py`
- [Exploit critic](https://github.com/buseclab/cve-genie/blob/main/src/agents/exploitCritic.py): `src/agents/exploitCritic.py`
- [CTF verifier](https://github.com/buseclab/cve-genie/blob/main/src/agents/ctfVerifier.py): `src/agents/ctfVerifier.py`
- [Sanity checks](https://github.com/buseclab/cve-genie/blob/main/src/agents/sanityGuy.py): `src/agents/sanityGuy.py`

### Agent runtime

- [Agent execution](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/agent.py): `src/agentlib/agentlib/lib/agents/agent.py`
- [Plan execution](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/planning.py): `src/agentlib/agentlib/lib/agents/planning.py`
- [Agent review](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/agents/critic.py): `src/agentlib/agentlib/lib/agents/critic.py`
- [Model access](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/llm_api.py): `src/agentlib/agentlib/lib/common/llm_api.py`
- [Model registry](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/available_llms.py): `src/agentlib/agentlib/lib/common/available_llms.py`
- [Output parsing](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/parsers.py): `src/agentlib/agentlib/lib/common/parsers.py`
- [Persistent objects](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/object.py): `src/agentlib/agentlib/lib/common/object.py`
- [Runtime callbacks](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/base.py): `src/agentlib/agentlib/lib/common/base.py`
- [Code handling](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/code.py): `src/agentlib/agentlib/lib/common/code.py`
- [Agent tools](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/tools/tool_wrapper.py): `src/agentlib/agentlib/lib/tools/tool_wrapper.py`
- [Agent console](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/web_console.py): `src/agentlib/agentlib/lib/web_console.py`
- [LLM records](https://github.com/buseclab/cve-genie/blob/main/src/agentlib/agentlib/lib/common/store.py): `src/agentlib/agentlib/lib/common/store.py`

### Execution and inspection

- [Shell operations](https://github.com/buseclab/cve-genie/blob/main/src/toolbox/command_ops.py): `src/toolbox/command_ops.py`
- [Tool collection](https://github.com/buseclab/cve-genie/blob/main/src/toolbox/tools.py): `src/toolbox/tools.py`
- [VM execution](https://github.com/buseclab/cve-genie/blob/main/vm_library/run_cve.py): `vm_library/run_cve.py`
- [Snapshot runs](https://github.com/buseclab/cve-genie/blob/main/vm_library/run_cve_with_snaps.py): `vm_library/run_cve_with_snaps.py`
- [QEMU utilities](https://github.com/buseclab/cve-genie/blob/main/vm_library/qemu_utils.py): `vm_library/qemu_utils.py`
- [SSH utilities](https://github.com/buseclab/cve-genie/blob/main/vm_library/ssh_utils.py): `vm_library/ssh_utils.py`
- [Run visualizer](https://github.com/buseclab/cve-genie/blob/main/visualizer/serve.py): `visualizer/serve.py`
- [Log parsing](https://github.com/buseclab/cve-genie/blob/main/visualizer/log-parser.js): `visualizer/log-parser.js`
- [Run data loader](https://github.com/buseclab/cve-genie/blob/main/visualizer/data-loader.js): `visualizer/data-loader.js`
- [Visualizer UI](https://github.com/buseclab/cve-genie/blob/main/visualizer/ui.js): `visualizer/ui.js`

### Other components

- **Engineer**

## Connections

- Engineer → CVE extraction: extracts context (evidence: `README.md`)
- Engineer → Run orchestrator: starts reproduction (evidence: `README.md`)
- CVE extraction → Context processing: prepares context
- Run orchestrator → Context processing: processes context (evidence: `src/main.py`)
- Run orchestrator → Repository builder: invokes build (evidence: `src/main.py`)
- Run orchestrator → Exploit agent: invokes exploit (evidence: `src/main.py`)
- Run orchestrator → CTF verifier: invokes verify (evidence: `src/main.py`)
- Run orchestrator → Repository critic: reviews repository
- Run orchestrator → Exploit critic: reviews exploit (evidence: `src/main.py`)
- Run orchestrator → Prerequisite builder: builds prerequisites
- Run orchestrator → Knowledge builder: builds knowledge
- Run orchestrator → Sanity checks: checks run
- Repository builder → Agent execution: uses agent framework
- Exploit agent → Agent execution: uses agent framework (evidence: `src/agents/exploiter.py`)
- Exploit critic → Agent execution: uses agent framework (evidence: `src/agents/exploitCritic.py`)
- Sanity checks → Agent execution: uses agent framework (evidence: `src/agents/sanityGuy.py`)
- Agent execution → Model access: calls model API (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Agent execution → Model registry: selects model (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Agent execution → Output parsing: parses responses (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Agent execution → Agent tools: dispatches tools (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Agent execution → Persistent objects: persists objects (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Agent execution → Runtime callbacks: uses callbacks (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Plan execution → Agent execution: extends execution (evidence: `src/agentlib/agentlib/lib/agents/planning.py`)
- Plan execution → Agent review: requests review (evidence: `src/agentlib/agentlib/lib/agents/planning.py`)
- Output parsing → Code handling: extracts code (evidence: `src/agentlib/agentlib/lib/common/parsers.py`)
- Repository builder → Tool collection: uses tools
- Tool collection → Shell operations: includes commands (evidence: `src/toolbox/tools.py`)
- Engineer → VM execution: runs in VM (evidence: `README.md`)
- VM execution → QEMU utilities: manages VM (evidence: `vm_library/run_cve.py`)
- VM execution → SSH utilities: connects by SSH (evidence: `vm_library/run_cve.py`)
- Snapshot runs → QEMU utilities: manages snapshots (evidence: `vm_library/run_cve_with_snaps.py`)
- Snapshot runs → SSH utilities: connects by SSH (evidence: `vm_library/run_cve_with_snaps.py`)
- Engineer → Run visualizer: opens visualizer (evidence: `README.md`)
- Run visualizer → Visualizer UI: serves interface (evidence: `README.md`)
- Visualizer UI → Run data loader: loads run (evidence: `visualizer/ui.js`)
- Run data loader → Log parsing: parses logs (evidence: `visualizer/data-loader.js`)
- Agent execution → Agent console: records activity (evidence: `src/agentlib/agentlib/lib/agents/agent.py`)
- Agent console → LLM records: stores records (evidence: `src/agentlib/agentlib/lib/web_console.py`)
