# lab-boy-toy/usb-vm-defender- architecture

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

- Interactive diagram: https://gitdiagram.com/lab-boy-toy/usb-vm-defender-
- Repository: https://github.com/lab-boy-toy/usb-vm-defender-

## Overview

USB Defender detects USB arrivals on Windows, sends device details to its Python security process, and applies a whitelist and sandbox-scanning workflow before allowing or denying the device. The Python process manages the VirtualBox USB-Sandbox, read-only mounting and scanning, and returns a decision to the detector. Evidence is partial: the Python source excerpt omits implementation spans, so the documented workflow supports some subsystem links that are not directly visible as calls.

Main entry points: [`USBDefender-Python-FreshInstall-Debug-CURRENT.py`](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py) (Security coordinator), [`usbDetectorLayer/usbDetectorLayer/transmitter.cpp`](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/transmitter.cpp) (TCP request and reply), [`usbDetectorLayer/usbDetectorLayer/main.cpp`](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/main.cpp) (Device event loop), [`usbDetectorLayer/usbDetectorLayer/usbproc.cpp`](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/usbproc.cpp) (USB identification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_windows["Windows Detection"]
  node_win_entry["Device event loop<br/>[main.cpp]"]
  node_device_probe["USB identification<br/>[usbproc.cpp]"]
  node_device_info["Device details<br/>[usbproc.h]"]
end

subgraph group_bridge["Decision Bridge"]
  node_tcp_bridge["TCP request and reply<br/>[transmitter.cpp]"]
  node_python_service["Security coordinator"]
end

subgraph group_security["Device Security"]
  node_whitelist[("Whitelist database")]
  node_device_gate["Device classification"]
  node_verdict["Allow or deny"]
end

subgraph group_sandbox["Sandbox Operations"]
  node_vm_control["VM lifecycle"]
  node_usb_capture["Virtual USB capture"]
  node_readonly_scan["Read-only scan"]
end

node_usb(("USB device"))
node_virtualbox["VirtualBox sandbox"]
node_ubuntu["Ubuntu guest"]
node_clamav["ClamAV scanner"]

node_usb -->|"triggers arrival"| node_win_entry
node_win_entry -.->|"dispatches events"| node_device_probe
node_device_probe -->|"produces details"| node_device_info
node_device_info -.->|"formats for transfer"| node_tcp_bridge
node_tcp_bridge -->|"sends on 5050"| node_python_service
node_python_service -->|"returns decision on 5000"| node_tcp_bridge
node_python_service -->|"checks and records"| node_whitelist
node_python_service -->|"classifies device"| node_device_gate
node_device_gate -->|"skips known devices"| node_whitelist
node_python_service -->|"starts and checks"| node_vm_control
node_python_service -->|"configures capture"| node_usb_capture
node_vm_control -->|"controls VM"| node_virtualbox
node_usb_capture -->|"sets USB filters"| node_virtualbox
node_python_service -->|"runs scan workflow"| node_readonly_scan
node_readonly_scan -->|"mounts read-only"| node_ubuntu
node_readonly_scan -.->|"scans device"| node_clamav
node_python_service -->|"decides outcome"| node_verdict
node_verdict -->|"stores clean device"| node_whitelist
node_verdict -->|"sends DENY"| node_tcp_bridge

click node_win_entry "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/main.cpp"
click node_device_probe "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/usbproc.cpp"
click node_device_info "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/usbproc.h"
click node_tcp_bridge "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/transmitter.cpp"
click node_python_service "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py"
click node_whitelist "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py"
click node_device_gate "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py"
click node_vm_control "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py"
click node_usb_capture "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py"
click node_readonly_scan "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py"
click node_verdict "https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.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_win_entry,node_device_probe,node_device_info toneBlue
class node_tcp_bridge,node_python_service toneAmber
class node_whitelist,node_device_gate,node_verdict toneMint
class node_vm_control,node_usb_capture,node_readonly_scan toneRose
class node_usb,node_virtualbox,node_ubuntu,node_clamav toneIndigo
```

## Components

### Windows Detection

- [Device event loop](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/main.cpp): `usbDetectorLayer/usbDetectorLayer/main.cpp`
- [USB identification](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/usbproc.cpp): `usbDetectorLayer/usbDetectorLayer/usbproc.cpp`
- [Device details](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/usbproc.h): `usbDetectorLayer/usbDetectorLayer/usbproc.h`

### Decision Bridge

- [TCP request and reply](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/usbDetectorLayer/usbDetectorLayer/transmitter.cpp): `usbDetectorLayer/usbDetectorLayer/transmitter.cpp`
- [Security coordinator](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`

### Device Security

- [Whitelist database](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`
- [Device classification](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`
- [Allow or deny](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`

### Sandbox Operations

- [VM lifecycle](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`
- [Virtual USB capture](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`
- [Read-only scan](https://github.com/lab-boy-toy/usb-vm-defender-/blob/main/USBDefender-Python-FreshInstall-Debug-CURRENT.py): `USBDefender-Python-FreshInstall-Debug-CURRENT.py`

### Other components

- **USB device**
- **VirtualBox sandbox**
- **Ubuntu guest**
- **ClamAV scanner**

## Connections

- USB device → Device event loop: triggers arrival (evidence: `usbDetectorLayer/usbDetectorLayer/main.cpp`)
- Device event loop → USB identification: dispatches events
- USB identification → Device details: produces details (evidence: `usbDetectorLayer/usbDetectorLayer/usbproc.cpp`)
- Device details → TCP request and reply: formats for transfer (evidence: `usbDetectorLayer/usbDetectorLayer/transmitter.cpp`)
- TCP request and reply → Security coordinator: sends on 5050 (evidence: `usbDetectorLayer/usbDetectorLayer/transmitter.cpp`)
- Security coordinator → TCP request and reply: returns decision on 5000 (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Security coordinator → Whitelist database: checks and records (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Security coordinator → Device classification: classifies device (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Device classification → Whitelist database: skips known devices (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Security coordinator → VM lifecycle: starts and checks (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Security coordinator → Virtual USB capture: configures capture (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- VM lifecycle → VirtualBox sandbox: controls VM (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Virtual USB capture → VirtualBox sandbox: sets USB filters (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Security coordinator → Read-only scan: runs scan workflow (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Read-only scan → Ubuntu guest: mounts read-only (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Read-only scan → ClamAV scanner: scans device
- Security coordinator → Allow or deny: decides outcome (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Allow or deny → Whitelist database: stores clean device (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
- Allow or deny → TCP request and reply: sends DENY (evidence: `USBDefender-Python-FreshInstall-Debug-CURRENT.py`)
