What is MallardScript?

Gravatar Profile nate-wilkins@code-null.com
Nate-Wilkins
6 min read
Jan 22, 2023

MallardScript is an extension of the language called DuckyScript that adds additional syntax like

IMPORT
commands. This extension thus allows developers and hackers alike to write more verbose scripts by giving them the ability to "import" other files. This happens recursively for the sake of composability.

What's interesting about this project is that I initially started out writing this for myself to use on my Hak5 USB Rubber Ducky but soon discovered DuckyPad which also similarly uses DuckyScript.

Let me start from the beginning.

What is a USB Rubber Ducky?

USB Rubber Ducky

In a nutshell it's an automated keyboard.

It allows a user to program the USB Rubber Ducky to do anything a normal keyboard can do but automatically when you plug it in. Which, I think, is very cool.

In the context of Hak5 it's a hacker's best friend. The automation enables a hacker to construct a payload that allows the hacker to do anything a keyboard can do. Which... is quite a lot (and keyboard use is a good thing regardless of whether hackers abuse it or not). All under the guise of a normal looking USB stick.

To see the payloads that people have already started to make you can check out the Hak5 Payload Repository.

What is DuckyScript?

Now DuckyScript is the scripting language used to instruct the USB Rubber Ducky on what keys to press and when.

Here's a sample script that opens the command line on my machine and runs

display_rice
.

1REM Wait for Device Recognition.
2DELAY 2000
3REM Open rofi launcher.
4GUI SPACE
5REM Wait for Search.
6DELAY 200
7REM Search for 'alacritty'.
8STRING alacritty
9REM Wait for Search results.
10DELAY 100
11REM Open application 'alacritty'.
12ENTER
13REM Wait for Application 'alacritty'.
14DELAY 4000
15REM Run 'display_rice'.
16STRING display_rice
17ENTER
DuckyScript Example

What is a DuckyPad?

DuckyPad

This keyboard allows the user to write custom DuckyScript scripts for keys on the keyboard and mouse input. Allowing them to automate workflows that might not have an intuitive/usable programmable interface.

Pretty cool.

I don't currently own one of these because I don't really have a need for one since I automate most everything with keyboard shortcuts and because I use terminal programs a

lot

.

Okay, So what is MallardScript?

This is a syntax and command line interface that extends the DuckyScript language that I created to allow for

IMPORT
commands to allow me to create reusable/composable scripts.

It extends DuckyScript but only the Hak5 USB Rubber Ducky variant right now since the DuckyPad has additional syntax/commands for other various instructions like mouse controls.

The supported syntax can be found in the PEST Grammar File. This parser has the ability to parse:

  • Commands

    • REM Custom Payload

    • STRING Hello World!

    • STRINGN echo "Hello World!"

    • GUI SPACE

    • DELAY 1000

    • IMPORT "./intro.duckyscript"

    • etc

  • Variables

    • VAR $MY_VAR = 0

    • MY_VAR = $MY_VAR + 1

    • etc

  • Control Flow

    • IF

    1IF $MY_VALUE > 0 THEN
2  STRING Hello World!
3END_IF

    • Expressions

    1IF ($MY_VALUE > 0 && FALSE) THEN
2  STRING Hello World!
3END_IF

To use MallardScript with the USB Rubber Ducky you'll have to check out the mallardscript command line tool that takes an input script and outputs DuckyScript for deployment.

Using MallardScript with a USB Rubber Ducky

So now you know what it looks like, how do we use it? At least in the context of deploying a payload to the USB Rubber Ducky you can follow these steps:

  1. Setup language dependencies. You can do this globally or with a tool like

    asdf
    .

  2. Setup command line tools.

  3. Create a MallardScript (

    src/index.duckyscript
    ):

    1GUI SPACE
2DELAY 1000
3STRINGN Alacritty
4DELAY 1000
5STRINGN display_rice
6REM Optionally IMPORT Statements!
7IMPORT "./run_introduction.duckyscript"

  4. Compile the MallardScript to DuckyScript.

    mallardscript build --input "src/index.ducky" --output "output/index.ducky"

  5. Compile the DuckyScript to a binary.

    ducktools.py -e -l gb "output/index.ducky" "bin/inject.bin"

  6. Once compiled successfully copy the

    inject.bin
    to the USB Rubber Ducky.

  7. Plug in the USB Rubber Ducky in Attack Mode!

Congratulations! You just wrote your first MallardScript and possibly your first ever payload!

Please use the USB Rubber Ducky responsibly.

If you'd like to know more about how MallardScript works feel free to keep reading!

MallardScript Development

There are two parts that make up the command line tool

mallardscript
.

The first is

pest_duckyscript
. A Rust PEST grammar that is used to parse DuckyScript and MallardScript syntaxes. This grammar allows the main
mallardscript
 tool to understand the structure of the provided script.

The second is

mallardscript
, the tool itself. This is a command line tool also written in Rust with the clap argument parser. Which takes in a MallardScript script and outputs a valid DuckyScript script.

Each of these repositories have corresponding crates in the Rust package repository and are currently maintained in my spare time.

In the future I'd like to get the following working:

  • Compile MallardScript directly to a binary payload.

  • Support DuckyPad syntax.

  • Create OS packages for the command line tool.

  • Add source errors.

If you'd like to provide feedback please feel free to email me!