Raspberry Pi Zero 2 W BadUSB HID Toolkit

Eine programmierbare BadUSB-/HID-Angriffsplattform auf Basis eines Raspberry Pi Zero 2 W. Der Pi präsentiert sich als USB-Verbundgerät (Composite Device) (Tastatur plus optionales, schreibgeschütztes Massenspeicher-Volume) und führt Ducky-Script-artige Payloads gegen den Host aus, an den er angeschlossen ist. Entwickelt für autorisierte Red-Team-Einsätze, Penetrationstests und CTFs.

⚠️ Rechtlicher Hinweis. Verwenden Sie das Gerät nur an Systemen, die Ihnen gehören oder für die Sie eine ausdrückliche schriftliche Testgenehmigung besitzen. Unbefugter Zugriff ist in den meisten Rechtsordnungen illegal, und so zu tun, als hätte man es nicht gewusst, hilft nicht weiter.

Funktionen

Programmierbare Keystroke-Payloads in einem Ducky-Script-kompatiblen Dialekt.
Zuverlässige Host-Erkennung über den UDC-Zustand configured — keine fehlerhaften Payload-Auslösungen beim Booten.
„Reset zwischen Angriffen“, der auf Pi-Zero-2-W-Hardware tatsächlich funktioniert. Abziehen, wieder einstecken, erneut auslösen — kein Stromzyklus nötig.
Konfigurierbare Schutzmechanismen gegen Endlosschleifen, wenn das Gerät eingesteckt bleibt: Mindestintervall pro Auslösung und eine Ratenbegrenzung der Auslösungen pro Minute, beide per Umgebungsvariable überschreibbar.
Optionales Verbund-Massenspeicher-Gadget auf Basis einer flachen Image-Datei (standardmäßig schreibgeschützt — das Offenlegen Ihrer Live-SD-Karte war die alte, schwer zu debuggende Stolperfalle für Dateisystem-Korruption).
US- und UK-Tastaturlayouts, pro Payload über LAYOUT wählbar.
Variablen, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, RANDOM_*-Generatoren, STRING_BLOCK / STRINGLN_BLOCK, DEFINE.
systemd-Integration mit ExecStop, das das Gadget sauber herunterfährt. Kein übrig gebliebener configfs-Zustand; ein Neustart des Dienstes funktioniert ohne Reboot.
udev-verwaltete Berechtigungen für /dev/hidg0 — keine weltweit beschreibbaren Geräteknoten.
pytest-Suite mit 34 Tests für den Ducky-Parser, auf jedem Host ohne angeschlossenen Pi ausführbar.
ACT-LED-Statusanzeige nach jedem Payload-Lauf.

So funktioniert es

+----------------+        USB cable        +-------------+
|  Raspberry Pi  | ===================>>>  |  Host PC    |
|  Zero 2 W      |   (Pi emulates HID +    |  (target)   |
|  (this device) |    optional drive)      |             |
+----------------+                         +-------------+
        |
        |  /home/pi/pi-badusb/
        |
        +-- badusb.service ----> monitor_and_run.py
                                   |
                                   |  on `state == configured`:
                                   v
                                 run_payload.py
                                   |
                                   v
                                 /dev/hidg0  (USB HID gadget)

Beim Booten führt die systemd-Unit badusb.service gadget_setup.sh aus, das über configfs/libcomposite ein USB-Gadget mit einer HID-Tastaturfunktion und (optional) einer Massenspeicher-LUN zusammensetzt, die von einer flachen Image-Datei unter /var/badusb/storage.img gespeist wird.
Die Unit führt dann monitor_and_run.py aus. Sie pollt /sys/class/udc/<udc>/state und wartet auf configured — den USB-Spezifikationszustand, der bedeutet, dass ein Host das Gadget erfolgreich enummeriert hat. (Wir verwenden nicht die Existenz von /dev/hidg0 als Signal: die ist bereits in dem Moment gegeben, in dem das Gadget beim Booten an die UDC gebunden wird, unabhängig davon, ob etwas eingesteckt ist.)
Wenn der Host angeschlossen wird, führt der Listener run_payload.py aus, das payload.txt parst und HID-Reports an /dev/hidg0 schreibt.
Wenn der Payload abgeschlossen ist, entbindet der Listener das Gadget aktiv von der UDC (der Pi Zero 2 W kann ein physisches Trennen nicht per Software erkennen — siehe Architektur-Hinweise), wartet eine Abklingzeit ab und bindet erneut. Das Gerät wartet dann auf den nächsten configured-Übergang.

Hardware

Komponente	Hinweis
Raspberry Pi Zero 2 W	Getestet mit der Hardware-Revision von 2026-05. Der ältere Pi Zero W mit dem BCM2835-dwc_otg-Treiber funktioniert prinzipiell ebenfalls, aber dieses README setzt den 2 W mit dwc2 voraus.
micro-USB-auf-USB-A-Kabel	Oder ein Adapter im „USB-Stick“-Formfaktor, mit dem der Pi direkt in einen Host-Port gesteckt werden kann.
Optional: separates Netzteil	Wenn Sie den Pi aus einer Nicht-Host-Quelle mit Strom versorgen möchten, damit der Listener booten kann, bevor er in ein Zielgerät eingesteckt wird (andernfalls liefert der Host-Port den Strom).

Der Pi Zero 2 W hat zwei micro-USB-Ports:

PWR IN — nur Strom, legt keine USB-Datenleitungen an den dwc2-OTG-Block.
USB — der OTG-Datenport; hier stecken Sie das Gerät in das Zielgerät.

Software

Anforderung	Grund
Raspberry Pi OS (Debian Bookworm oder Trixie, 64-Bit-Lite empfohlen)	Das Installationsskript schreibt auf Bookworm+ nach `/boot/firmware/...` und fällt bei älteren Images auf `/boot/...` zurück.
Python 3	Ist in Pi OS enthalten.
`mkfs.vfat`	Zum Formatieren des Massenspeicher-Backing-Images beim ersten Lauf. Überspringbar, wenn Sie Massenspeicher deaktivieren.
Root-Zugriff für die Einrichtung	Modifiziert systemd, udev und `/boot/firmware/config.txt`.

Installation

Klonen oder kopieren Sie das Repository auf den Pi und führen Sie dann den Installer aus:

git clone http://your-gitea/admin/Pi-Zero-2W-Bad-USB.git /home/pi/pi-badusb
cd /home/pi/pi-badusb
sudo ./install.sh
sudo reboot

Nach dem Neustart den Dienst aktivieren und starten:

sudo systemctl enable --now badusb.service
journalctl -u badusb -f

install.sh ist idempotent — führen Sie es erneut aus, wenn Sie Projektdateien ändern. Es:

Erkennt /boot/firmware (Bookworm+) gegenüber /boot (älter).
Stellt sicher, dass dtoverlay=dwc2,dr_mode=otg unter einem [all]-Block in config.txt aktiv ist. Die Standardeinstellungen des Raspberry Pi Imagers setzen diese Zeile in einen [cm5]-Filter, der auf dem Pi Zero 2 W nicht greift; der Installer fügt einen mit Sentinel markierten Override hinzu, damit erneute Ausführungen ihn nicht duplizieren.
Stellt sicher, dass modules-load=dwc2 in cmdline.txt steht.
Warnt, wenn g_ether noch in cmdline.txt vorhanden ist (es entzieht libcomposite die UDC und bricht den Gadget-Modus).
Installiert die systemd-Unit unter /etc/systemd/system/badusb.service.
Installiert die udev-Regel unter /etc/udev/rules.d/99-badusb-hidg.rules, sodass /dev/hidg0 von der Gruppe plugdev beschreibbar ist.
Fügt den Benutzer pi zur Gruppe plugdev hinzu.
Erstellt /var/badusb/ für das Massenspeicher-Backing-Image.

Täglicher Betrieb

# Start / stop / restart
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # safe to do while plugged in

# Watch live
journalctl -u badusb -f

# Disable autostart on boot
sudo systemctl disable badusb

Pi-Zero-2W-Bad-USB

Beliebteste