____ _ _ _ _ ____ ____ / ___| |__ ___ ___| |_| | | / ___|| __ ) | | _| '_ \ / _ \/ __| __| | | \___ \| _ \ | |_| | | | | (_) \__ \ |_| |_| |___) | |_) | \____|_| |_|\___/|___/\__|\___/|____/|____/
Experimental USB Security Testing Framework
-blue?style=flat-square){kind=icon}
Features • Quick Start • Hardware • Deployment Modes • Documentation
GhostUSB is an experimental USB-based security testing framework that operates through keyboard emulation. It combines BadUSB capabilities — AMSI bypass, CVE exploitation, payload delivery — with WiFi C2 communication, all running on commodity ESP32 hardware.
The firmware implements a non-blocking state machine that handles USB HID keyboard emulation via the ESP32 native USB stack (TinyUSB), target OS detection through enumeration timing heuristics, and configurable deployment modes that range from quick one-shot payload drops to full-chain exploitation with C2 persistence.
Emulates a keyboard over the ESP32 native USB stack. Configurable typing speed with human-like random delays between keystrokes, stealth mode for extended random pauses, and fast mode for minimal inter-key delay. Supports multi-modifier key combinations (Win+R, Ctrl+Alt+T, Ctrl+Shift+Esc).
Four AMSI bypass techniques delivered as PowerShell payloads via USB HID:
| Layer | Technique | Vector |
|---|---|---|
| 1 | Reflection | amsiInitFailed via .NET reflection |
| 2 | Memory Patch | AmsiScanBuffer prologue overwrite |
| 3 | VEH HWBP | Hardware breakpoint + Vectored Exception Handler |
| 4 | Write Raid | CLR writable entry overwrite |
Fallback chain: Write Raid -> Reflection.
Onboard WER ALPC LPE payload targeting SvcElevatedLaunch in wersvc.dll. The exploit creates a shared memory section with a malicious command line, connects to the WER ALPC port, and sends method 0x0D to launch WerFault.exe as SYSTEM. Non-blocking executor with 30-second compile timeout.
| ID | Payload | Target |
|---|---|---|
| 0 | Reverse TCP shell | Windows |
| 1 | Reverse HTTPS shell | Windows |
| 2 | Bind TCP shell | Windows |
| 3 | MSF stager | Windows |
| 4 | Keylogger | Windows |
| 5 | Screenshot capture | Windows |
| 6 | WMI persistence | Windows |
| 7 | Reverse shell | Linux |
| 8 | Bind shell | Linux |
| 9 | Cron persistence | Linux |
| 10 | Cleanup | Windows |
| 11 | CIM persistence | Windows |
All payloads are delivered as USB HID keystrokes. C2 addresses are compile-time constants.
Encrypted beacon protocol over TCP using AES-256-GCM (mbedtls hardware-accelerated). Configurable beacon interval with jitter. STA mode with automatic AP fallback. Each beacon carries device identity, target OS info, and session status in JSON format, encrypted with per-device key derived from PSK + chip ID.
Target cleanup commands, Windows event log clearing via wevtutil, timestomping via PowerShell, and self-destruct mechanism with NVRAM flag and flash wipe on next boot.
# Install PlatformIO
pip install platformio
# Build firmware
cd firmware/esp32
pio run -e s2mini
# Flash to device
pio run -e s2mini -t uploadcd c2_server/python
pip install -r ../requirements.txt
python c2_server.pyMetasploit handler and auxiliary modules are available in c2_server/msf/.
| Board | Flash | PSRAM | Cores | BLE |
|---|---|---|---|---|
| ESP32-S2 Mini | 4MB | 2MB | 1 (LX7) | No |
| ESP32-S3 SuperMini | 4-8MB | 2-8MB | 2 (LX7) | Yes |
USB HID uses the native USB controller (GPIO 19/20, no external wiring). GPIO0 serves as the safety arming button.
| Mode | HID | AMSI | CVE | C2 | Description |
|---|---|---|---|---|---|
| Quick Strike | Yes | Yes | No | No | One-shot payload delivery |
| Full Chain | Yes | Yes | Yes | Yes | Full compromise chain |
| Silent Drop | No | No | No | Yes | C2 implant only |
| Dead Drop | Yes | No | No | Yes | Timed delayed execution |
| MSF Relay | Yes | Yes | No | Yes | MSF stager delivery |
Key settings in firmware/esp32/src/config.h:
| Setting | Default | Description |
|---|---|---|
DEFAULT_MODE |
MODE_FULL_CHAIN |
Boot deployment mode |
WIFI_SSID |
GhostNet | Target WiFi network |
C2_HOST |
192.168.1.50 | C2 server address |
C2_PORT_TCP |
4444 | C2 TCP port |
C2_PSK |
GhostUSB2026! | AES pre-shared key |
USB_VID |
0x046D | Spoofed USB vendor (Logitech) |
USB_PID |
0xC52B | Spoofed USB product |
SAFETY_LAB_MODE |
1 | Require button at boot |
payloads/encoders/ps_obfuscator.py— PowerShell obfuscation: string splitting, variable renaming, junk code injection, Base64 encoding.tools/build_flash.py— Build and flash helper for PlatformIO environments.
| File | Contents |
|---|---|
firmware/esp32/README.md |
Firmware build, configuration, payload reference |
docs/DESIGN.md |
Architecture, state machine, memory model |
docs/DEVELOPMENT.md |
Source layout, building, extending the firmware |
docs/SAFETY_NOTES.md |
Safety mechanisms and operational notes |
docs/CHANGELOG.md |
Version history and fix log |
MIT — Educational and authorized security research only. See LICENSE.