Compact and versatile, this device packs a punch with its extensive capabilities, including USB HID attacks, mass storage emulation, network device impersonation and WiFi/Bluetooth exploits (thanks to our forked version of ESP32 Marauder).
Complete control over how and when your payloads are run. Plug in and execute, leave behind and trigger over WiFi, run on a timer or build a Hollywood-esq UI. Manage and deploy your attacks effortlessly using just a phone using a user-friendly Bootstrap web interface.
Want more? Deploy the agent and execute commands even when the machine is locked. Working over the serial interface egress is incredibly hard to detect. You can even view the victims screen over the devices' dedicated WiFi connection.
Equip yourself with the USB Army Knife and elevate your local access toolkit to the next level.
"Your device is evil. You are doing evil." - Mr. Peoples via X
There is a problem with physical access/USB attacks today. On their own, each attack doesn't provide enough of a solution to meet most objectives.
- USB keyboard attacks (Ducky, HID&Run) require a logged on machine and even the best tools don’t provide a solution to this.
- Networking attacks (poison tap and alike) might get you a password hash but often require something complex hanging out of an Ethernet port to get this back for offline cracking.
- When you get on a box, what options do you still have for exfiltrating data when anything that opens a socket is getting sent to VT.
What was needed is a physical access platform that enables a suitable rogue to take the best bits of each attack and workaround their respective problems with another attack. Ideally this platform would be so cheap and covert that losing one wouldn't be an issue.
This is why I decided to create the USB Army Knife.
- Want to become a USB Ethernet adapter PCAP the interface and egress it over WiFI? USB Army Knife.
- Want to wrap your attacks in custom UI or just show a Hollywood interface when your attack has worked? USB Army Knife
- Want a covert storage device? USB Army Knife
- Want to deauth everyone on the WiFi, PCAP the renegotiation and email this to yourself when the machine has been left unlocked for offline cracking? USB Army Knife
- Want your attack to destroy itself when it’s been found? USB Army Knife
- What to connect to other bits of hardware, motion sensors and alike? USB Army Knife.
- Want to view what’s on the victim's screen over WiFi? USB Army Knife.
- Want to record what your victim is saying? USB Army Knife.
This video shows how the ultimate rick roll works
rickroll.mp4
This video shows how the USB PCAP functionality and has a brief peak at the web interface
USBPcapExample.mp4
This video shows how to pull the victims machine once the agent has been installed
VNCExample.mp4
This project implements a variety of attacks based around an easily concealable USB/WiFi/BT dongle. The attacks include sending BadUSB (USB HID commands using DuckyScript), appearing as mass storage devices, appearing as USB network devices, and performing WiFi and Bluetooth attacks with ESP32 Marauder. Attacks are deployed using a Ducky-like language you probably already know and love. This language has been agumented with a raft of custom commands and even the entire ESP32 Marauder capability (improved). Attacks include:
- USB HID Attacks: Send custom HID commands using DuckyScript, supports BadUSB & USB HID and run style attacks.
- Mass Storage Device: Emulate a USB mass storage device.
- USB Network Device: Appear as a USB network device.
- WiFi and Bluetooth Attacks: Utilize ESP32 Marauder for WiFi and Bluetooth attacks.
- Hot Mic: Plug in a USB device and stream audio over WiFi
| Name | Description |
|---|---|
| Covert Storage | Example showing how to masquerade as two different USB mass storage devices. The first time the device is plugged in the devices appears with the full contents of the micro SD card. In all subsequence attempts a different 'benign' drive appears. |
| Progress Bar | Images are displayed on the devices LCD screen showing a progress bar. Great for those Hollywood style attacks or if you want a visual indicator to show an attack has deployed. |
| Ultimate RickRoll | Inject keystrokes to display the famous rickroll video but also uses ESP32 Marauder to blast the lyrics over WiFi. |
| USB Ethernet PCAP | Turns the device into a USB network adapter and collects a PCAP of the first few seconds of network traffic. |
| Deploy the serial agent | Deploys the agent if it isn't already installed and sends commands over the serial port. Command output can be seen in the web interface |
| Pull the screen | Deploys the agent, the agent includes a tiny VNC server. Now the screen can be viewed via the web interface |
| Simple UI | A simple yet powerful UI to select scripts/images and run these using the hardware button. Shows how you can build complex UI interactions simply. |
| Stream Mic audio over WiFi | The M5Stack AtomS3U has a microphone that you can stream over WiFi. |
| Instantly crash Linux boxes | Deploy a bad filesystem which cause Linux machines which automount to panic. |
| Hardware | Supported | Purchase Links |
|---|---|---|
LilyGo T-Dongle S3 (Recommended) |
The LilyGo T-Dongle S3 is a USB pen drive shaped ESP32-S3 development board. It features a colour LCD screen, physical button, hidden/covert micro SD card adapter (inside the USB-A connector) as well as a SPI adapter. It has 16MB of flash. It is based on the ESP32-S3 chipset which enables it to host a WiFi station as well as support a range of WiFi and Bluetooth attacks. It is incredibly cheap! There are two versions of this device with and without the screen. Only the version with the screen has been tested. | |
Waveshare ESP32-S3 1.47inch  |
This device is similar in design, size and features to the LilyGo T-Dongle S3 and uses the same chipset. It is clearly a dev board as it doesn't come with a case and has exposed circuitry on the underside. Where this device betters the T-Dongle S3 is that it has a very large high quality screen and 8MB of additional RAM. | |
M5Stack AtomS3U  |
This is an ESP32-S3 development board with two external interface at the rear. It doesn't feature a screen or an SD card, but does have an LED and a button. Instead of an SD card the flash memory is used to store files. Unusually it also contains a digital microphone and IR LED that are not currently supported. To put the device in boot mode hold RESET (the button on the side of the device) until a green LED comes on. | |
ESP32 Udisk  |
The most basic device that can run the USB Army Knife code is a ESP32-S2 chip connected to a USB port. Often you can find these sold in a very similar enclosures to the T-Dongle S3 and tend to advertised on sites like AliExpress as Playstation 4 jailbreaks under the name 'USB Dongle Udisk for P4'. These devices lack RAM, a screen, SD card, Bluetooth, LEDs and a good hardware button. Instead of an SD card, flash memory is used to store tiny files. These devices are incredibly cheap and are often good at running HID+WiFi payloads (like the rick roll). Warning They are too underpowered to run the webserver. When buying these beware that they can often be confused with a very similar looking device that includes a CH343P chipset and no reset button. Make sure the device you buy has a button that can be pushed with a paperclip. Ensure you flash this device with the Generic-ESP32-S2 configuration. | |
ESP32 Key  |
Very similar to the ESP32 UDisk this is an ESP32-S2 on a circuit board. It is probably the cheapest device that can just about run USB Army Knife and has a price point to match. You'll need to hold down the button when you plug it in to get the device into flashing mode. Ensure you flash this device with the Generic-ESP32-S2 configuration. | |
Waveshare-RP2040-GEEK  |
RP2040-GEEK is a development board designed by Waveshare. It has USB-A, 1.14-inch LCD screen, an SD card and has external ports (SWD, UART and I2C). This board does not run the ESP32 chipset. USB ethernet (NCM) mode are whole disk SD usage are both currently unsupported. ESP32 Maurader cannot work on this device! On Windows you may also need to set this device to use a WinUSB driver using Zadig. Hold down the button when you plug it in to get the device into flashing mode. |
There are two options for getting the USB Army Knife firmware onto your device:
- Flashing pre-built firmware using your web browser (easiest route)
- Building and flashing the source using Visual Studio Code (more powerful)
- Connect the USB dongle to your computer.
- Connect to the WiFi access point (iPhone14) with the password of 'password'
- Access the web interface (http://4.3.2.1:8080) by navigating to the URL with your browser.
- Ensure the web interface has correctly loaded. You should see thr currently running status and uptime. If not refresh the page.
- Use the web interface to create and manage your attacks using DuckyScript.
ESP-S2 based devices have WiFi support but do not have a web interface. Attacks are managed via DuckyScript files. RP2040 devices do not have ESP32 Maurader capability
There is no reason the USB Army Knife can't also operate in USB host mode. That is the same mode a computer works in. In this way the USB Army Knife can issue commands as if it was a computer. With most smart phones supporting PTP (picture transfer protocol) this means you could in theory plug in a USB Army Knife (with a USB adapter) into a phone and have it pull the photos off.
Espressif have documentation for USB host mode and also example code. They do not have an example for the PTP protocol. You can collect a PCAP of your phone using PTP using USB PCAP there is even a WireShark dissector
Contributions are welcome! Please fork the repository and submit a pull request.
If you have any questions or suggestions, feel free to reach out to us:
- Raise an issue on the repository: GitHub Repository
- Connect with us on Twitter: @therealshodan
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by various BadUSB projects and the ESP32 Marauder project.
