The Button

Overview

The button on the USB Rubber Ducky can be used to control payload execution.

By default, if no button definition (BUTTON_DEF) has yet been defined in the payload, pressing the button will invoke ATTACKMODE STORAGE. This will disable any further keystroke injection and effectively turning the USB Rubber Ducky into a mass storage flash drive, often referred to as "Arming Mode".

Confused on how to press the button through the case? You may have missed it in the Quick Start guide.

WAIT_FOR_BUTTON_PRESS

Halts payload execution until a button press is detected.

When this command is reached in the payload, no further execution will occur until the button is pressed. Additionally, while waiting for the button to be pressed, the button definition (either set using BUTTON_DEF or the default) will be temporarily suppressed.

Example

STRING Press the button...
WAIT_FOR_BUTTON_PRESS
STRING The button was pressed!

Result

  • The text "The button was pressed!" will not be typed until the button is pressed.

Example

Result

  • The button must be pressed 3 times to complete the payload.

Example

Result

  • The operator is instructed to press the button as soon as the target is ready for the next stage.

  • The LED command is used to indicate to the operator that the payload is waiting for a button press.

BUTTON_DEF

BUTTON_DEF defines a special function which will execute when the button is pressed anytime throughout the payload (as long as the button control is not already in use by the WAIT_FOR_BUTTON_PRESS command).

By default, if no button definition (BUTTON_DEF) has been defined in your payload at the time the button is pressed, the button will stop all further payload execution and invoke ATTACKMODE STORAGE — entering the USB Rubber Ducky into arming mode.

Similar to functions (described later), which begin with FUNCTION NAME() and end with END_FUNCTION, the button definition begins with BUTTON_DEF and ends with END_BUTTON.

Example

Result

  • The payload will type a period every second until the button is pressed.

  • Once the button is pressed, the payload will type the text "The button was pressed!"

  • After the button press text is typed, the payload will terminate.

Example

Result

  • If the button is pressed at any point in the payload it will stop typing "." and the LED will start blink red until the device is unplugged.

Example

Result

  • If the button is pressed once at any point in the payload it will stop typing "." and the first button definition will be executed.

  • When the first button definition is executed, a secondary button definition will be implemented.

  • If the button pressed a second time, the newly implement second button definition will execute.

DISABLE_BUTTON

The DISABLE_BUTTON command prevents the button from calling the BUTTON_DEF.

Example

Result

  • The DISABLE_BUTTON command disables the button.

  • The button definition which would inject "This will never execute", will never execute — even if the button is pressed.

Example

Result

  • The USB Rubber Ducky will be effectively disabled.

ENABLE_BUTTON

The ENABLE_BUTTON command allows pressing the button to call the BUTTON_DEF.

Example

Result

  • The payload will alternate between the button being enabled and disabled.

  • If the button is pressed within the 5 second disabled window, nothing will happen.

  • If the button is pressed within the 5 second enabled window, the button definition will be executed and "The button was pressed!" will be typed.

  • The payload will loop forever.

Example

Result

  • The payload will continuously type ".".

  • Pressing the button will execute the BUTTON_DEF.

  • The BUTTON_DEF will type "The button was pressed!", then disable itself with the DISABLE_BUTTON command. This will be announced by typing the message "Pressing the button again will do nothing."

  • The payload will continue to type "." as before.

  • Pressing the button again will do nothing.

Internal Variables

The following internal variables relate to the button operation and may be used in your payload for advanced functions.

$_BUTTON_ENABLED

Returns TRUE if the button is enabled or FALSE if the button is disabled.

May be set TRUE to enabled the button or FALSE to disable the button.

$_BUTTON_USER_DEFINED

Returns TRUE if a BUTTON_DEF has been already defined in the payload or FALSE if it hasn't and is still the default.

May be set TRUE or FALSE, however caution must be taken as setting TRUE when a BUTTON_DEF does not exist will cause undefined behavior.

$_BUTTON_PUSH_RECEIVED

Returns TRUE if the button has ever been pressed.

This variable 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.

Last updated

Was this helpful?