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.
This article originally appeared at my blog admantium.com.
Required Hardware & Software
For this article, you need a delightfully simple bill-of-materials:
- Raspberry Pico or Raspberry Pico W
And for the software:
- CircuitPython Raspberry Pico or CircuitPython Raspberry Pico W
- Adafruit CircuitPython Bundle
- Pico Ducky
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.
Top comments (0)