ShinobiDuck

"With great power comes great responsibility"

ShinobiDuck is a highly capable, stealthy ESP32-based Bluetooth Low Energy (BLE) Rubber Ducky. It acts as a standard BLE HID Keyboard but provides a hidden Wi-Fi Web Console where you can deploy DuckyScript payloads, send live keystrokes, and manage target connections in real-time.

---

* Key Features

• Persistent Payload Storage: Utilizing the ESP32's LittleFS, you can upload, edit, and store multiple .duck, .yml, or .txt payloads directly on the device.
• Autorun Payload: Designate a specific payload to execute automatically the absolute second a target connects via BLE.
• Stealth Web Console: A fully responsive, dark-themed "Ninja" Web UI served directly from the ESP32.
• Dynamic Configuration: No need to recompile to change settings. Update the Wi-Fi AP Name, Wi-Fi Password, and BLE Device Name directly from the Settings tab in the Web UI.
• Target Intel & Management: View the MAC address of the connected target, monitor action queue depth in real-time, and forcefully disconnect (kick) the target right from the web panel.
• Live Keystroke Injection: Send individual keystrokes, key combos (e.g., CTRL + ALT + DEL), or entire strings of text on the fly.
• Preloaded Demos: Automatically generates example scripts on first boot to get you started quickly.

+ Hardware Requirements

• ESP32 Development Board (Default configuration is for esp32doit-devkit-v1, but easily adaptable to others).

> Installation & Flashing

This project is built using PlatformIO.

Because ShinobiDuck uses the ESP32's flash memory to store the Web UI and payloads, you must flash both the firmware and the filesystem.

1. Clone the repository and open it in VSCode (with the PlatformIO extension installed) or use the PlatformIO CLI.
2. Flash the Firmware (C++ code):

   pio run -t upload

3. Flash the Filesystem (Web UI & Storage):

   pio run -t uploadfs

> Usage Guide

1. Power On: Provide power to your ESP32.
2. Connect to Web Console:
   • Connect your phone or laptop to the Wi-Fi Access Point.
   • Default SSID: Shinobi-AP
   • Default Password: keyboard123
   • Open a web browser and navigate to http://192.168.4.1
3. Deploy the Ducky:
   • On the target device, turn on Bluetooth and pair with ShinobiDuck.
   • Once connected, the Web Console will update to show "TARGET CONNECTED" along with the target's MAC address.
4. Execute Payloads: Use the Web Console to run stored payloads, type live text, or execute combinations.

- Supported Macro Commands

ShinobiDuck supports a practical subset of standard Rubber Ducky (DuckyScript) commands:

• REM [comment] - Comment line, ignored.
• STRING [text] - Types the following text.
• STRINGLN [text] - Types the following text and presses ENTER.
• DELAY [ms] / WAIT [ms] - Pauses execution for the specified milliseconds.
• DEFAULT_DELAY [ms] - Sets a standard delay between all subsequent commands.
• REPEAT [count] - Repeats the previous command.
• GUI r, CTRL ALT DELETE, ALT F2, etc. - Standard modifier key combinations.
• Single Keys: ENTER, TAB, ESC, DELETE, UP, DOWN, F1-F12, etc.

! Disclaimer

This tool is designed for educational purposes and authorized penetration testing. You should only use ShinobiDuck on systems that you own or have explicit permission to audit. The developers are not responsible for any misuse or damage caused by this software.

---

Created for stealth. Engineered for impact.