How i-am-shodan/usbarmyknife works
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: main.cpp Firmware runtime · WebServer.cpp Web control · Extensions.h Script commands · Executer.cs Command executor
Components 27
Device firmware
- Firmware runtime
src/main.cpp - Capability base
src/USBArmyKnifeCapability.h - Payload execution
src/Attacks/Ducky/DuckyPayload.cpp - Script commands
src/Attacks/Ducky/Extensions.h - USB modes
src/Devices/USB/USBCore.cpp - Device storage
src/Devices/Storage/HardwareStorage.cpp - Wi-Fi device
src/Devices/WiFi/HardwareWiFi.cpp - Wi-Fi Bluetooth attacks
src/Attacks/Marauder/Marauder.cpp - Settings
src/Utilities/Settings.cpp - Logging
src/Debug/Logging.h - Hardware peripherals
src/Devices/Platform/BoardSupport.cpp - Motion sensor
src/AuxiliaryComponent/Sensors/Motion/LD2410/LD2410.cpp - Agent capability
src/Attacks/Agent/Agent.cpp - Marauder command engine
lib/ESP32Marauder/esp32_marauder/CommandLine.cpp - Wi-Fi scanning
lib/ESP32Marauder/esp32_marauder/WiFiScan.cpp
Control interfaces
- Web control
src/Comms/Web/WebServer.cpp
Serial agent
- USB serial
tools/Agent/SerialComms.cs - Agent launcher
tools/Agent/Program.cs - Command executor
tools/Agent/Executer.cs - Agent transport
tools/Agent/TransportStream.cs - Agent VNC server
tools/Agent/VNC/VNCServer.cs
VNC viewing
- VNC client UI
ui/vnc/app/ui.js - RFB protocol client
ui/vnc/core/rfb.js - Touch gestures
ui/vnc/core/input/gesturehandler.js
Other components
- Operator
- Web browser
- Target computer
Connections 28
- Firmware runtime → Capability base: uses lifecycle
src/main.cpp - Firmware runtime → Payload execution: starts runtime
src/main.cpp - Payload execution → Script commands: dispatches commands
- Script commands → Device storage: lists files
src/Attacks/Ducky/Extensions.h - Script commands → USB modes: controls USB
src/Attacks/Ducky/Extensions.h - Firmware runtime → Device storage: initializes and loops
src/main.cpp - Firmware runtime → Wi-Fi device: loops device
src/main.cpp - Firmware runtime → Hardware peripherals: initializes board
src/main.cpp - Firmware runtime → Wi-Fi Bluetooth attacks: initializes attack
src/main.cpp - Web control → Device storage: reports capacity
src/Comms/Web/WebServer.cpp - Web control → Wi-Fi Bluetooth attacks: runs command
src/Comms/Web/WebServer.cpp - Web control → Settings: updates settings
src/Comms/Web/WebServer.cpp - Web control → Agent capability: controls agent
- Web control → Operator: serves controls
README.md - Firmware runtime → Motion sensor: starts sensor
src/main.cpp - Motion sensor → Payload execution: reports activity
src/AuxiliaryComponent/Sensors/Motion/LD2410/LD2410.cpp - Agent launcher → USB serial: starts connection
tools/Agent/Program.cs - USB serial → Agent capability: communicates over USB
README.md - Agent launcher → Command executor: runs executor
tools/Agent/Program.cs - Command executor → Agent transport: uses transport
tools/Agent/Executer.cs - Command executor → Agent VNC server: starts VNC
tools/Agent/Executer.cs - Web browser → VNC client UI: opens viewer
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
README.md - Agent VNC server → Target computer: captures screen
README.md - Wi-Fi Bluetooth attacks → Marauder command engine: runs commands
- Marauder command engine → Wi-Fi scanning: performs scans