USB Army Knife: a DuckyScript-driven USB attack dongle for red teams

The gap USB Army Knife is trying to fill in physical access work

The README opens with a blunt argument: single-purpose USB attacks are not enough on their own. A BadUSB keyboard payload needs a logged-in session. A network impersonation attack such as PoisonTap can yield a password hash but then leaves you needing somewhere to send it for offline cracking. And once you are on a host, anything that opens a socket risks being flagged. The author's answer is one cheap, concealable dongle that chains these techniques so the weakness of one becomes the transport for another.

The intended audience is narrow and stated plainly: penetration testers and red teamers doing close access. The README lists the scenarios it was built for, including becoming a USB Ethernet adapter, capturing the interface and egressing the PCAP over WiFi, presenting a covert storage device, deauthenticating a WiFi network and mailing the captured renegotiation to yourself, self-destructing a payload, and driving external hardware such as motion sensors. If your work does not involve a device you can physically plug into a target, most of this project is irrelevant to you.

One ESP32-S3 dongle, several USB personalities, and a forked Marauder

The device is an ESP32-S3 dongle, and the repository layout reflects a firmware project rather than an application: src/, include/, lib/, data/, ui/ and a platformio.ini at the top level, with extra_scripts.py alongside it. The attack surface is implemented as a set of USB personalities the firmware can present to the host. According to the README these include USB HID (BadUSB style keyboard injection using DuckyScript), a USB mass storage device that can appear as either a drive or a CDROM, and a USB network device. WiFi and Bluetooth attacks come from a forked version of ESP32 Marauder, which the README credits directly.

The control layer is a web interface. The README describes a Bootstrap interface managed from a phone, and the ui/ directory in the repository is consistent with that. Payloads are written in a Ducky-like language that the README says has been augmented with custom commands and with the Marauder capabilities. The examples/ directory is where the real documentation lives: covertstorage, evilap, hotmic, install_agent_and_run_command, led, linux_panic, malicious_ethernet_adapter, mount_whole_disk_and_run_command, multiple_keyboard_layouts, progressbar, rickroll, self_destruct, simple_ui, usb_ethernet_pcap, vnc, watch, wifi_connect_to_existing_ap and wifi_deauth_and_crypt_capture. There is also an agent component, referenced by the install_agent_and_run_command and vnc examples, which the README says allows command execution even when the machine is locked and screen viewing over the device's WiFi connection. The README claims serial-interface egress is hard to detect; that is the author's assessment, not a measured result.

Building and flashing USB Army Knife with PlatformIO

The README does not contain a step-by-step install section. What it does provide is the repository structure: platformio.ini at the root, a PlatformIO CI badge in the badge row, and a .NET workflow badge, which together indicate that the firmware is built with PlatformIO and that some tooling is written in .NET. The examples/ directory is the practical starting point, since each subdirectory is a self-contained scenario.

The README gives no build commands, so there is nothing to quote verbatim here. What can be said from the repository layout is that platformio.ini at the root is the file that defines the build environments, and it is the first thing to open. The README does not name the target board, the environment names, or a flashing procedure, so any command you run has to come from that file rather than from the documentation.

The same applies to the web interface assets in ui/ and the filesystem content in data/. The README does not describe how those are deployed to the device, so treat the PlatformIO project files as the source of truth. Once the firmware is running, the README says attacks are deployed and managed through the Bootstrap web interface, reachable from a phone. The practical first exercise is the rickroll example, which the README links to a video walkthrough, or simple_ui if you want to see the interface layer without a payload that touches the host.

Where USB Army Knife is the wrong tool

The README is unusually candid about the project's own trajectory, and that candour is the main limitation. It states that after two years of development on v1, v2 is planned as a full red-team platform, and that "the dongle that started this project won't be able to handle the newer v2 features." Anyone buying hardware today on the assumption that it will run the v2 feature set should read that sentence twice. The v2 announcement also describes a new web UI, a new UAK scripting engine, a cross-platform agent for Windows, Linux and macOS, and USB 2.0 throughput, none of which exist in the current tree as far as the repository shows.

There are operational constraints too. The device presents itself as USB hardware, so it depends on physical access and on the target accepting the class of device you emulate. The agent-based capabilities, including command execution on a locked machine and screen viewing, require deploying an agent first, which is a separate step from plugging in the dongle. The README's claim that serial-interface egress is "incredibly hard to detect" is an assertion about detection difficulty, not a result from a controlled test, and it should be treated as a hypothesis to validate in your own environment. Finally, this is firmware for a specific board family. If you want a general-purpose USB attack platform with a large, versioned payload library and no hardware dependency, this is not that.

USB Army Knife compared with a plain DuckyScript-only device

The obvious alternative is a single-purpose HID injection device, the classic Rubber Ducky style tool that runs DuckyScript and nothing else. The difference in approach is architectural rather than cosmetic. A HID-only device is a keyboard to the host and stops there; USB Army Knife changes what it presents to the host at runtime, so the same stick can be a keyboard, a mass storage device or a USB network adapter, and it can move captured data off the device over its own WiFi link instead of relying on the host's network stack.

That flexibility has a cost. A HID-only device has a small, well-understood failure surface: if the target accepts keyboards, the payload runs. USB Army Knife carries an ESP32-S3 firmware image, a web interface served from the device, and a forked Marauder component, so there are more places for a build to differ from the author's. The README also positions the tool as a platform for chaining attacks, which means payloads are more likely to be bespoke per engagement than copied from a shared library. If your work is mostly keyboard injection against known-good targets, the extra surface buys you little. If your work involves capturing traffic from a host that will not let you open a socket, the multi-personality design is the whole point.

Licence, maintenance and what an upgrade actually costs

The repository is MIT licensed, and the LICENSE file sits at the top level. MIT is permissive, so redistribution and modification in commercial engagements are broadly allowed, but two things need checking that the licence file alone does not settle. First, the project bundles a forked version of ESP32 Marauder, and the README credits that fork explicitly; the Marauder licence terms apply to that component independently of the MIT licence on the rest. Second, the .NET agent tooling visible in the workflow badges may carry its own terms. This is a note to read the licences, not legal advice.

On maintenance, the last push to the default branch was on 2026-09-04, and the most recent release listed is v1.1.5 from 2026-02-16, preceded by v1.1.4 and v1.1.3 earlier the same month. The repository is not archived. Those dates describe activity on the v1 line; the README's v2 announcement describes work that is planned rather than shipped, and the author states that current hardware will not support the v2 features. The practical upgrade cost is therefore hardware replacement, not a firmware flash, whenever v2 lands. Budget for that before standardising a team on the current dongle.

Editorial conclusion

Adopt USB Army Knife if you already run physical access engagements and are comfortable reading C++ and PlatformIO build files, because the payload language and the examples directory carry most of the value. Do not adopt it if you need a frozen feature set or a documented upgrade path: the README states that v2 is planned and that the current dongle will not handle the newer v2 features, so verify which hardware revision your build targets before buying anything. Verify first that your board matches the build environment in platformio.ini, and check the LICENSE file and the licence of the bundled ESP32 Marauder fork before shipping a device into a client environment.

Frequently asked questions

Official sources

1. i-am-shodan/USBArmyKnife on GitHub
2. Issues
3. License: MIT
4. README
5. Releases