USBArmyKnife - USB Army Knife – the ultimate close access tool fo

项目说明

<a href=" alt="License" src="
![PlatformIO CI]()
![.NET]()
<a href=" src=" alt="Twitter"></a>
![ko-fi]()
<a href=" target="_blank"><img src=" alt="Buy Me A Coffee" height="41" width="174"></a>

> ## 🚀 USB Army Knife v2 is steeping — and its going to be a beast
>
> After two years of acti on v1, v2 is planned to turn the USB Army Knife into a full red-team platform in your pocket. A big announcement is coming this autumn but I still wanted to tease:
>
> - Brand-new web UI — smaller, faster, sleeker & multilingual, with a built-in to watch and drive the target straight from your browser. This won't be tied to any web tools like today so anyone can change it.
> - New UAK Scripting engine — DuckyScript , but goes way beyond what DuckyScript 3 can do with full string and return code support. This makes writing neater and more robust payloads much easier.
> - New cross-platform Agent for Windows, Linux *and* macOS — live VNC, microphone capture and maybe e access over the USB serial link.
> - Many new capabilities — Brand new functionality across networking, files, capti, bluetooth and many more! USB 2.0 for faster throughput with read-only and read-write containers!
> - AI-ready — an MCP server with a real UAK script so your AIs can write and check payloads before they hit the device.
>
> A ton of this work has now been completed and I've been busy working with hardware that will be powerful enough to run this new platform. What's clear is that the dongle that started this project won't be able to handle the newer V2 features. But I for one love
its form factor.
> What I'm sure of is that v2 will take UAK make one tiny stick that scripts itself, picks its target, controls the device, hears the room, and maybe can even talk to its siblings...

USB Army Knife

<di="center">
Introducing the USB Army Knife – the ultimate tool for penetration testers and red teamers.
<img src="./docs/images/t-dongle-s3-side.png" width="400px"</img>
</div>

Compact and , this device packs a punch with its extensi, including USB HID attacks, mass storage emulation, network device impersonation and WiFi/Bluetooth exploits (thanks to our forked of ESP32 Marauder).

Complete control over how and when your payloads are run. Plug in and execute, lea 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 screen over the devices' dedicated WiFi connection.

Equip yourself with the USB Army Knife and elevate your local access toolkit to the next level.

Testimonials

*"Your device is evil. You are doing evil."* - Mr. Peoples via X

Intro

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 respecti 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 e 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 's screen over WiFi? USB Army Knife.
* Want to record what your is saying? USB Army Knife.

Video

This video shows how the ultimate rick roll works

This video shows how the USB PCAP functionality and has a brief peak at the web interface

This video shows how to pull the machine once the agent has been installed

Features

This project implements a 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. Supports multiple keyboard layouts/languages.

Mass Storage Device: Emulate a USB mass storage device (USB drive and CDROM).

USB Network Device: Appear as a USB network device.

WiFi and Bluetooth Attacks: Utilize ESP32 Marauder for WiFi and Bluetooth attacks. Include EvilAP, Deauth and pcap.

Hot Mic: Plug in a USB device and stream audio over WiFi

Examples

| 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' dri. |
| 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 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 . Now the screen can be 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. |
| Evil USB CDROM/NIC | Pretend to be a USB NICs which requires a driver from a CDROM device that appears when you plug the NIC in. |
| Use different keyboard layouts | Automatically support different keyboard layouts without rewriting your payloads |

Supported Hardware

| Hardware | Supported | Purchase Links |
| ------------ | -------------- | -------------- |
| LilyGo T-Dongle S3 (Recommended)!screenshot | The LilyGo T-Dongle S3 is a USB pen dri ESP32-S3 de 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 of this device with and without the screen. Only the with the screen has been tested. | <ul><li>AliExpress</li><li>Amazon UK</li><li>Amazon US</li><li>eBay UK</li></ul>
| Evil Crow Cable Wind !screenshot | The Evil Crow Cable Wind is a malicious implanted USB cable with a ESP32-S3 hidden inside, it comes in a couple of different . One end can be used for active USB attacks whilst the other is intended to charge a device. Its unique design makes it one of the most covert USB Army Knife capable devices. For this reason the device doesn't have a screen, SD card or LEDs or a good hardware button (there is one inside that requires the use of a magnet). Instead of an SD card, flash memory is used to store files. NOTE Whilst it's possible to run a wireless access point on these devices the unit can get very hot. To counter this USB Army Knife supports thermal throttling and will turn the WiFi off if the device is o. To completely avoid this issue you should connected to an existing wireless network (that than host an access point) or disable WiFI, the device then does not o. This device has specific install instructions | <ul><li>USB-A to USB-C AliExpress</li> <li>USB-C to USB-C AliExpress</li> </ul>
| T-Watch S3 !screenshot | The T-Watch S3 is a smart watch platform with a a ton of hardware packed inside including screen, WiFi, real time clock, mic, accelerometer, infrared, haptic feedback and a LoRa transceiver. Much of this is already supported by the USB Army Knife platform. The watch crown acts as a button and there is a mini USB port for charging / HID attacks. As the watch is based on the ESP32-S3 chipset it can host a WiFi station as well as support a range of WiFi and Bluetooth attacks. Crucially it does not have an SD card slot and flash memory is used to store files. As such attack scripts and any results are limited to ~10MB. The flashing of this platform is a little more complex, check the Wiki for guidance on how to get your device up and running. This device has specific install instructions | <ul><li>with GPS AliExpress</li><li>Without GPS (smaller) recommended model AliExpress</li></ul>
| Wa ESP32-S3 1.47inch !screenshot | This device is similar in design, size and features to the LilyGo T-Dongle S3 and uses the same chipset. It is clearly a de 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. | <ul><li>AliExpress</li><li>eBay UK</li></ul>
| M5Stack AtomS3U !screenshot | This is an ESP32-S3 de 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. | <ul><li>AliExpress</li></ul>
| ESP32 Udisk !screenshot | 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 ad 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. | <ul><li>AliExpress</li><li>Amazon UK</li><li>Amazon US</li><li>eBay UK</li></ul>
| Pocket-Dongle-S3 !screenshot | Very similar looking device to the LilyGo T-Dongle S3 but with a different SD card and button form factor. The device doesn't have an LED or QWIIC interface slot. Internally this device uses the older SD card interface so expect slow transfer speeds. | <ul><li>AliExpress</li></ul>
| ESP32 Key !screenshot | Very similar to the ESP32 UDisk (please see that description for a list of things it can't do) 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. | <ul><li>AliExpress</li></ul>
| Wa !screenshot | ESP32-GEEK is a de board designed by Wa. It has USB-A, 1.14-inch LCD screen, an SD card and has external ports (SWD, UART and I2C), it doesn't have an LED. Hold down the button when you plug it in to get the device into flashing mode. This device has some SD card issues (compatibility and low speed). You may need to use 8GB partitions and try a few card brands to find something compatible (I found a Kingston 64gb card with a 9GB partition worked YMMV). | <ul><li>AliExpress</li><li>Amazon UK</li><li>Amazon US</li></ul>
| Wa !screenshot | RP2040-GEEK is a de board designed by Wa. 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 dri Zadig. Hold down the button when you plug it in to get the device into flashing mode. | <ul><li>AliExpress</li><li>Amazon UK</li><li>Amazon US</li></ul>

Getting Started

Firstly please check the wiki for a step by step guide and all manner of advice for getting started.

Installation

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 Studio Code (more powerful))

Usage

1. Connect the USB dongle to your computer.
1. Connect to the WiFi access point (iPhone14) with the password of 'password'
1. Access the web interface () by na to the URL with your browser.
1. Ensure the web interface has correctly loaded. You should see thr currently running status and uptime. If not refresh the page.
1. 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 files.*
*RP2040 devices do not ha Maurader capability*

How to get help

* Questions about DuckyScript?
* DuckyScript quick reference
* The USB Army Knife command reference
* Problem getting started?
* Check out the examples
* The discussions pages
* Found a bug?
* Create an issue

Future plans

USB Host Mode / Mobile device support

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 ha 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

Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

Contact

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:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Inspired by BadUSB projects and the ESP32 Marauder project.

Star History

![Star History Chart]()

项目信息

开发语言：C++

Star 数：2939

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕USB Army Knife – the ultimate close access tool for penetration testers and red teamers.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。