Getting Started with DuckyScript: A Complete Beginner's Guide

What is DuckyScript?

DuckyScript is a simple yet powerful scripting language designed specifically for Human Interface Device (HID) automation. Originally developed by Hak5 for their USB Rubber Ducky, it has since become the de facto standard for keystroke injection devices used in security testing and IT automation.

Think of DuckyScript as a way to "type" commands automatically. When you plug a DuckyScript-enabled device into a computer, it appears as a regular keyboard and executes pre-programmed keystrokes at superhuman speeds. This makes it an invaluable tool for security professionals conducting authorized penetration tests, IT administrators automating repetitive tasks, and developers testing application security.

Why Learn DuckyScript?

Understanding DuckyScript opens doors to several practical applications in the cybersecurity and IT fields. Security researchers use it to demonstrate vulnerabilities in physical security protocols during authorized assessments. System administrators leverage it to automate software deployments and configuration tasks across multiple machines. Quality assurance teams employ it for automated testing scenarios that require keyboard input simulation.

The language itself is remarkably accessible. Unlike complex programming languages that require months of study, DuckyScript can be learned in an afternoon. Its syntax mirrors natural language, making scripts readable even to those without programming experience.

DuckyScript Versions Explained

Before writing your first script, it's important to understand that DuckyScript exists in multiple versions, each with different capabilities.

DuckyScript 1.0 is the original version, supported by most devices including Flipper Zero, Evil Crow Cable, USB Nova, and Malduino. It provides basic keystroke injection with commands like STRING, DELAY, and modifier keys. This version is excellent for straightforward automation tasks and remains the most widely compatible option.

DuckyScript 2.X extends the original with additional commands for devices like Bash Bunny and Key Croc. These devices can switch between multiple attack modes (HID, storage, network) and include specialized commands for their unique features.

DuckyScript 3.0 represents the latest evolution, available exclusively on the new USB Rubber Ducky. It introduces programming constructs like variables, conditional statements, loops, and functions. This version enables complex logic that was previously impossible with basic keystroke injection.

Your First DuckyScript

Let's write a simple script that opens Notepad on Windows and types a message. This example demonstrates the core concepts you'll use in every script:

REM This is a comment - it won't be executed
REM Open the Run dialog
DELAY 1000
GUI r
DELAY 500
STRING notepad
ENTER
DELAY 1000
STRING Hello from DuckyScript!

Let's break down each line. The REM command creates comments that document your code without affecting execution. The DELAY command pauses execution for a specified number of milliseconds, giving the target system time to respond. GUI r simulates pressing the Windows key and 'r' simultaneously, opening the Run dialog. STRING types the specified text character by character. ENTER simulates pressing the Enter key.

Essential Commands Reference

Mastering these fundamental commands will enable you to create effective scripts for most scenarios.

Text Input Commands form the backbone of most scripts. STRING types text exactly as written, while STRINGLN (DuckyScript 3.0 only) types text and presses Enter automatically.

Timing Commands control the pace of execution. DELAY pauses for a specific duration in milliseconds, and DEFAULTDELAY sets a pause between every subsequent command.

Modifier Keys enable keyboard shortcuts. GUI (or WINDOWS) represents the Windows/Super key, CTRL is Control, ALT is Alt, and SHIFT is Shift. These can be combined with other keys, such as CTRL ALT DELETE or GUI r.

Navigation Keys include ENTER, TAB, ESCAPE, SPACE, BACKSPACE, DELETE, and arrow keys (UPARROW, DOWNARROW, LEFTARROW, RIGHTARROW).

Best Practices for Script Development

Writing effective DuckyScript requires understanding both the language and the target environment. Here are practices that will improve your scripts' reliability.

Always include adequate delays. Different computers respond at different speeds. A script that works perfectly on a fast SSD-equipped machine might fail on an older system with a spinning hard drive. Start with generous delays and optimize later.

Test incrementally. Build your script piece by piece, testing each section before adding more complexity. This approach makes debugging significantly easier.

Consider keyboard layouts. DuckyScript assumes a US keyboard layout by default. If your target uses a different layout, special characters might not type correctly. Many devices support layout configuration to address this.

Document your scripts. Use REM comments liberally to explain what each section does. Your future self will thank you when revisiting scripts months later.

Practical Example: System Information Gathering

Here's a more practical script that demonstrates how security professionals might gather system information during an authorized assessment:

REM System Information Gathering Script
REM For authorized security assessments only
DELAY 2000
GUI r
DELAY 500
STRING powershell
DELAY 500
ENTER
DELAY 1500
STRING $info = Get-ComputerInfo | Select-Object CsName, WindowsVersion, OsArchitecture
ENTER
DELAY 500
STRING $info | Format-List
ENTER

This script opens PowerShell and retrieves basic system information. In a real security assessment, such information helps auditors understand the target environment and identify potential vulnerabilities.

Next Steps

Now that you understand the fundamentals, practice by writing scripts for tasks you perform regularly. Start simple: perhaps a script that opens your favorite applications, or one that types your email signature. As you gain confidence, explore device-specific features and more advanced techniques.

The SAPSAN TERMINAL editor provides syntax highlighting, templates, and AI-powered assistance to accelerate your learning. Upload your scripts to supported devices and see your code come to life.

Remember: always use these skills responsibly and only on systems you own or have explicit permission to test. DuckyScript is a powerful tool that, like any tool, should be used ethically and legally.