DuckyScript™ Quick Reference
DuckyScript™ is the programming language of the USB Rubber Ducky™, Hak5® hotplug attack gear and officially licensed devices (Trademark Hak5 LLC. Copyright © 2010 Hak5 LLC. All rights reserved.)
Last updated
DuckyScript™ is the programming language of the USB Rubber Ducky™, Hak5® hotplug attack gear and officially licensed devices (Trademark Hak5 LLC. Copyright © 2010 Hak5 LLC. All rights reserved.)
Last updated
DuckyScript™ officially licensed and supported devices are backwards compatible with previous versions, excluding any device specific functionality.
E.g. DuckyScript™ 1.0 payloads written for the USB Rubber Ducky are valid DuckyScript™ 3.0 and will function on the New USB Rubber Ducky without modification
1.0
Original USB Rubber Ducky (USB-A Only)
2.X
3.0
New USB Rubber Ducky (USB-A & USB-C)
DuckyScript™ includes commands/syntax which only work on some devices. For example, MATCH
and SAVEKEYS
are DuckyScript™ commands which are only for Key Croc payloads and will not work on other devices.
Hak5 does NOT guarantee payload functionality for unlicensed device's, or payloads NOT compiled using Hak5 PayloadStudio
The REM
command does not perform any keystroke injection functions. REM
gets its name from the word remark. While REM
may be used to add vertical spacing within a payload, blank lines are also acceptable and will not be processed by the compiler.
Defining a comment block is simple! Start the comment with REM_BLOCK
and end the comment with END_REM
; everything in between will be considered a comment without the need to prepend every new line with REM
. Comment blocks can be especially useful when you have multiple lines to be included in a single comment or want to retain formatting.
The STRING
command keystroke injects (types) a series of keystrokes. STRING
will automatically interpret uppercase letters by holding the SHIFT
modifier key where necessary. The STRING
command will also automatically press the SPACE cursor key, however trailing spaces will be omitted.
The STRINGLN
command, like STRING
, will inject a series of keystrokes then terminate with a carriage return (ENTER
).
STRING
blocks can be used effectively to convert multiple lines into one without needing to prepend each line with STRING
STRING
blocks strip leading white space and ignore new lines!
is the equivalent of
Or in this case: STRING abc
STRINGLN
blocks can be used like here-doc; allowing you to inject multiple lines as they are written in the payload.
STRINGLN
blocks strip the first tab but will preserve all other formatting
is the equivalent of
Deploying this payload will produce the following keystroke injection on the target machine:
The cursor keys are used to navigate the cursor to a different position on the screen.
UP
DOWN
LEFT
RIGHT
UPARROW
DOWNARROW
LEFTARROW
RIGHTARROW
PAGEUP
PAGEDOWN
HOME
END
INSERT
DELETE
DEL
BACKSPACE
TAB
SPACE
System keys are primarily used by the operating system for special functions and may be used to interact with both text areas and navigating the user interface.
ENTER
ESCAPE
PAUSE BREAK
PRINTSCREEN
MENU APP
F1
F2
F3
F4
F5
F6
F7
F8
F9
F0
F11
F12
Modifier keys held in combination with another key to perform a special function. Common keyboard combinations for the PC include the familiar CTRL c
for copy, CTRL x
for cut, and CTRL v
for paste.
SHIFT
ALT
CONTROL
orCTRL
COMMAND
WINDOWS
orGUI
In addition to the basic modifier key combinations, such as CTRL c
, modifiers and keys may be combined arbitrarily.
CTRL SHIFT
ALT SHIFT
COMMAND CTRL
COMMAND CTRL SHIFT
COMMAND OPTION
COMMAND OPTION SHIFT
CONTROL ALT DELETE
Injecting a modifier key alone without another key — such as pressing the WINDOWS
key — may be achieved by prepending the modifier key with the INJECT_MOD
command.
Lock keys toggle the lock state (on or off) and typically change the interpretation of subsequent keypresses. For example, caps lock generally makes all subsequent letter keys appear in uppercase.
CAPSLOCK
NUMLOCK
SCROLLOCK
The DELAY
command instructs the USB Rubber Ducky to momentarily pause execution of the payload. This is useful when deploying a payload which must "wait" for an element — such as a window — to load. The DELAY
command accepts the time parameter in milliseconds.
The minimum delay value is 20.
The DELAY
command may also accept an integer variable.
DELAY
timings might differ slightly depending on the ATTACKMODE
the USB Rubber Ducky is in when executing the DELAY
and depending on the target host.
By default, if no other button command is currently in use, pressing the button during payload execution will make the USB Rubber Ducky stop any further keystroke injection. It will then become an ordinary USB flash drive, commonly referred to as "arming mode".
Halts payload execution until a button press is detected. When this command is reached in the payload, no further execution will occur.
The BUTTON_DEF
command defines a function which will execute when the button is pressed anytime within the payload so long as the button control is not already in use by the WAIT_FOR_BUTTON_PRESS
command or other such function.
The DISABLE_BUTTON
command prevents the button from calling the BUTTON_DEF
.
The ENABLE_BUTTON
command allows pressing the button to call the BUTTON_DEF
.
The USB Rubber Ducky includes an LED which may be helpful when deploying certain payloads where feedback is important.
The LED_OFF
command will disable all LED modes.
The LED_R
command will enable the red LED.
The LED_G
command will enable the green LED.
An attack mode is the device type that a USB Rubber Ducky, is functioning as or emulating. If no ATTACKMODE
command is specified as the first command (excluding REM
), the HID
attack mode will execute, allowing the device to function as a keyboard. The ATTACKMODE
command may be run multiple times within a payload, which may cause the device to be re-enumerated by the target if the attack mode changes.
HID
Functions as a Human Interface Device, or Keyboard, for keystroke injection.
STORAGE
Functions as USB Mass Storage, or a Flash Drive, for copying files to/from the target.
HID STORAGE
Functions as both USB Mass Storage and Human Interface Device
OFF
Will not function as any device. May be used to disconnect the device from the target.
When using these optional parameters, VID
and PID
must be used as a set. Further, MAN
, PROD
and SERIAL
must also be used as a set.
VID_
Vendor ID (16-bit HEX)
PID_
Product ID (16-bit HEX)
MAN_
Manufacturer (32 alphanumeric characters)
PROD_
Product (32 alphanumeric characters)
SERIAL_
Serial (12 digits)
The SAVE_ATTACKMODE
command will save the currently running ATTACKMODE
state (including any specified VID
, PID
, MAN
, PROD
and SERIAL
parameters) such that it may be later restored.
The RESTORE_ATTACKMODE
command will restore a previously saved ATTACKMODE
state.
The DEFINE
command is used to define a constant. One may consider the use of a DEFINE
within a payload like a find-and-replace at time of compile.
The VAR
command will initiate a variable. Unlike constants, variables begin with a dollar sign ("$
"). Variables contain unsigned integers with values from 0 to 65535. Booleans may be represented as well, either by TRUE
/FALE
or any non-zero number and 0
respectively.
Operators instruct the payload to perform a given mathematical, relational or logical operation.
=
Assignment
+
Add
-
Subtract
*
Multiply
/
Divide
%
Modulus
^
Exponent
Will compare two values to evaluate a single boolean value.
==
Equal to
!=
Not equal to
>
Greater than
<
Less than
>=
Greater than or equal to
<=
Less than or equal to
Parentheses ( )
are required to define the precedence conventions.
Logical operators may be used to connect two or more expressions.
&&
Logical AND. If both the operands are non-zero, the condition is TRUE
.
||
Logical OR. If any of the two operands is non-zero, the condition is TRUE
.
When assigning a value to a variable, the variable itself may be referenced.
Operate on the uint16 values at the binary level.
&
Bitwise AND. If the corresponding bits of the two operands is 1, will result in 1. Otherwise if either bit of an operand is 0, the result of the corresponding bit is evaluated as 0.
|
Bitwise OR. If at least one corresponding bit of the two operands is 1, will result in 1.
>>
Right Shift. Accepts two numbers. Right shifts the bits of the first operand. The second operand determines the number of places to shift.
<<
Left Shift. Accepts two numbers. Left shifts the bits of the first operand. The second operand decides the number of places to shift.
Conditional statements, loops and functions allow for dynamic execution.
The flow control statement IF
will determine whether or not to execute its block of code based on the evaluation of an expression. One way to interpret an IF
statement is to read it as "IF
this condition is true, THEN
do this".
The ELSE
statement is an optional component of the IF
statement which will only execute when the IF
statement condition is FALSE
.
Loops are flow control statements that can be used to repeat instructions until a specific condition is reached.
The block of code within the WHILE
statement will continue to repeatedly execute for a number of times (called iterations) for as long as the condition of the WHILE
statement is TRUE
.
Functions are blocks of organized single-task code that let you more efficiently run the same code multiple times without the need to copy and paste large blocks of code over and over again.
A function may return a integer or boolean value which may also be evaluated.
The pseudorandom number generator provides randomization for keystroke injection, variables and attackmode parameters. The first time a randomization feature is used, a seed.bin
will be generated on the root of the MicroSD card. One may also be generated from the Hak5 IDE.
RANDOM_LOWERCASE_LETTER
abcdefghijklmnopqrstuvwxyz
RANDOM_UPPERCASE_LETTER
ABCDEFGHIJKLMNOPQRSTUVWXYZ
RANDOM_LETTER
abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
RANDOM_NUMBER
0123456789
RANDOM_SPECIAL
!@#$%^&*()
RANDOM_CHAR
abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789 !@#$%^&*()
The internal variable $_RANDOM_INT
assigns a random integer between the specified $_RANDOM_MIN
and $_RANDOM_MAX
values. May be 0-65535. The default values are 0-9
.
The ATTACKMODE
command may accept random values for the optional parameters.
VID_RANDOM
Random Vendor ID
PID_RANDOM
Random Product ID
MAN_RANDOM
Random 12 alphanumeric character iManufacturer
PROD_RANDOM
Random 12 alphanumeric character iProduct
SERIAL_RANDOM
Random 12 digit serial number
Use caution when using random VID
and PID
values as unexpected results are likely.
A key may be held, rather than pressed, by specifying a HOLD
and RELEASE
command with a DELAY
in between the two. Both HOLD
and RELEASE
must specify a key. Multiple simultaneous keys may be held.
These simple commands exist to control the execution of a payload.
The RESTART_PAYLOAD
command ceases execution, restarting the payload from the beginning.
The STOP_PAYLOAD
command ceases and further execution.
The RESET
command clears the keystroke buffer, useful for debugging complex hold key states.
Jitter randomly varies the delay between individual key presses based on the seed.bin
value.
$_JITTER_ENABLED
Set TRUE
to enable and FALSE
to disable jitter.
$_JITTER_MAX
Integer (0-65535) of maximum time in milliseconds between keystrokes. Default 20.
The inject.bin
and seed.bin
file may be hidden from the MicroSD card before implementing ATTACKMODE STORAGE
. The HIDE_PAYLOAD
and RESTORE_PAYLOAD
commands must be run while using ATTACKMODE OFF
or ATTACKMODE HID
.
Hides the inject.bin and seed.bin files from the MicroSD card.
Restores the inject.bin and seed.bin files to the MicroSD card.
USB HID devices contain both IN endpoints for data (keystrokes) from the keyboard to computer, and OUT endpoints for data (LED states) from the computer to the keyboard. In many cases the LED state control codes sent from the computer to the attached keyboard are sent to all attached "keyboards". Versions of macOS behave differently.
WAIT_FOR_CAPS_ON
Pause until caps lock is turned on
WAIT_FOR_CAPS_OFF
Pause until caps lock is turned off
WAIT_FOR_CAPS_CHANGE
Pause until caps lock is toggled on or off
WAIT_FOR_NUM_ON
Pause until num lock is turned on
WAIT_FOR_NUM_OFF
Pause until num lock is turned off
WAIT_FOR_NUM_CHANGE
Pause until num lock is toggled on or off
WAIT_FOR_SCROLL_ON
Pause until scroll lock is turned on
WAIT_FOR_SCROLL_OFF
Pause until scroll lock is turned off
WAIT_FOR_SCROLL_CHANGE
Pause until scroll lock is toggled on or off
The currently reported lock key states may be saved and later recalled using the SAVE_HOST_KEYBOARD_LOCK_STATE
and RESTORE_HOST_KEYBOARD_LOCK_STATE
commands.
Exfiltration is the unauthorized transfer of information from a system. Typically performed over a physical medium (copying to a USB flash disk such as the USB Rubber Ducky while using ATTACKMODE STORAGE
) or a network medium such as email, ftp, smb, http, etc.
By taking advantage of the HID OUT endpoint as described in the lock keys section, binary data may be exfiltrated "out of band" using the Keystroke Reflection side-channel attack. This is done by using the $_EXFIL_MODE_ENABLED
internal variable. The reflected lock keystrokes are saved to loot.bin
on the root of the MicroSD card. For a detailed example, see the section on Keystroke Reflection.
Similarly, arbitrary variable data may be saved to the loot.bin
file using the EXFIL
command.
BUTTON
$_BUTTON_ENABLED
Returns TRUE
if the button is enabled or FALSE
if the button is disabled.
$_BUTTON_USER_DEFINED
Returns TRUE
if a BUTTON_DEF
has been implemented in the payload or FALSE
if it hasn't been implemented.
$_BUTTON_PUSH_RECEIVED
Returns TRUE
if the button has ever been pressed. May be retrieved or set.
$_BUTTON_TIMEOUT
The button debounce, or cooldown time before counting the next button press, in milliseconds. The default value is 1000
.
LED
$_SYSTEM_LEDS_ENABLED
Default set TRUE
. May be retrieved or set. Boot and ATTACKMODE
change LED.
$_STORAGE_LEDS_ENABLED
Default set TRUE
. May be retrieved or set.
Blinks the LED red/green on storage read/write in ATTACKMODE STORAGE
.
$_LED_CONTINUOUS_SHOW_STORAGE_ACTIVITY
Default set TRUE
. May be retrieved or set.
The LED will light solid green when the storage has been inactive for longer than $_STORAGE_ACTIVITY_TIMEOUT
(default 1000 ms). Otherwise, the LED will light red when active.
$_INJECTING_LEDS_ENABLED
Default set TRUE
. May be retrieved or set. When TRUE
the LED will blink green on payload execution.
$_EXFIL_LEDS_ENABLED
Default set TRUE
. May be retrieved or set. When TRUE
the LED will blink green during Keystroke Reflection.
$_LED_SHOW_CAPS
Default set FALSE
. May be retrieved or set. When TRUE
will bind the GREEN LED state to the CAPSLOCK
state.
$_LED_SHOW_NUM
Default set FALSE
. May be retrieved or set. When TRUE
will bind the RED LED state to the NUMLOCK
state.
$_LED_SHOW_SCROLL
Default set FALSE
. May be retrieved or set. When TRUE
will bind the GREEN LED state to the SCROLLLOCK
state.
ATTACKMODE
$_CURRENT_VID
Returns the currently operating Vendor ID with endian swapped. May only be retrieved. Cannot be set.
$_CURRENT_PID
Returns the currently operating Product ID with endian swapped. May only be retrieved. Cannot be set.
$_CURRENT_ATTACKMODE
Returns the currently operating ATTACKMODE represented as 0
for OFF
, 1
for HID
, 2
for STORAGE and 3
for both HID
and STORAGE
RANDOM
$_RANDOM_INT
Random integer within set range.
$_RANDOM_MIN
Random integer minimum range (unsigned, 0-65535)
$_RANDOM_MAX
Random integer maximum range (unsigned, 0-65535)
$_RANDOM_SEED
Random seed from seed.bin
$_RANDOM_LOWER_LETTER_KEYCODE
Returns random lower letter scancode (a-z)
$_RANDOM_UPPER_LETTER_KEYCODE
Returns random upper letter scancode (A-Z)
$_RANDOM_LETTER_KEYCODE
Returns random letter scancode (a-zA-Z)
$_RANDOM_NUMBER_KEYCODE
Returns random number scancode (0-9)
$_RANDOM_SPECIAL_KEYCODE
Returns random special char scancode (shift+0-9)
$_RANDOM_CHAR_KEYCODE
Returns random letter number or special scancode
JITTER
$_JITTER_ENABLED
Set TRUE
to enable jitter. Default FALSE
.
$_JITTER_MAX
Sets the maximum time between key presses in milliseconds. The default maximum is 20 ms.
LOCK KEYS
$_CAPSLOCK_ON
TRUE
if on, FALSE
if off.
$_NUMLOCK_ON
TRUE
if on, FALSE
if off.
$_SCROLLLOCK_ON
TRUE
if on, FALSE
if off.
$_SAVED_CAPSLOCK_ON
On USB attach or SAVE_HOST_KEYBOARD_LOCK_STATE
, sets TRUE
or FALSE
depending on the reported OS condition.
$_SAVED_NUMLOCK_ON
On USB attach or SAVE_HOST_KEYBOARD_LOCK_STATE
, sets TRUE
or FALSE
depending on the reported OS condition.
$_SAVED_SCROLLLOCK_ON
On USB attach or SAVE_HOST_KEYBOARD_LOCK_STATE
, sets TRUE
or FALSE
depending on the reported OS condition.
$_RECEIVED_HOST_LOCK_LED_REPLY
On receipt of any lock state LED control code, sets TRUE
. This flag is helpful for fingerprinting certain operating systems (e.g. macOS) or systems which do not reflect lock keys.
STORAGE
$_STORAGE_ACTIVITY_TIMEOUT
As payload is running, this value decrements if storage activity is not detected. Default value is 1000.
EXFILTRATION
$_EXFIL_MODE_ENABLED
Default FALSE
. Set TRUE
to enable Keystroke Reflection. Will listen for CAPSLOCK
and NUMLOCK
changes, writing binary values to loot.bin. num=1, caps=0.
OS_DETECT
$_HOST_CONFIGURATION_REQUEST_COUNT
Used by OS_DETECT
EXTENSION
to detect device enumeration count.
$_OS
Used by OS_DETECT
EXTENSION
to return value of fingerprinted operating system. May return WINDOWS
, MACOS
, LINUX
, CHROMEOS
, ANDROID
, IOS
. These names are reserved and should not be used in user variables.
, , , , ,