> For the complete documentation index, see [llms.txt](https://documentation.hak5.org/hak5-usb-rubber-ducky/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.hak5.org/hak5-usb-rubber-ducky/advanced-features/extensions.md). # 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](https://encoder.hak5.org) 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. ![Payload Studio showing a modified, official, up-to-date extension.](/files/cf5z5192nNVs5BmanvvG) ### 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. {% hint style="info" %} Similar to payloads which may be contributed to the open source [USB Rubber Ducky Payload repository](https://github.com/hak5/usbrubberducky-payloads) via pull-request, extensions too may be added. {% endhint %} ## Adding Extensions to your payload ### Directly within PayloadStudio Copy and paste is a thing of the past! PayloadStudio automatically includes all the official `EXTENSION`s for easy access within autocomplete. {% hint style="info" %} Just start typing the extension name **then select it ****from the autocomplete menu** {% endhint %}

Adding extension from autocomplete

### Github Alternatively, the full library of `EXTENSION`s can be found in the [USB Rubber Ducky Payload repository](https://github.com/hak5/usbrubberducky-payloads) within the [Extensions folder](https://github.com/hak5/usbrubberducky-payloads/tree/master/payloads/extensions). ## 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`. {% hint style="danger" %} The below snippets are simply **examples of usage**. See [Adding Extensions to your payload](#adding-extensions-to-your-payload) section for usage within your payload {% endhint %} ``` 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". ```