USBArmyKnife turns cheap ESP32-S3 dongles into a programmable close-access platform combining DuckyScript HID, mass storage emulation and WiFi tooling for authorized penetration testers.
| Tool | i-am-shodan/USBArmyKnife — ESP32-S3 based close-access attack platform for penetration testers and red teamers |
| Category | Physical / close-access red teaming hardware and firmware, written in C++ |
| Primary Use | Composing DuckyScript payloads that combine USB HID, mass storage, USB network emulation and WiFi/BT capabilities on a concealable dongle during authorized engagements |
| Safe Use | Intended solely for penetration testers and red teamers operating under written authorization on systems they own or are contracted to assess, and for defenders studying close-access tradecraft |
| Telemetry Note | Defenders can observe its footprint via unusual USB device descriptor changes (HID plus mass storage plus NIC composite devices), rogue EvilAP beacon activity, deauth bursts, and unexpected USB serial devices; the README itself notes serial-based egress is deliberately quiet, making USB device inventory and endpoint USB logging the key detection surfaces |
USBArmyKnife is an open-source close-access platform that runs on inexpensive ESP32-S3 hardware and stitches together several traditionally separate physical attack disciplines into one concealable dongle. Written in C++ and carrying nearly three thousand stars plus an MIT license, the project frames itself explicitly as a tool for penetration testers and red teamers. Its core thesis is that no single USB attack primitive — keystroke injection, network spoofing, storage smuggling — is sufficient on its own to meet realistic engagement objectives, so the value comes from orchestrating them together on hardware cheap enough that losing a unit is operationally acceptable.
The architecture, as the README describes it, centers on a fork of ESP32 Marauder for the wireless side and a DuckyScript-derived language for orchestration. That scripting layer has been augmented with custom commands that expose the full Marauder capability set, meaning one payload can interleave keystroke injection, device emulation and WiFi actions. This is a meaningful design decision: rather than asking operators to learn a new language, USBArmyKnife extends a syntax the BadUSB community already knows, lowering the barrier to composing multi-stage close-access scenarios.
Feature-wise the tool enumerates USB HID attacks with support for BadUSB and HID-and-run styles plus multiple keyboard layouts and languages, USB mass storage emulation covering both drive and CDROM device types, USB network device impersonation, and WiFi/Bluetooth attacks including EvilAP, deauthentication and packet capture. There is also a hot microphone capability that streams audio over WiFi on hardware that has a mic. Each of these is individually well understood by defenders; the analytical interest is in the composition, where one primitive covers the weakness of another.
Control and triggering are a major part of the pitch. The README lists plug-in-and-execute, leave-behind operation triggered over WiFi, timer-based execution, and a hardware button driven through a custom on-device UI. Everything is managed from a Bootstrap-based web interface that runs on the device itself, explicitly designed to be operable from a phone. For an operator running a physical access engagement, this matters: a dongle left in place becomes a remotely schedulable payload platform rather than a one-shot injection device.
The agent component is the most technically notable piece. Deployed over the serial interface, it enables command execution even when the target machine is locked, and the README claims serial-based egress is very hard to detect precisely because it never opens a network socket. The agent also embeds a tiny VNC server, letting the operator view the target screen through the web interface over the device's dedicated WiFi connection. From a defensive research standpoint, this is the capability worth studying: USB serial traffic as a covert channel largely bypasses network egress monitoring.
Hardware support is anchored on the LilyGo T-Dongle S3, a USB pen-drive-shaped ESP32-S3 board with 16MB of flash, a color LCD, a physical button and a hidden micro SD adapter inside the USB-A connector. The README emphasizes it is incredibly cheap, which aligns with the project's disposable-dongle philosophy. Also supported are the Evil Crow Cable Wind, an implanted USB cable with an ESP32-S3 hidden inside — notable because the firmware implements thermal throttling that disables WiFi on overheating — and the T-Watch S3 smartwatch platform, which brings a screen, mic, accelerometer, infrared and a LoRa transceiver into the supported surface.
The examples directory reads like a curriculum in close-access tradecraft, and it is useful to security teams as an awareness catalog. Covert Storage demonstrates a device that presents its full SD contents on first plug-in and a benign-looking drive on every subsequent attempt, a technique defenders should understand when relying on manual USB inspection. USB Ethernet PCAP turns the dongle into a network adapter and captures the first seconds of traffic. The VNC and serial-agent examples document the screen-viewing and locked-machine execution flows described above, while Simple UI shows how hardware buttons and on-device screens can drive payload selection without a companion computer.
The README's problem statement is worth quoting analytically because it maps directly onto defensive gaps. It observes that HID attacks require a logged-on machine, network impersonation attacks like those in the PoisonTap family require awkward hardware and offline cracking workflows, and post-exploitation egress is constrained when anything opening a socket gets submitted to VirusTotal. USBArmyKnife exists to chain primitives so each compensates for another's limitation. Understanding that chaining logic is exactly what purple teams should be tabletop-ing.
For defenders, the telemetry angles are concrete even if the tool tries to minimize them. Composite USB devices that flip between HID, mass storage and NIC descriptors are anomalous and should alert in any endpoint USB monitoring. The EvilAP and deauth features inherit Marauder's detectable RF signatures. The serial-agent egress, while quiet on the network, still manifests as a new USB serial device on the host, so device inventory and change detection on USB classes remain the strongest compensating controls. The linux_panic example — a malformed filesystem that crashes automounting Linux hosts — is also a reminder that USB storage attach handling should be hardened.
The project is actively developed, with PlatformIO and .NET CI workflows visible in the badges, and the README teases a substantial v2: a multilingual web UI with a browser-embedded VNC viewer, a new UAK scripting engine with DuckyScript v3 compatibility plus full string and return-code support, a cross-platform agent for Windows, Linux and macOS with live VNC and microphone capture, USB 2.0 throughput with read-only and read-write containers, and an MCP server with a script validator so AI assistants can author and verify payloads before deployment. The original dongle hardware reportedly cannot run v2, signaling a hardware refresh alongside the software rewrite.
In terms of positioning, USBArmyKnife occupies the space between consumer BadUSB tools like the USB Rubber Ducky and much more expensive commercial close-access platforms. Its distinguishing traits are the phone-managed web interface, the serial agent's locked-machine capability, the fusion with ESP32 Marauder, and hardware cheap enough to treat as expendable. For authorized red teams it compresses a bag of separate gadgets into one programmable stick; for blue teams it is a well-documented catalog of what close-access attacks look like when they stop being one-trick devices. Both audiences benefit from reading its README carefully.
i-am-shodan/USBArmyKnife.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.