EvilDuck is a custom USB rubber ducky — a device that plugs into any computer and acts as a keyboard, executing pre-written payloads automatically. It's inspired by WiFiDuck by Spacehuhn, which pairs an ESP8266 for WiFi with an ATmega32U4 for USB HID. EvilDuck takes that concept and builds on it with each hardware revision.
This repo covers two generations of the design:
| Version | Chip(s) | WiFi | SD Card | Web Interface |
|---|---|---|---|---|
| EvilDuck SD | Arduino Micro (ATmega32U4) | ❌ | ✅ | ❌ |
| EvilDuck S3 | ESP32-S3 | ✅ | ✅ | ✅ |
The original version. Simple, standalone, and effective. Scripts are stored on an SD card and executed automatically when the device is powered. No WiFi, no web interface — just plug in, run.
- Keystroke Injection via Arduino Micro acting as a USB HID keyboard
- SD Card Payload Storage — scripts stored as
script.txton FAT16/32 - Hot-Swap Detection — detects SD card insertion while powered
- LED Status Indicators:
- Blinks every 1s → no SD card detected
- Blinks every 2s → no script file found
- Blinks on each keystroke during execution
- Rubber Ducky-style scripting — supports
STRING,DELAY, and special keypresses
| Component | Detail |
|---|---|
| Microcontroller | Arduino Micro (ATmega32U4) |
| Storage | MicroSD card (FAT16/32) |
| Status LED | Connected to Pin 9 |
| SD Card Module | SPI interface |
| SD Card Pin | Arduino Pin |
|---|---|
| CS | 4 |
| MOSI | 11 |
| MISO | 12 |
| SCK | 13 |
LED: Anode → Pin 9, Cathode → GND
- Arduino IDE 1.8+
- Libraries:
SD,SPI,Keyboard
The second generation. Built around the ESP32-S3, which handles both USB HID and WiFi natively on a single chip — no second microcontroller needed. The result is a more compact, more capable, fully self-contained device.
It adds a browser-based control panel over WiFi, SD card support for expanded storage, an addressable RGB LED, and a full DuckScript interpreter — all while staying the same physical size.
- Single-chip design — ESP32-S3 replaces the ATmega32U4 + ESP8266 combo
- WiFi access point — browser-based control panel, no app required
- Addressable RGB LED — WS2812 (2020 package), fully color-controllable in software
- SD card support with expanded storage and USB mass storage mode
- Over-the-air firmware updates via the web interface
- DuckScript interpreter — executes scripts line by line as USB HID keystrokes
- Autorun — plug in and a chosen script starts automatically
- Stealth mode — adjusts timing and LED behavior
| Component | Detail |
|---|---|
| Microcontroller | ESP32-S3 |
| WiFi | Built-in (802.11 b/g/n) |
| USB | Native USB HID (no second MCU) |
| Storage | Internal SPIFFS + MicroSD |
| RGB LED | WS2812 (2020 package) |
| Voltage Regulator | LM1117 (5V → 3.3V) |
| Connector | USB Type-A |
Accessible over WiFi once the device is powered:
- Upload, edit, save, and delete scripts
- Trigger payloads remotely
- Live execution status (current script + line number)
- Execution log with warnings and errors
- Stop a running script mid-execution
- Send individual commands for quick testing
- Built-in script library (Windows, Linux, macOS, demos, advanced)
- Password-protected with optional hidden SSID
- Configurable network name, password, and channel
- Internal flash (SPIFFS) — persistent across reboots
- SD card — expanded storage, file transfer between internal and SD
- USB mass storage mode — drag and drop files directly
| Mode | Description |
|---|---|
| Keyboard only | Acts purely as HID keyboard |
| Storage only | Acts as USB mass storage |
| Combined | Both keyboard and storage |
| Disabled | Neither |
Full schematics for both versions are available in the /Schematic folder, and detailed build guides can be found on the project website.
Distributed under the MIT License. See LICENSE for details.
▶ Support me on Patreon: patreon.com/cifertech
CiferTech — @twitter — CiferTech@gmail.com
Project Link: https://github.com/cifertech/EvilDuck