Getting Started with DuckyScript Payload development
No introduction to a programming language would be complete without a "Hello, World!" example. Call it cliché, but this ubiquitous example makes for a welcoming DuckyScript initiation.
While the new DuckyScript 3.0 introduces a ton of new features, it does so by building on the simplicity of the original DuckyScript language — a language which has become synonymous with the keystroke injection attack technique it invented.
So with this one "Hello, World!" example we'll not only learn the absolute basics of the original DuckyScript language, but also the process for testing out a payload.
- Keystroke Injection — a type of hotplug attack which mimics keystrokes entered by a human.
- Hotplug Attack — an attack or automated task that takes advantage of plug-and-play.
- Plug and Play — a peripheral standard whereby connected devices work automatically.
- HID — a Human Interface Device; the protocol a keyboard uses to speak to a computer
- Mass Storage — what we think of as a thumb drive or SD Card
- USB Rubber Ducky — the USB device that delivers hotplug attacks.
- Payload — the specific hotplug attack instructions processed by the USB Rubber Ducky.
- DuckyScript — both the programming language of, and source code for USB Rubber Ducky payloads. May refer to a specific payload in human-readable DuckyScript source code.
- inject.bin — the binary equivalent of the DuckyScript source code generated by the compiler and encoder consisting of byte code to be interpreted by the USB Rubber Ducky.
- Payload Studio — Integrated Development Environment consisting of a source code editor, compiler, encoder and debugger for programming DuckyScript.
- Editor — the text processing element of the Payload Studio featuring syntax highlighting, autocomplete, indentation and snippets specific to the DuckyScript programming language.
- Compiler — the element of the Payload Studio which converts the DuckyScript source code (payload.txt) into the byte code (inject.bin) interpreted by the USB Rubber Ducky. The Compiler also tests the DuckyScript source to be syntactically correct. May provide warning or error messages if a programming bug is found.
- Debugger — the element of the Payload Studio which may be used to help you test or troubleshoot your payload.
- Language File — also referred to as the Language JSON, this is the lookup table the Compiler uses to encode your keystrokes for a given keyboard language
- Loot — the logs, data and other information obtained during the deployment of a payload, often consisting of details about the target (recon) or information from the target (exfiltration).
- Arming — the act of transferring a payload to the hotplug attack device.
- Arming Mode — a mode whereby the USB Rubber Ducky facilitates convenient payload and loot transfer by acting as USB mass storage.
- Target — the computing device (or "Host") on which the payload will be deployed.
- Deployment — the execution of the payload on the target.
Learn the basics of the original DuckyScript language from this one example alone.
REM My first payload
STRING Hello, World!
As you might imagine, this payload types "Hello, World!".
With the new terms in mind, let's try out the Hello World example by following these steps:
- 1.Plug the USB Rubber Ducky into your computer. If it doesn't show up as a flash drive automatically, press the button to enter arming mode.
- 2.Copy the DuckyScript source code of the Hello World example payload.
- 3.Paste it into a blank new project from the editor in Payload Studio.
- 4.Click Generate Payload to compile the payload.
- 5.Click Download Payload to save the
- 6.Copy the
inject.binfile to the root of the USB Rubber Ducky drive. Ensure the name is exactly
- 7.Unplug the newly armed USB Rubber Ducky from your computer.
- 8.Open a text editor on the target. This may be the same computer used for arming.
- 9.Ensure that the text area is the active window, which is usually indicated by a blinking cursor.
- 10.Deploy the payload against the target by plugging it into an available USB port.
- 11.Watch as the keystroke injection payload is executed by the hotplug attack device.
Voilà — "
These are the steps that will be repeated numerous times as you continue to learn and experiment with the DuckyScript language.
The Payload MUST be named
inject.binexactly. No other name will function;
inject (2).binwill not work.
On Windows: if explorer is NOT set to Show File Extensions When downloading your
inject.bindo NOT append
.binto the filename or your file will be incorrectly named
So, let's break down each line of this payload to understand the language and what it does.
Each line of an original DuckyScript file, or "payload" as they are known, is processed one at a time. A line may include a comment, a delay, or a key or set of keys to press. That's it.
REMis short for Remark and adds a comment to the payload, like a title or the author's name.
DELAYpauses the payload for a given amount of time, expressed in milliseconds.
STRINGinjects keystrokes, or "types", the given characters (a-z, 0-9, punctuation & specials).
ENTERis a special key which may be pressed, like
A full list of special keys is available in the keystroke injection section — but they're named as one might expect. Think:
F11and the like...
Yep. That's it. That's the entirety of the original DuckyScript 1.0 language; comments, delays and keys.
Want to take it just a tiny bit further? Check out these examples for Windows and macOS.
REM A slightly more advanced "Hello, World!" for Windows
REM Open the Run dialog
REM Open powershell with our message
STRING powershell "echo 'Hello, World!'; pause"
- This original Ducky Script payload will open a powershell window showing "
- It starts by opening the Windows Run dialog using the keyboard shortcut Windows Key+r.
- Next it will type a line of powershell which will display "
Hello, World!", then pause.
- Finally, it will press
ENTERto execute the powershell.
REM A slightly more advanced "Hello, World" for macOS
REM Open Spotlight Search
REM Open the text editor
STRING echo Hello, World!
- This original DuckyScript payload will open a TextEdit window showing "
- It starts by opening the Spotlight Search using the keyboard shortcut Command+Space.
- Next it will type "TextEdit" and press
ENTER, which will open the TextEdit app.
- Then it will press the keyboard shortcut Command+N to open a new document.
- Finally, after a 2 second delay, it will type "