# i-am-shodan/usbarmyknife architecture

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

- Interactive diagram: https://gitdiagram.com/i-am-shodan/usbarmyknife
- Repository: https://github.com/i-am-shodan/usbarmyknife

## Overview

USB Army Knife is an embedded physical-access and red-team platform, with firmware coordinating scripts, USB impersonation, Wi-Fi/Bluetooth capabilities, storage, and peripherals. The primary workflow is a user triggering a Ducky-style payload through the device or web interface; firmware executes its commands against device capabilities and can expose results through USB or the web UI. Separate branches cover the companion serial agent and browser VNC viewer. Links for subsystems described only by the README are documented links; unsampled implementation details are not inferred.

Main entry points: [`src/main.cpp`](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/main.cpp) (Firmware runtime), [`src/Comms/Web/WebServer.cpp`](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Comms/Web/WebServer.cpp) (Web control), [`src/Attacks/Ducky/Extensions.h`](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Ducky/Extensions.h) (Script commands), [`tools/Agent/Executer.cs`](https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/Executer.cs) (Command executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Device firmware"]
  node_main["Firmware runtime<br/>[main.cpp]"]
  node_capability["Capability base"]
  node_ducky["Payload execution<br/>[DuckyPayload.cpp]"]
  node_extensions["Script commands<br/>[Extensions.h]"]
  node_usb["USB modes<br/>[USBCore.cpp]"]
  node_storage[("Device storage")]
  node_wifi["Wi-Fi device<br/>[HardwareWiFi.cpp]"]
  node_marauder["Wi-Fi Bluetooth attacks<br/>[Marauder.cpp]"]
  node_settings["Settings<br/>[Settings.cpp]"]
  node_logging["Logging<br/>[Logging.h]"]
  node_peripherals["Hardware peripherals<br/>[BoardSupport.cpp]"]
  node_aux["Motion sensor<br/>[LD2410.cpp]"]
  node_agent_fw["Agent capability<br/>[Agent.cpp]"]
  node_marauder_lib["Marauder command engine<br/>[CommandLine.cpp]"]
  node_scan["Wi-Fi scanning<br/>[WiFiScan.cpp]"]
end

subgraph group_interface["Control interfaces"]
  node_web["Web control<br/>[WebServer.cpp]"]
end

subgraph group_agent["Serial agent"]
  node_serial["USB serial<br/>[SerialComms.cs]"]
  node_agent_program["Agent launcher<br/>[Program.cs]"]
  node_executer["Command executor<br/>[Executer.cs]"]
  node_transport["Agent transport<br/>[TransportStream.cs]"]
  node_vncserver["Agent VNC server<br/>[VNCServer.cs]"]
end

subgraph group_vnc["VNC viewing"]
  node_vncui["VNC client UI<br/>[ui.js]"]
  node_rfb["RFB protocol client<br/>[rfb.js]"]
  node_gestures["Touch gestures<br/>[gesturehandler.js]"]
end

node_user(("Operator"))
node_browser(("Web browser"))
node_victim(("Target computer"))

node_main -->|"uses lifecycle"| node_capability
node_main -->|"starts runtime"| node_ducky
node_ducky -.->|"dispatches commands"| node_extensions
node_extensions -->|"lists files"| node_storage
node_extensions -->|"controls USB"| node_usb
node_main -->|"initializes and loops"| node_storage
node_main -->|"loops device"| node_wifi
node_main -->|"initializes board"| node_peripherals
node_main -->|"initializes attack"| node_marauder
node_web -->|"reports capacity"| node_storage
node_web -->|"runs command"| node_marauder
node_web -->|"updates settings"| node_settings
node_web -.->|"controls agent"| node_agent_fw
node_web -.->|"serves controls"| node_user
node_main -->|"starts sensor"| node_aux
node_aux -->|"reports activity"| node_ducky
node_agent_program -->|"starts connection"| node_serial
node_serial -.->|"communicates over USB"| node_agent_fw
node_agent_program -->|"runs executor"| node_executer
node_executer -->|"uses transport"| node_transport
node_executer -->|"starts VNC"| node_vncserver
node_browser -.->|"opens viewer"| node_vncui
node_vncui -.->|"uses client"| node_rfb
node_vncui -.->|"handles touch"| node_gestures
node_rfb -.->|"connects to"| node_vncserver
node_vncserver -.->|"captures screen"| node_victim
node_marauder -.->|"runs commands"| node_marauder_lib
node_marauder_lib -.->|"performs scans"| node_scan

click node_main "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/main.cpp"
click node_capability "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/USBArmyKnifeCapability.h"
click node_ducky "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Ducky/DuckyPayload.cpp"
click node_extensions "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Ducky/Extensions.h"
click node_usb "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/USB/USBCore.cpp"
click node_storage "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/Storage/HardwareStorage.cpp"
click node_wifi "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/WiFi/HardwareWiFi.cpp"
click node_marauder "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Marauder/Marauder.cpp"
click node_web "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Comms/Web/WebServer.cpp"
click node_settings "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Utilities/Settings.cpp"
click node_logging "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Debug/Logging.h"
click node_peripherals "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/Platform/BoardSupport.cpp"
click node_aux "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/AuxiliaryComponent/Sensors/Motion/LD2410/LD2410.cpp"
click node_agent_fw "https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Agent/Agent.cpp"
click node_serial "https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/SerialComms.cs"
click node_agent_program "https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/Program.cs"
click node_executer "https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/Executer.cs"
click node_transport "https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/TransportStream.cs"
click node_vncserver "https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/VNC/VNCServer.cs"
click node_vncui "https://github.com/i-am-shodan/usbarmyknife/blob/master/ui/vnc/app/ui.js"
click node_rfb "https://github.com/i-am-shodan/usbarmyknife/blob/master/ui/vnc/core/rfb.js"
click node_gestures "https://github.com/i-am-shodan/usbarmyknife/blob/master/ui/vnc/core/input/gesturehandler.js"
click node_marauder_lib "https://github.com/i-am-shodan/usbarmyknife/blob/master/lib/ESP32Marauder/esp32_marauder/CommandLine.cpp"
click node_scan "https://github.com/i-am-shodan/usbarmyknife/blob/master/lib/ESP32Marauder/esp32_marauder/WiFiScan.cpp"

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_main,node_capability,node_ducky,node_extensions,node_usb,node_storage,node_wifi,node_marauder,node_settings,node_logging,node_peripherals,node_aux,node_agent_fw,node_marauder_lib,node_scan,node_browser toneBlue
class node_web toneAmber
class node_serial,node_agent_program,node_executer,node_transport,node_vncserver toneMint
class node_vncui,node_rfb,node_gestures toneRose
class node_user,node_victim toneIndigo
```

## Components

### Device firmware

- [Firmware runtime](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/main.cpp): `src/main.cpp`
- [Capability base](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/USBArmyKnifeCapability.h): `src/USBArmyKnifeCapability.h`
- [Payload execution](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Ducky/DuckyPayload.cpp): `src/Attacks/Ducky/DuckyPayload.cpp`
- [Script commands](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Ducky/Extensions.h): `src/Attacks/Ducky/Extensions.h`
- [USB modes](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/USB/USBCore.cpp): `src/Devices/USB/USBCore.cpp`
- [Device storage](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/Storage/HardwareStorage.cpp): `src/Devices/Storage/HardwareStorage.cpp`
- [Wi-Fi device](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/WiFi/HardwareWiFi.cpp): `src/Devices/WiFi/HardwareWiFi.cpp`
- [Wi-Fi Bluetooth attacks](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Marauder/Marauder.cpp): `src/Attacks/Marauder/Marauder.cpp`
- [Settings](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Utilities/Settings.cpp): `src/Utilities/Settings.cpp`
- [Logging](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Debug/Logging.h): `src/Debug/Logging.h`
- [Hardware peripherals](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Devices/Platform/BoardSupport.cpp): `src/Devices/Platform/BoardSupport.cpp`
- [Motion sensor](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/AuxiliaryComponent/Sensors/Motion/LD2410/LD2410.cpp): `src/AuxiliaryComponent/Sensors/Motion/LD2410/LD2410.cpp`
- [Agent capability](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Attacks/Agent/Agent.cpp): `src/Attacks/Agent/Agent.cpp`
- [Marauder command engine](https://github.com/i-am-shodan/usbarmyknife/blob/master/lib/ESP32Marauder/esp32_marauder/CommandLine.cpp): `lib/ESP32Marauder/esp32_marauder/CommandLine.cpp`
- [Wi-Fi scanning](https://github.com/i-am-shodan/usbarmyknife/blob/master/lib/ESP32Marauder/esp32_marauder/WiFiScan.cpp): `lib/ESP32Marauder/esp32_marauder/WiFiScan.cpp`

### Control interfaces

- [Web control](https://github.com/i-am-shodan/usbarmyknife/blob/master/src/Comms/Web/WebServer.cpp): `src/Comms/Web/WebServer.cpp`

### Serial agent

- [USB serial](https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/SerialComms.cs): `tools/Agent/SerialComms.cs`
- [Agent launcher](https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/Program.cs): `tools/Agent/Program.cs`
- [Command executor](https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/Executer.cs): `tools/Agent/Executer.cs`
- [Agent transport](https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/TransportStream.cs): `tools/Agent/TransportStream.cs`
- [Agent VNC server](https://github.com/i-am-shodan/usbarmyknife/blob/master/tools/Agent/VNC/VNCServer.cs): `tools/Agent/VNC/VNCServer.cs`

### VNC viewing

- [VNC client UI](https://github.com/i-am-shodan/usbarmyknife/blob/master/ui/vnc/app/ui.js): `ui/vnc/app/ui.js`
- [RFB protocol client](https://github.com/i-am-shodan/usbarmyknife/blob/master/ui/vnc/core/rfb.js): `ui/vnc/core/rfb.js`
- [Touch gestures](https://github.com/i-am-shodan/usbarmyknife/blob/master/ui/vnc/core/input/gesturehandler.js): `ui/vnc/core/input/gesturehandler.js`

### Other components

- **Operator**
- **Web browser**
- **Target computer**

## Connections

- Firmware runtime → Capability base: uses lifecycle (evidence: `src/main.cpp`)
- Firmware runtime → Payload execution: starts runtime (evidence: `src/main.cpp`)
- Payload execution → Script commands: dispatches commands
- Script commands → Device storage: lists files (evidence: `src/Attacks/Ducky/Extensions.h`)
- Script commands → USB modes: controls USB (evidence: `src/Attacks/Ducky/Extensions.h`)
- Firmware runtime → Device storage: initializes and loops (evidence: `src/main.cpp`)
- Firmware runtime → Wi-Fi device: loops device (evidence: `src/main.cpp`)
- Firmware runtime → Hardware peripherals: initializes board (evidence: `src/main.cpp`)
- Firmware runtime → Wi-Fi Bluetooth attacks: initializes attack (evidence: `src/main.cpp`)
- Web control → Device storage: reports capacity (evidence: `src/Comms/Web/WebServer.cpp`)
- Web control → Wi-Fi Bluetooth attacks: runs command (evidence: `src/Comms/Web/WebServer.cpp`)
- Web control → Settings: updates settings (evidence: `src/Comms/Web/WebServer.cpp`)
- Web control → Agent capability: controls agent
- Web control → Operator: serves controls (evidence: `README.md`)
- Firmware runtime → Motion sensor: starts sensor (evidence: `src/main.cpp`)
- Motion sensor → Payload execution: reports activity (evidence: `src/AuxiliaryComponent/Sensors/Motion/LD2410/LD2410.cpp`)
- Agent launcher → USB serial: starts connection (evidence: `tools/Agent/Program.cs`)
- USB serial → Agent capability: communicates over USB (evidence: `README.md`)
- Agent launcher → Command executor: runs executor (evidence: `tools/Agent/Program.cs`)
- Command executor → Agent transport: uses transport (evidence: `tools/Agent/Executer.cs`)
- Command executor → Agent VNC server: starts VNC (evidence: `tools/Agent/Executer.cs`)
- Web browser → VNC client UI: opens viewer (evidence: `README.md`)
- VNC client UI → RFB protocol client: uses client
- VNC client UI → Touch gestures: handles touch
- RFB protocol client → Agent VNC server: connects to (evidence: `README.md`)
- Agent VNC server → Target computer: captures screen (evidence: `README.md`)
- Wi-Fi Bluetooth attacks → Marauder command engine: runs commands
- Marauder command engine → Wi-Fi scanning: performs scans
