Extensions

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. Payload Studio 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.

Similar to payloads which may be contributed to the open source USB Rubber Ducky Payload repository via pull-request, extensions too may be added.

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

Alternatively, the full library of EXTENSIONs can be found in the USB Rubber Ducky Payload repository within the Extensions folder.

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.

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

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".

Last updated