🦆⚡ Raspiducky

A modern, high-performance, and lightweight USB Gadget & DuckyScript/HIDScript execution appliance for Raspberry Pi Zero W (and compatible SBCs).

Designed to run as a single Go executable on lightweight Linux distributions (like Raspberry Pi OS Lite), Raspiducky turns your Pi into a powerful, multi-purpose USB attack/automation tool.

✨ Why Raspiducky?

Single Executable Binary: Built in modern Golang, incorporating an embedded REST API, WebSocket server, CLI commands, and a sleek single-page web dashboard using go:embed.
Plug & Play Linux USB ConfigFS: Direct interaction with /sys/kernel/config/usb_gadget for runtime configuration without system reboots.
- ⌨️ HID Keyboard: 8-byte reports with multi-language layout translation (US, ES, DE, FR).
- 🖱️ HID Mouse: Relative movements, absolute positioning, and button clicks.
- 💾 USB Mass Storage (UMS): Mount ISO or RAW disk image backing files in CD-ROM or writable Flash Drive modes.
- 🌐 USB Network: CDC ECM (Linux/Mac) and RNDIS (Windows) with custom MAC addresses and Windows OS descriptors.
- 🔌 USB Serial: CDC ACM serial device interface.
Dual Scripting Engines:
- JavaScript Engine (Goja): Pure Go ECMAScript 5.1+ runtime with native USB HID bindings (type(), press(), delay(), layout(), typingSpeed(), waitLED(), mouseMove(), mouseMoveTo(), mouseClick()).
- DuckyScript Parser: Transparently parses and executes standard Hak5 Rubber Ducky .txt scripts.
Host Keyboard LED State Listener: Reads output reports from /dev/hidg0 (NUMLOCK, CAPSLOCK, SCROLLLOCK), enabling synchronization and payload triggering based on target host interactions.

🖼️ Web Dashboard Showcase

A sleek, dark-mode single-page dashboard with real-time WebSocket log streaming, a payload editor, job manager, and gadget controls.

Main Dashboard & Gadget Control	Script Editor & Live Execution Console

Payload Library & Job Manager

🚀 Getting Started

⚡ 1. Automated Installation (Recommended)

Run this single command on your Raspberry Pi (or compatible Linux target):

curl -fsSL https://raw.githubusercontent.com/arrase/Raspiducky/master/install.sh | sudo sh

¿What does this script do?

Automatically detects your architecture and downloads the latest release binary.
Configures the required USB Gadget kernel overlays.
Installs and starts Raspiducky as a background system service.

Note: Running this command again in the future will automatically update Raspiducky to the latest GitHub release.

🌐 2. Using the Application

Once installed via the script above, Raspiducky is already running in the background! You do not need to start it manually from the terminal.

Simply open your web browser on any device in the same network and navigate to:

http://<raspberry-pi-ip>:8000

From this live dashboard, you can configure your USB gadget settings, manage payloads, and execute scripts interactively.

💻 Hardware Compatibility & USB OTG Support

⚠️ Important Hardware Requirement: USB Gadget mode requires a Single Board Computer (SBC) where the USB OTG controller (DWC2, DWC3, or MUSB) is connected directly to a Micro-USB or USB-C OTG port without an onboard USB Hub chip.

✅ Supported RPi Ports: Raspberry Pi Zero / Zero W / Zero 2 W (Micro-USB USB port), Raspberry Pi 3A+ / A+ (Type-A OTG port), Raspberry Pi 4B / 5 (USB-C power/data port).

❌ Unsupported RPi Ports: Standard Type-A ports on Raspberry Pi 1B, 2B, 3B, and 3B+ pass through an onboard LAN9512/LAN9514/LAN7515 USB hub chip which prevents USB Device/Gadget mode.

🚦 Hardware Endpoint Limits

Depending on your SBC's USB controller, there is a physical hardware limit on the maximum number of USB IN Endpoints that can be active simultaneously:

Raspberry Pi Zero / 1 / 2 / 3 (DWC2 Controller): Limited to 7 IN Endpoints.
Raspberry Pi 4 / 5 (DWC3 Controller): Limited to 15 IN Endpoints.
Other SBCs (e.g., Orange Pi, NanoPi): Varies depending on the SoC's USB controller.

Endpoint Consumption per Function:

⌨️ USB Keyboard (HID): 1 Endpoint
🖱️ USB Mouse (HID): 1 Endpoint
💾 Mass Storage: 1 Endpoint
🔌 USB Serial Console (ACM): 2 Endpoints
🌐 USB Ethernet (RNDIS/ECM): 4 Endpoints (2 for RNDIS, 2 for ECM)

The Raspiducky Web Dashboard automatically reads your specific board's limits directly from the kernel DebugFS and prevents you from deploying a combination of functions that exceeds your hardware's capabilities.

📋 Supported Boards & Binary Asset Matrix

Asset Name	Architecture	Target SBC Boards	USB OTG Port
`raspiducky-linux-armv6`	ARMv6 (32-bit)	• RPi Zero / Zero W • RPi Model A / A+	Micro-USB
`raspiducky-linux-armv7`	ARMv7 (32-bit)	• RPi 3A+ (32-bit OS) • RPi CM 3 • Banana Pi M2 Zero/M1 • Orange Pi Zero/One/PC • NanoPi NEO	Micro-USB
`raspiducky-linux-arm64`	ARM64 (64-bit)	• RPi Zero 2 W (64-bit OS) • RPi 4B / 5 (USB-C) • RPi 3A+ (64-bit OS) • RPi CM4 / CM5 • Orange Pi Zero 2/3/5 • NanoPi R2S/R4S/NEO3 • Radxa Rock Pi • Pine64 Quartz64	USB-C / Micro-USB
`raspiducky-linux-amd64`	x86_64 (64-bit)	• Standard PC / Intel NUC (Linux with USB OTG/UDC hardware or vUSB testing)	USB-C OTG

📜 Scripting Examples

Raspiducky supports both standard DuckyScript and an advanced JavaScript API.

🦆 DuckyScript Example (`hello.txt`)

REM Standard Rubber Ducky Payload
DELAY 1000
GUI r
DELAY 500
STRING notepad.exe
ENTER
DELAY 1000
STRING Hello World from Raspiducky!
ENTER

⚡ JavaScript HIDScript Example (`hello.js`)

// Set keyboard layout to Spanish and speed
layout("es");
typingSpeed(20, 50);

// Open Run dialog on Windows
press("GUI R");
delay(500);
type("notepad.exe\n");
delay(1000);

// Type text
type("Hello from Raspiducky JS Engine!\n");

// Wait for target user to hit NumLock key
waitLED("NUM", 10000);
type("NumLock was toggled on host!\n");

🛠️ Advanced Usage & CLI

While the web dashboard is the easiest and primary way to use Raspiducky, advanced or technical users can interact with the tool directly via the command line.

Starting the Daemon Manually

If you decided to build from source or did not use the automated install script, you must run raspiducky in daemon mode with root privileges (required to interact with /sys/kernel/config/usb_gadget and /dev/hidg*):

sudo ./raspiducky daemon -port :8000 -layout US

Note: The -layout flag sets the default keyboard layout (e.g., US, ES, DE, FR).

Executing Scripts via CLI (Automation)

You can execute a DuckyScript (.txt) or JavaScript (.js) file directly from the command line without using the web interface.

This is especially useful for automation. For example, you can schedule a script to run automatically when the system boots by adding it to the root user's crontab.

sudo ./raspiducky run payloads/hello_world.txt -layout ES

🏗️ Building from Source

Native Build (On Target Device)

git clone https://github.com/arrase/Raspiducky.git
cd Raspiducky
go build -o build/raspiducky ./cmd/raspiducky

Cross-Compiling for Specific Targets

Raspberry Pi Zero / Zero W (ARMv6):

GOOS=linux GOARCH=arm GOARM=6 go build -ldflags="-s -w" -o build/raspiducky-linux-armv6 ./cmd/raspiducky

Raspberry Pi 3A+ / Banana Pi M2 Zero / Orange Pi (ARMv7 32-bit):

GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w" -o build/raspiducky-linux-armv7 ./cmd/raspiducky

Raspberry Pi Zero 2 W / Pi 4 / Pi 5 / Orange Pi 5 / Radxa (ARM64 64-bit):

GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o build/raspiducky-linux-arm64 ./cmd/raspiducky

📐 Architecture

                                  +---------------------------------------+
                                  |         Web Browser / REST / WS       |
                                  +-------------------+-------------------+
                                                      |
                                                      v
+---------------------------------------------------------------------------------------------------+
| Raspiducky (Single Executable)                                                                    |
|                                                                                                   |
|  +-------------------+   +--------------------+   +-----------------------+   +----------------+  |
|  | Embedded Web UI   |   |   REST & WS API    |   |  Goja JS Engine &     |   | Storage        |  |
|  | (go:embed)        |   |   (pkg/api)        |   |  DuckyScript Parser   |   | (pkg/storage)  |  |
|  +-------------------+   +---------+----------+   +-----------+-----------+   +----------------+  |
|                                    |                      |                                       |
|                                    v                      v                                       |
|                         +-----------------------------------+                                     |
|                         |    HID & ConfigFS Controllers     |                                     |
|                         |    (pkg/gadget, pkg/hid)          |                                     |
|                         +-----------------+-----------------+                                     |
+-------------------------------------------|-------------------------------------------------------+
                                            |
                                            v
                      +-------------------------------------------+
                      | Linux Kernel ConfigFS & /dev/hidgX        |
                      +-------------------------------------------+

📡 REST API Reference

Endpoint	Method	Description
`/api/gadget`	`GET`	Retrieve active USB gadget configuration & state
`/api/gadget`	`POST`	Update and deploy new USB gadget parameters
`/api/scripts`	`GET`	List all saved script templates
`/api/scripts`	`POST`	Save or update a script template
`/api/scripts/{name}`	`DELETE`	Delete a script template
`/api/run`	`POST`	Trigger script execution (JS or DuckyScript)
`/api/stop`	`POST`	Stop active script execution
`/api/ws`	`GET`	Real-time WebSocket connection for logs & status events

📄 License

This project is released under the MIT License.

Name		Name	Last commit message	Last commit date
.github		.github
cmd/raspiducky		cmd/raspiducky
docs		docs
pkg		pkg
screenshots		screenshots
.gitignore		.gitignore
.sonarcloud.properties		.sonarcloud.properties
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
mkdocs.yml		mkdocs.yml
sonar-project.properties		sonar-project.properties

Navigation Menu

Repository navigation

About

Repository files navigation

🦆⚡ Raspiducky

✨ Why Raspiducky?

🖼️ Web Dashboard Showcase

🚀 Getting Started

⚡ 1. Automated Installation (Recommended)

🌐 2. Using the Application

💻 Hardware Compatibility & USB OTG Support

🚦 Hardware Endpoint Limits

📋 Supported Boards & Binary Asset Matrix

📜 Scripting Examples

🦆 DuckyScript Example (`hello.txt`)

⚡ JavaScript HIDScript Example (`hello.js`)

🛠️ Advanced Usage & CLI

Starting the Daemon Manually

Executing Scripts via CLI (Automation)

🏗️ Building from Source

Native Build (On Target Device)

Cross-Compiling for Specific Targets

📐 Architecture

📡 REST API Reference

📄 License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🦆⚡ Raspiducky

✨ Why Raspiducky?

🖼️ Web Dashboard Showcase

🚀 Getting Started

⚡ 1. Automated Installation (Recommended)

🌐 2. Using the Application

💻 Hardware Compatibility & USB OTG Support

🚦 Hardware Endpoint Limits

📋 Supported Boards & Binary Asset Matrix

📜 Scripting Examples

🦆 DuckyScript Example (hello.txt)

⚡ JavaScript HIDScript Example (hello.js)

🛠️ Advanced Usage & CLI

Starting the Daemon Manually

Executing Scripts via CLI (Automation)

🏗️ Building from Source

Native Build (On Target Device)

Cross-Compiling for Specific Targets

📐 Architecture

📡 REST API Reference

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

🦆 DuckyScript Example (`hello.txt`)

⚡ JavaScript HIDScript Example (`hello.js`)