Hacking on Admantium

Physical Hacking: An introduction to Ducky Script

Thu, 07 May 2026 00:00:00 +0000

Image source: hak5

Physical hacking of a computer encompasses injection of commands with the target to grab files, install programs, create custom users or gain control. With the programmable Ducky Script USB stick, these exploits can be crafted to target any host system. When inserted, a preprogramed script is executed, written in the Ducky Script language.

This article is a concise introduction to the DuckyScript programming language. Based on the official DuckyScript documentation, it covers the essential commands and overall syntax, from keystrokes to host state management and function definition.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The technical context for this article is CircuitPython v9.1.4 and Adafruit CircuitPython Bundle v9.x. The examples should work with newer releases too, but might require some code changes.

DuckyScript Program

A DuckyScript program is a line terminated sequence of commands that executes keystrokes on a target computer. The goal of these keystrokes is typically to infiltrate or compromise a system, for example by running commands that start a reverse shell, creating user accounts with root privileges, or downloading and installing malware. Therefore, a DuckyScript program can be thought of the vehicle, and the actual, os-specific exploit, as the transport.

The original DuckyScript programs are compiled into a binary using the Hak5 Payload Studio program. This binary is then uploaded to an USB stick, and executed when the USB stick is connected to a host device

The original hardware is not the only option to run DuckyScripts - several interpreters for different hardware are available in the open source community, including these:

pico ducky: A library for running DuckyScript on the Raspberry Pico microcontroller, using a CircuitPython interpreter.
Potato Parser: A library for running DuckyScript on ESP32 Devices. This Arduino project creates a custom binary with all included libraries.
Flipper BadUSB: A DuckyScript 2.x compatible language that runs on the flipper hacking device.
DucKey-Logger: A special PowerShell based exploit that completely logs all keystrokes and sends them to an online address.

Ducky Script Commands

The DuckyScript commands can be separated into these categories:

Keystrokes: Most commands initiate a single or sequence of keystrokes, including control keys.
Host State Management: Some commands read the systems keyboard state, and can be used as triggers to continue program flow, e.g. waiting for the user to start the screensaver, from which the exploit than resumes
Device State Management: The original rubber duck USB stick features an LED and a button. Commands for these features can turn the LED on or await the press of a button as a trigger
Program Structure & Control: DuckyScript allow the definition of variables and functions, lopping, branches and functions. For integer and boolean values, several operators exist. Finally, the global program state can be reflected and modified.

Keystrokes

Character Keys

STRING, STRINGLN

Execute character keypresses one after the other. The STRINGLN command automatically adds a newline character. Both commands can also be used in a block notation, and indented form.

To enter the string “hello” on a target system, both of the following commands can be used.

STRING
  h
  e
  l
  l
  o

STRING hello

cursor keys

UP DOWN LEFT RIGHT UPARROW DOWNARROW LEFTARROW RIGHTARROW PAGEUP PAGEDOWN HOME END INSERT DELETE DEL BACKSPACE TAB SPACE

These commands execute a cursor key press. As such, they are helpful to navigate inside a specific program, such as a text editor.

System Keys

ENTER ESCAPE PAUSE BREAK PRINTSCREEN MENU APP F1 F2 F3 F4 F5 F6 F7 F8 F9 F0 F11 F12

SHIFT ALT

CONTROL or CTRL

COMMAND

WINDOWS or GUI

CTRL SHIFT ALT SHIFT COMMAND CTRL COMMAND CTRL SHIFT COMMAND OPTION COMMAND OPTION SHIFT CONTROL ALT DELETE CAPSLOCK NUMLOCK SCROLLOCK

System keys and key combinations can be used to target OS-specific shortcuts, such as to quickly open a program.

INJECT_MOD

This special command needs to be used when a single modifier key should be pressed. See the following example.

INJECT_MOD GUI

Control Keystroke Duration

HOLD RELEASE

All keystroke commands are executed immediately, but with the help of these special commands, the duration can be controlled.

The following example shows how to keep two keys pressed for 4 seconds.

HOLD ALT F4
DELAY 4000
RELEASE ALT F4

Host State Management

With these commands, the hosts currently pressed keys can be determined.

WAIT_FOR_CAPS_ON WAIT_FOR_CAPS_OFF WAIT_FOR_CAPS_CHANGE WAIT_FOR_NUM_ON WAIT_FOR_NUM_OFF WAIT_FOR_NUM_CHANGE WAIT_FOR_SCROLL_ON WAIT_FOR_SCROLL_OFF WAIT_FOR_SCROLL_CHANGE

On a keyboard, the cap, num and scroll keys can be locked. Their absolute state is reflected by the ON and OFF variants, and any state change with the CHANGE suffix. These commands act as triggers - the program execution stops until the desired state of a key is detected.

$_CAPSLOCK_ON $_NUMLOCK_ON $_SCROLLLOCK_ON

These commands return boolean values depending on the current state of the lock keys.

SAVE_HOST_KEYBOARD_LOCK_STATE RESTORE_HOST_KEYBOARD_LOCK_STATE

This command saves the current state of all lock keys and then restores this state. It could be used to detect a certain user behavior, then switching to a desired state to execute a program, and then to return to the previous state without alarming the user.

Device State Management

Device Type

ATTACKMODE {HID STORAGE HID STORAGE OFF}

A command that puts the USB stick into a different device type that the host system discovers, such as HID, storage, or HID and storage. When set to off, the device will disconnect.

ATTACKMODE {VID_ PID_ MAN_ PROD_ SERIAL_}

Each USB device has several identifiers. These can be configured during setup. Here is a concrete example how to combine these two commands into one.

ATTACKMODE HID VID_033A PID_C3C4 MAN_DUCK PROD_DUCK SERIAL_42

ATTACKMODE {VID_RANDOM PID_RANDOM MAN_RANDOM PROD_RANDOM SERIAL_RANDOM}

Randomize the vendor and product information.

SAVE_ATTACKMODE RESTORE_ATTACKMODE

For dynamically changing the programs behavior, its attack mode configuration can be saved as a state. The state also stores the current ID values - enabling the device to mimic itself as a keyboard now, an USB stick later, and so on.

Device Files

HIDE_PAYLOAD, RESTORE_PAYLOAD

A DuckyScript program will be compiled to a binary file and placed on the device. This file is called inject.bin, and an accompanying seed.bin to generate random values. Both files are shown when the device is connected in HID mode to the host. Executing HIDE_PAYLOAD hides both files, and RESTORE_PAYLOAD shows them.

A third file is called loot.bin, which will be filled with content extracted from the host using the special command EXFIL.

Hardware Components

WAIT_FOR_BUTTON_PRESS

The Ducky Script USB device features a button which can be used for two purposes inside a program. With this command, program execution is blocked until the hardware button is pressed.

BUTTON_DEF & END_BUTTON, ENABLE_BUTTON, DISABLE_BUTTON

This command encapsulates a separate block of code that executes when the button is pressed. (a simple form of a function, but without parameter passing or other). The other two commands control whether such defined blocks will or will not be executed when a button is pressed.

Here is an example to print a message when the button is pressed.

BUTTON_DEF
  STRING Magic button was pressed
END_BUTTON

ENABLE_BUTTON

LED_OFF, LED_R LED_G

These commands control the onboard LED - it can be illuminated as red, green or turned off.

Program Structure & Control

Ducky Script programs are executed top-down. Some commands alter this control flow, including function definition, loops, and several commands delaying the execution until a trigger occurs.

Variables

DEFINE

Constants declared with #, they can contain any string. When called, their value will be inserted. The documentation is not clear about if you can also nest Ducky script commands inside a constant.

VAR

Variables are declared with a $, they can hold unsigned 8bit integer values in decimal and hex notation, as well as the boolean values (represented as strings) of TRUE and FALSE.

Assignments can be augmented, e.g. increasing numerical values as shown in the following example.

VAR $COUNTER = ( $COUNTER + 1 )

RANDOM_LOWERCASE_LETTER RANDOM_UPPERCASE_LETTER RANDOM_LETTER RANDOM_NUMBER RANDOM_SPECIAL RANDOM_CHAR

With these commands, random strings can be created, including letters, numbers, and special characters. See the following code for the full rule set.

RANDOM_LOWERCASE_LETTER = "abcdefghijklmnopqrstuvwxyz"
RANDOM_UPPERCASE_LETTER = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
RANDOM_LETTER = """
  abcdefghijklmnopqrstuvwxyz
  ABCDEFGHIJKLMNOPQRSTUVWXYZ
  """
RANDOM_NUMBER = "0123456789"
RANDOM_SPECIAL = "!@#$%^&*()"
RANDOM_CHAR = """
  abcdefghijklmnopqrstuvwxyz
  ABCDEFGHIJKLMNOPQRSTUVWXYZ
  0123456789
  !@#$%^&*()
  """

$_RANDOM_INT $_RANDOM_MIN $_RANDOM_MAX

These commands can be used instead of concrete numerical values, resulting in a random integer with the default range of 0...65535, or within the defined min and max values.

Programming Operators

+, -, *, /, %, ^

Perform mathematic operations on numbers. The documentation does not detail how overflows of the integer value range are handled.

==, !=

These comparison operator work on pairs of integers and boolean values, for example checking the state of a certain key press.

>, <, >=, <=

These comparison operators only work on integer values.

&&, ||

These commands enable chaining multiple boolean expressions together.

&, |, >>, <<

Bitwise operators that work on numerical values.

Loops and Conditions

WHILE

The while statement continuously executes a code block until its termination definition evaluates to true. The following example prints and increases an integer value until it reaches the value of 10.

VAR $NUM = 0
WHILE ($NUM <= 10)
    STRING $NUM
    $NUM = ($NUM + 1)
END_WHILE

IF, ELSE

These commands enable branching of program logic. The given term is evaluated to a boolean value, and when evaluated to true, the given code is executed. From the documentation, it is unclear whether multiple ELSE blocks can be used, and also if other program structure commands can be nested, such as function definitions.

VAR $NUM = 42
IF ( $NUM == 42 ) THEN
  STRING Magic number
ELSE IF ( $NUM != 42 ) THEN
  STRING Just an ordinary number
END_IF

Function Definition

FUNCTION RETURN

Functions define blocks of code that are executed when called. They cannot receive parameters, but any variable referenced from within a function will be searched in the global scope. Functions can return numerical and boolean values that can used in other expression (for example a comparison operator).

Here is an example how to increment a numerical value by 10.

FUNCTION INCR()
  VAR $RES = $NUM +10
  RETURN $RES
END_FUNCTION

VAR $NUM = 10
VAR $NUM2 = INCR()

Global Program Flow

DELAY

Fixed time in milliseconds that needs to pass before running the next step.

RESTART_PAYLOAD, STOP_PAYLOAD

Stop and restart the programmed payload

RESET

Completely clears the keystroke buffers, including all LED states.

Global Program Configuration

$_JITTER_ENABLED, $_JITTER_MAX

Define a maximum value of millisecond delay to keystrokes, where each value will be computed individually.

Internal Variables

Ducky Script programs define several internal variables - the complete list encompassed around 40 entries. The variables provide access to the global device, program, and host state, including the hardware buttons and LED, the lock keys, and on the host, whether read/write activity to the USB device is detected or the OS type.

Conclusion

DuckyScript is a programming language to initiate keystrokes on a target computer. Essentially, these commands serve as a vehicle to transport an exploit onto a target system. This article provided a compact introduction to the DuckyScript language. You learned about all commands structured into four categories: a) keystrokes, a single or sequence of keys that are executed, b) host state management, commands that check the state of control keys, c) device management, to control the rubber ducks USB stick button and LED , d) program structure & control, defining variables, functions, and using various expressions to compare and modify numbers, strings and boolean values. Reflecting the language design, a striking feature is that the linear, continuous execution can be controlled by waiting for a specific condition on the target system. And with this, an exploit can be applied at the best moment to fulfill its goal.

Raspberry Pico: USB Hacking Device Programming

Sun, 26 Apr 2026 00:00:00 +0000

Small form-factor single board computers and microcontroller are an ubiquitous stack in electronic projects. An interesting application area for these devices is physical hacking, e.g. using an USB connection to a host system to inject commands, gain system access, or steal files. To my surprise, an entry level microcontroller, the Raspberry Pico, can be used for these nefarious tasks.

This article shows how to turn a Raspberry Pico into a USB hacking device, also called bad USB in hacker jargon. The Pico is programmed to execute a set of steps on the target computer once its USB connection is established. You will learn how to setup the Pico with the required Python version and libraries and see a simple example program that runs on a Linux host: Opening a text file, writing a text, and storing the file.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The technical context for this article is CircuitPython v9.1.4 and Adafruit CircuitPython Bundle v9.x. The examples should work with newer releases too, but might require some code changes.

Required Hardware & Software

For this article, you need a delightfully simple bill-of-materials:

Raspberry Pico or Raspberry Pico W

And for the software:

Connect the Pico to your computer and continue with the setup steps.

Installing Circuit Python and Required Libraries

To turn the Pico into a USB hacking gadget, you first need to install the Circuit Python distribution.

Download the latest version of Circuit Python for the Raspberry Pico or Raspberry Pico W
Hold down the Pico’s BOOTSEL button and connect the Pico to your computer
Drag and drop the Circuit Python firmware to the Pico

With Circuit Python installed, open the Thonny IDE, configure the interpreter as “CircuitPython (generic)” and select the connected Raspberry Pico. This should look like this:

Now you can access the Pico’s filesystem and add the required libraries:

Download the Adafruit Circuit Python bundle for the same major release of Circuit Python that you used before
From the Zip file, copy the following files to the Raspberry Pico with the very same path:

lib/adafruit_hid
lib/adafruit_wsgi
lib/asyncio
adafruit_debouncer.mpy
adafruit_ticks.mpy

The last part is to copy selected files from Pico Ducky.

Download a Zip file of the project, or use git clone
Copy the following files to the Pico’s root directory:

boot.py
code.py
duckyinpython.py

And if you are using a Pico W, additionally copy these files:

secrets.py
webapp.py
wsgiserver.py

The final file layout should like this in the Thonny IDE:

Now you are ready to write your first exploit.

Writing an Exploit

In hacking jargon, an exploit is the execution of intended commands and functions on a computer for a specific goal. The spearhead of bad USB exploits is the scripting language DuckyScript, which is used on special programmable USB sticks.

But thanks to Pico Ducky, these scripts can be run on the Raspberry Pico instead. This libraries code contains an interpreter for DuckyScript, executing Python code instead. According to its develop, you should be able to run any Duck scripts, such as those from the official DuckyScript Payloads GitHub repository.

A coverage of the complete Ducky script language, its syntax and features, is not the scope of this article. But two points need to be mentioned. First, each exploit is specific to an operating system. Second, real world exploits target specific known vulnerabilities of the host for the purpose if infiltration, privilege escalation or malware installation (which is out of scope too). Third, only execute exploits on your own computers, and be aware that you can damage them in the process.

With all this being said, lets stick to an entry level example. Targeting a Linux host system, the script opens the application shortcut menu, opens a text editor, and types a message. The script is as follows:

REM Target: Linux Ubuntu
REM Exploit: open text editor and write a message
ALT F2
STRING gedit
DELAY 1500
ENTER
DELAY 1500
STRING Hello World!
DELAY 3000

As you can infer, these commands correspond to concrete keystrokes (ALT, F4, ENTER), consecutive typing of arbitrary text (STRING), waiting between commands with DELAY and making commands with REM. This script does not have any triggers, so it will run continuously once started.

Running an Exploit

The copied file code.py contains all instructions to run a Pico Duck exploit. It will search and load a file called payload.dd and execute it. Therefore, to run the test exploit, you just need to upload it to the Pico. But be advised again: Only run exploits on your own computers, and be mindful that you can damage the computer in the process.

For testing purposes, you can run the script from the Thonny IDE on your setup computer. To have an additional fallback: Connect the GP0 0 with any GND pin on the Pico to put it into setup mode and disable automatic program execution. Then, selects the code.py file, and click on the run button. The Thonny terminal shows the program execution like this:

progStatus False
Finding payload
Running  payload.dd
Done

For the concrete deployment of the exploit, simply unplug the Pico and connect it to its target system. Once the USB drive is mounted, the script will run automatically.

Pico W Bonus: Interactive Web Server

When you use a Pico W Board, the Pico Duck library will create a local Wifi hotspot with SSID and PSK defined in the secrets.py file. Starting the program via Thonny, you should see the following messages:

Starting Wifi
Connect wifi
192.168.4.1 80
Starting Web Service
starting monitor_buttons
starting blink_pico_w_led
192.168.4.1 80
open this IP in your browser: http://192.168.4.1:80/

Connect to the WiFi hotspot, open the given URL, and you will see a simple web GUI that allows you to add, edit and run exploits.

Outlook

Using USB devices to automatically execute commands can compromise systems. This article only showed a very simple exploit, and it has clear limitations. First, it only works on the intended target system and relies on the specific graphical text editor program to be present. Second, the script will run continuously, without interpretation.

Comparing the DuckyScript with HID script from my earlier article leads me to several observations. HID is based on JavaScript, giving access to full programming language concepts with functions, loops and conditions. Also, HID scripts includes commands to randomize the typing speed of long texts to that of humans Another difference are triggers. HID scripts can be started when a specific event happens, for example when other keystrokes on the host system are detected or when no keystrokes are detected for an amount of time. This makes HID script more stealthy. But there is one big difference: For DuckyScript, a complete language documentation is available. I’m sure that a better understanding of its features will change my viewpoints.

Finally, the USB HID library provides many additional features that can be used. The official documentation lists examples how to control the mouse as well as other generic input like changing the sound volume of the targeted computer. It would be interesting to see how these commands could be incorporated or integrated with Pico Duck.

Conclusion

In this article, you learned how to convert the Raspberry Pico microcontroller into a USB hacking device. Essentially you program the Pico with a custom scripting language, called DuckyScript, with which USB keyboard commands can be executed. Mounted to a target system, the script is executed on the host, and can be used to input complex command sequences. The article showed you how to get started. Besides the Pico itself, you just need a recent Circuit Python version, a USB HID library, and the Pico Duck library which interprets DuckyScript exploits to run with Micro Python. You also saw a very simple exploit for a Linux system: Opening the text editor and type an automated message. But be advised: Only run exploits on systems that you own, and mind that you can damage your computer too.

Turning the Raspberry Pi Zero into a Hacking Gadget

Thu, 16 Apr 2026 00:00:00 +0000

Single Board Computers with the ability to run a full-fledged Linux distribution can be used as portable devices for a wide variety of use cases. To my surprise, one of them is computer hacking. I was astonished about the creativity and ease-of-use how a Raspberry Pi, Raspberry Pi Zero or Pico can be used for potentially nefarious activities. And after a long deliberation, I decided to start writing blog posts about this subject.

The article completely covers the installation, setup, and configuration to convert a Raspberry Pi Zero into a portable hacking device. Once powered, the device will start a custom WiFi endpoint and can be connected to via SSH or HTTP. It offers a CLI and a full-fledged GUI to configure the device behavior when connected to USB. And it can run shell or a custom JavaScript compatible language to initiate keyboard stokes, move the mouse, and access files of the device it is connected too. You will also learn how to combine triggers, startup templates, and HID script for an entry level exploit: When connected via USB to a host system, a text editor will be opened and a message written into it.

This article is for educational purposes only. Only use computers and devices that you own, and be mindful that they can be damaged.

The initial idea for this topic was sparked by an excellent article in the German computer magazine CT 2023/27 titled “Bad USB: Raspi Zero”. The articles itself cannot be accessed, but only its link collection is available on the public internet.

Writing about Hacking?

For a long time, I have been thinking about the aspect of writing about hacking. My specific concern is about how knowledge in this area, the concrete concepts and processes, can be used for nefarious activities. On the other hand, knowledge gathered by first-hand experience, and transparent communication about it, can raise the awareness about essential dangers. Ultimately, this is tied to the question of knowledge itself: For which purpose do you use it?

Physical hacking is the process of connecting an external device to a target computer and starting an exploit. The goals of hacking are manifold, starting from recording interactions that happen at the computer, reading and copying computer files or the computer memory, running user interactions like keystrokes or mouse movements, executing scripts to modify the system or install new applications. An exploit is the concrete process to achieve a goal, and it can be a combination of intended computer behavior (e.g. registering a USB device) with known or new vulnerabilities in a computer system.

I’m no security consultant, but working in IT, I’m exposed to security topics on a daily basis. Bridging the gap from theoretical knowledge to hands-on experiences while further exploring the amazing Raspberry Pi use cases provided the final nudge to start this blog series. And with this realization, I also feel the need to formulate a disclaimer: This blog content is presented as-is for educational purposes. Only use them on computer systems that you own, and be aware that you can damage the systems.

Finally, bear in mind that explored concepts in this article are written from a beginner’s mind.

Hardware Requirements and Assembly

The required hardware for this article is as follows:

Raspberry Pi Zero W (specifically not a Pi Zero W)
USB Dongle (for example the EP-0097)

The USB dongle needs to be assembled to turn the Zero into a USB hacking device. The particular dongle that I acquired did not include a construction manual, but its components seemed manageable.

However, trying to assemble it manually surfaced an embarrassing knowledge gap. Specifically, I thought that the connection pins of the USB dongle need to be connected to the Zeros GPI pins. But no, right next to the Zeros USB ports, external circuit “touchpoints” are exposed - the dongle pins merely need to touch them too.

To assemble the USB dongle correctly, follow these steps:

Remove the protection layer from the acryl board
Put the thinner acryl board to the bottom
Put the dongle board on top so that the backside of the extruding pins aligns
Put the thicker acryl board on top, aligning with the pins outward facing direction
Put the RPI Zero with the bottom side down and align the connector pins with the touchpoints
Carefully tighten the screws

The resulting device should look like this:

Software Installation & First Boot

To turn the RPI Zero into a hacking device, the Linux Distribution P4wnP1 ALOA - called PPA from here - will be used. This is a custom Linux distribution, build on top of Kali Linux and specifically modified to run on the RPI Zero. As any other OS, the installation encompasses downloading the image, flashing it onto a SD Card, and booting the device.

The specific steps in detail:

Go to the P4wnP1 ALOA release page and download the latest version (Note: Don’t be discouraged by the release date of February 2020 - the project works very well!)
Open an image software of your choice, then flash the image (my recommendation is Balena Etcher)

After this, put the SD Card into the device, and power it via the USB mini port.

Shortly after booting, PPA creates a custom WiFi with an awkward, UTF8 icon encoded named: “💥 🖥️ 💥”. Connect to it with the password MaMe82-P4wnP1, and once the connection is established, you start exploring the many configuration options.

Tool Overview

PPA is a special Linux distribution with flexible and run-time configurable hardware features of the Raspberry Pi Zero. It provides access to this configuration both via the Web GUI and a CLI. After reading the projects extensive documentation and using the tool for some time, the Web GUI provides more features and will be used exclusively in the remainder of this article.

With an active connection to the hotspot, open http://172.24.0.1:8000 in a browser to access the configuration screen:

Each section in this GUI is a configurable building block of the complete functionality. By learning one section at a time, the overall number of available features becomes clearer.

Hardware Settings

Most sections in the tool menu directly modify the hardware features.

USB: In this section, you define the USB properties when the Zero is connected to the targets. Available options start with the ID, serial number and vendor name, and continue with which USB functions the device offers. It can serve as an ethernet adapter, an HID device (keyboard, mouse, custom HID like pointer), as a serial interface, and as USB storage.
WiFi: You can enable or disable the WiFi, change its SSID and PSK, and define its channel and visibility.
Bluetooth: The Bluetooth stack provides several configuration options. The basic ones: availability, discoverability, and connectivity. Furthermore, you can configure if other devices are pairable with/without a key. BLE and Blue Toot High Speed are also supported. Lastly, different Bluetooth network encapsulation protocol services are provided: Network Access Point, Portable Area Network, and Group Ad-hoc network.
Network: In this category, you can configure the concrete network interface settings for the bteth, usbeth and wlan0. For an DHCP server, the IPv4 gateway address, client addresses and netmask, and static hosts. Alternatively, you can also configure interfaces with just static addresses or as clients.

Behavior Programming

To create and manage scripts that are executed when the USB stick is connected to a host, you can use the following:

Trigger Actions: A combination of an event and a concrete action. For an event, several options exist: system checkpoints during startup (Wifi AP, core services), when an USB gadget connects or disconnects, when an external WiFi AP is joined, values on group channel, and even when a GPIO input is detection. The actions can be to write a log entry, send a value to a group channel, set an output to a GPIO, as well as starting a HID script or bash script. Each trigger action can be set to run only and exactly once, or continuously every time it occurs.
HID Script: The heart of exploitation scripting. PPA provides a JavaScript compatible language to program complex behavior that runs on the target machines. As provided in the documentation, special attention was given to robust and OS-agnostic keyboard interactions, including keyboard layout, timing of keystrokes, and waiting for keyboard input. Also, the mouse cursor can be controlled, and combining it with the concrete physical dimensions of the target screen, pixel perfect controls can be achieved. Finally, all JavaScript concepts can be used, giving access to functions, loops, complex conditions and much more.

Log and Settings

Two more sections complete the configurability of the PPA device.

Event Log: Shows all on-device stored log messages that PPA created during its usage. Messages are retained and persisted between boots, giving a complete picture how and when it was used.
Generic Settings: The very last menu item appears a bit misleadingly named - it does not control the overall GUI, but the concrete run- and boot time behavior of PPA. Essentially, the Master Template Editor allows you to select and combine any defined USB, WiFi, Bluetooth, and Network setting, as well as the Trigger actions. With this, you specify the concrete behavior of the PPA, essentially arming the device for its intend purpose. The other options are to restart or shutdown the system, and to create or restore a backup of all user-define settings and modifications.

Writing and activating an HID Exploit

The feature of PPA is extensive, and for a beginner exploring the device features, it might seem daunting to find a good start point. Following the project documentation closely, let’s start with a script that opens a text editor on the host and writes a message. The target OS is Linux Ubuntu.

In the GUI, open the HID Script tab. The editor features syntax highlighting and remote execution for testing purposes. Paste the following code into the editor:

layout('de');   // US keyboard layout
typingSpeed(100,150) // Wait 100ms between key strokes + an additional random value between 0ms and 150ms (natural)

//waitLED(ANY_OR_NONE);  // Wait till NUM LED of target changes frequently multiple times (doesn't work on OSX)

delay(5000);
press("CTRL ALT t");
delay(1000);
type("gedit\n")
delay(1000);
type("Hello from Raspberry Pi Zero");

As you see, the commands relate directly to executing keystrokes on the target machines, enriched by meta-arguments to influence the typing process. The function layout sets the target keyboard, and the delay function defines a random time range for each keystroke, making interactions more natural. With waitForLed, a specific trigger can be added, deferring the script execution until keyboard interaction is detected. This prevents executing the script when e.g. the screen is still locked by the user.

Now, to run this script, two options exist. If you connected the Raspberry Zero directly to a host system, you could click on “Run”. The other option is to actually program this script to be executed when the Raspberry Zero is connected to a computer. For this:

Click on “Store” and define a suitable name for the script.
Select the tab “Trigger Action” and click on “Add one”
In the dialog, activate the “Enabled” slider, then fill out the trigger “USB gadget connected to host”, and in the action field the option “start a HID script” as well as the given script name file (also see the next picture)

The final step is to store and activate this trigger definition:

Still on the “Trigger Action” tab, click on “Store” to save all active triggers as a configuration
Go to on “Generic Settings”, and in the “Master Template Editor”, select the Trigger Action template that you just stored

That’s it. Now you can connect the stick to a Linux host computer and see the script happening.

Where to Continue

Exploring the depth of HID script to write advanced exploits is not the focus of this article. However, I explored some ideas and give my summary here:

P4wnP1: The ancestor project. It includes links to videos and presentations showing particular exploits.
pwnhyve: Naming itself as a sibling project, it focuses on bad USB capabilities and the injection of shellcode into target computers.
pi_zero2w Another developer forked the project and created a version that runs on a Raspberry Pi Zero 2 W, but it with fewer Kali Linux tools and no Bluetooth support
Explore HID Script language: Unfortunately, there is no written document of the language, and digging into the project source code did not reveal an approachable form to me. Considering related rubber duck scripts, the general attack vector is to use HID commands to deploy a base64 decoded scripts for the shell language of the target system (PowerShell for Windows, Bash for Linux), which is then executed to install additional malware or a backdoor.
HID Script collection: This repository is the only other source of examples. It contains script that target Windows Systems to steal credentials and password and provides examples both in HID and in Rubber Duck script.

Conclusion

Small form-size single board computer can be used as hacking gadgets. This article showed how to turn a Raspberry Pi Zero into a bad USB device, a specific form of physical hacking in which an inserted USB stick executes command on the host. You only need a Raspberry Pi Zero, an USB dongle to expose the Zeros USB ports, and the PPA Linux Image. Once the initial setup is completed, the Zero turns into a WiFi and SSH accessible device with complex configuration options for all hardware features. To write a bad USB exploit, the HID language, based on JavaScript, can be used to instruct a sequence of keystrokes. This article showed only a simple exploit: Opening the systems text editor to write a message. Yet the potential for serious exploits becomes visible: By executing shell scripts on the targets, access to the system can be achieved, stealing credentials or installing malware and backdoors.