EvilDuck

       

📖 About the Project

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:

🦆 EvilDuck SD

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.

Features

• Keystroke Injection via Arduino Micro acting as a USB HID keyboard
• SD Card Payload Storage — scripts stored as script.txt on 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

Hardware

Wiring

LED: Anode → Pin 9, Cathode → GND

Software Requirements

• Arduino IDE 1.8+
• Libraries: SD, SPI, Keyboard

🦆 EvilDuck S3

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.

What’s New

• 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

Hardware

Web Interface Features

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

Storage Modes

• 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

Device Modes

🔌 Schematics

Full schematics for both versions are available in the /Schematic folder, and detailed build guides can be found on the project website.

📄 License

Distributed under the MIT License. See LICENSE for details.

🤝 Contact

▶ Support me on Patreon: patreon.com/cifertech

CiferTech — @twitter — [email protected]

Project Link: https://github.com/cifertech/EvilDuck