USB Rubber Ducky
  • USB Rubber Ducky by Hak5
  • Unboxing "Quack-Start" Guide
  • DuckyScript™ Quick Reference
  • Ducky Script Basics
    • Hello, World!
    • Keystroke Injection
    • Comments
    • Delays
  • Basic Input and Output
    • The Button
    • The LED
  • Attack Modes, Constants and Variables
    • Attack Modes
    • Constants
    • Variables
  • Operators, Conditions, Loops and Functions
    • Operators
    • Conditional Statements
    • Loops
    • Functions
  • Advanced Features
    • Randomization
    • Holding Keys
    • Payload Control
    • Jitter
    • Payload Hiding
    • Storage Activity
    • Lock Keys
    • Exfiltration
    • Extensions
    • Conditional Compilation
  • Tips & Troubleshooting
    • Common issues
    • Tips
Powered by GitBook
On this page
  • Overview
  • Using Extensions
  • How Extensions Work
  • Example
  • Adding Extensions to your payload
  • Directly within PayloadStudio
  • Github
  • Featured Extensions
  • OS_DETECT
  • TRANSLATE

Was this helpful?

  1. Advanced Features

Extensions

Last updated 2 years ago

Was this helpful?

Overview

It should be clear by now that so much is possible with DuckyScript 3.0. The combination of keystroke injection with various attack modes, logic and data processing, along with the built-in features like randomization and internal variables — the possibilities for advanced payload functions seems endless.

As the payload library continues to grow, so too will the DuckyScript 3.0 language. To that end, the extensions feature of the language and editor facilitate the continued growth of the language.

Extensions are blocks of reusable code which may be implemented in any payload. Think of them as snippets, or building blocks, upon which your next payload may benefit.

While Hak5 developers cannot envision all possible use cases for the USB Rubber Ducky, the DuckyScript language has been architected in such a way so that the community as a whole may gain new features and abilities with each contributed extension.

This section describes how to build, publish and use existing published extensions, as well as a summary of a few popular extensions. Extensions (beyond some examples) are currently reserved for collections of helper functions (+ required variables, defines, and configuration options) required to make a complex task simple and reusable - abstracting very complex problems down into one or a few calls for the ease of use to others (example: the translate extension).

Using Extensions

The code blocks within an extension are executed just like any other DuckyScript. The syntax is to wrap the block of code within the EXTENSION Name and END_EXTENSION commands (where Name is the name or title of the extension). Best practice is to include functions within the extension, which may be called as necessary.

How Extensions Work

Extensions begin with a special command, VERSION, which is used to indicate the version of an extension. This is useful because extensions may change over time. will automatically check the version of the used extension with the online extension repository. Within Payload Studio, a current extension will show an UP-TO-DATE tag while an old extension will show OUT-OF-DATE tag.

When using an extension that has been included in the USB Rubber Ducky repository, Payload Studio will show OFFICIAL tag. User created extensions which have not been included in the repository will show UNOFFICIAL tag. An official extension which has been modified will show a MODIFIED tag.

Example

Typically extensions include functions which may be reused across many different payloads. With the below example, any payload including the ASCIIDUCK extension may call DUCK() to enjoy a quacking duck ASCII art.

EXTENSION ASCIIDUCK
    VERSION 1.0
    FUNCTION DUCK()
        STRINGLN      _   
        STRINGLN   __(.)< QUACK!
        
STRINGLN   \___)  
    END_FUNCTION
END_EXTENSION

STRING Let's run our first extension:
DUCK()

Result

  • The payload will type "Let's run our first extension:" followed by the Duck ASCII art.

Adding Extensions to your payload

Directly within PayloadStudio

Copy and paste is a thing of the past! PayloadStudio automatically includes all the official EXTENSIONs for easy access within autocomplete.

Just start typing the extension name then select it from the autocomplete menu

Github

Featured Extensions

OS_DETECT

The OS_DETECT extension includes functions which will attempt to enumerate the target operating system using a variety of techniques including testing $_HOST_CONFIGURATION_REQUEST_COUNT and $_RECEIVED_HOST_LOCK_LED_REPLY.

The DETECT_OS() function will return to $_OS as WINDOWS, MACOS, LINUX, CHROMEOS, ANDROID or IOS.

EXTENSION OS_DETECTION
	REM VERSION 1.0
	REM Omitted for brevity - DO NOT COPY PASTE FROM THIS EXAMPLE.
	REM SEE ABOVE FOR ADDING TO YOUR PAYLOAD
END_EXTENSION

DETECT_OS()

IF ($_OS == WINDOWS) THEN
	STRING Hello Windows!
ELSE IF ($_OS == MACOS) THEN
	STRING Hello Mac!
ELSE IF ($_OS == LINUX) THEN
	STRING Hello Linux!
ELSE IF ($_OS == IOS) THEN
	STRING Hello iOS!
ELSE IF ($_OS == CHROMEOS) THEN
	STRING Hello ChromeOS!
ELSE IF ($_OS == ANDROID) THEN
	STRING Hello Android!
ELSE
	STRING Hello World!
END_IF

TRANSLATE

The TRANSLATE extension can type the values of variables. It includes the functions TRANSLATE_INT, TRANSLATE_HEX, and TRANSLATE_BOOL. Call these functions by first assigning the $INPUT variable.

EXTENSION TRANSLATE
	REM VERSION 1.0
	REM Omitted  for brevity - DO NOT COPY PASTE FROM THIS EXAMPLE.
	REM SEE ABOVE FOR ADDING TO YOUR PAYLOAD
END_EXTENSION

VAR $FOO = 1337
$INPUT = $FOO
TRANSLATE_INT()

REM This will type the digits "1337".

$INPUT = $_CURRENT_VID
TRANSLATE_HEX()

REM This will type the HEX value of the current Vendor ID.

VAR $BAR = FALSE
$INPUT = $BAR
TRANSLATE_BOOL()

REM This will type "FALSE".

Similar to payloads which may be contributed to the open source via pull-request, extensions too may be added.

Alternatively, the full library of EXTENSIONs can be found in the within the .

The below snippets are simply examples of usage. See section for usage within your payload

USB Rubber Ducky Payload repository
USB Rubber Ducky Payload repository
Extensions folder
Adding Extensions to your payload
Payload Studio
Payload Studio showing a modified, official, up-to-date extension.
Adding extension from autocomplete