Toolkit BadUSB HID per Raspberry Pi Zero 2 W

Una piattaforma di attacco BadUSB / HID programmabile basata su un Raspberry Pi Zero 2 W. Il Pi si presenta come un dispositivo USB composito (tastiera più un volume di archiviazione di massa di sola lettura opzionale) ed esegue payload in stile Ducky-Script sull'host a cui è collegato. Progettata per attività di red team autorizzate, test di penetrazione e CTF.

⚠️ Nota legale. Utilizzare solo su sistemi di propria proprietà o per i quali si dispone di esplicita autorizzazione scritta al test. L'accesso non autorizzato è illegale nella maggior parte delle giurisdizioni, e fingere di non saperlo non aiuta.

Funzionalità

Payload di sequenze di tasti programmabili in un dialetto compatibile con Ducky-Script.
Rilevamento affidabile del collegamento dell'host tramite lo stato configured della UDC — nessun payload spurio viene eseguito all'avvio.
"Reset tra gli attacchi" che funziona realmente sull'hardware Pi Zero 2 W. Scollega, ricollega, esegui di nuovo — nessun ciclo di alimentazione.
Protezioni configurabili contro i loop incontrollati se il dispositivo viene lasciato collegato: intervallo minimo tra le esecuzioni e un limite di esecuzioni al minuto, entrambi sovrascrivibili tramite variabili d'ambiente.
Gadget composito di archiviazione di massa opzionale basato su un file immagine flat (sola lettura per impostazione predefinita — esporre la scheda SD in uso era la vecchia trappola di corruzione del file system difficile da debuggare).
Layout di tastiera US e UK selezionabili per payload con LAYOUT.
Variabili, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, generatori RANDOM_*, STRING_BLOCK / STRINGLN_BLOCK, DEFINE.
Integrazione con systemd con ExecStop che smonta il gadget in modo pulito. Nessuno stato configfs residuo, il riavvio del servizio funziona senza riavviare il sistema.
Permessi gestiti da udev per /dev/hidg0 — nessun nodo di dispositivo scrivibile da tutti.
Suite pytest di 34 test per il parser Ducky, eseguibile su qualsiasi host senza alcun Pi collegato.
Indicatore di stato sul LED ACT dopo ogni esecuzione del payload.

Come funziona

+----------------+        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)

All'avvio, l'unità systemd badusb.service esegue gadget_setup.sh, che usa configfs/libcomposite per comporre un gadget USB con una funzione di tastiera HID e (opzionalmente) una LUN di archiviazione di massa basata su un file immagine flat in /var/badusb/storage.img.
L'unità esegue quindi monitor_and_run.py. Sonda /sys/class/udc/<udc>/state e attende configured — lo stato della specifica USB che indica che un host ha enumerato correttamente il gadget. (Non usiamo l'esistenza di /dev/hidg0 come segnale: tale condizione è vera nel momento in cui il gadget si lega alla UDC all'avvio, indipendentemente dal fatto che qualcosa sia collegato.)
Quando l'host si collega, il listener esegue run_payload.py, che analizza payload.txt e scrive i report HID su /dev/hidg0.
Quando il payload termina, il listener slega attivamente il gadget dalla UDC (il Pi Zero 2 W non può rilevare la disconnessione fisica via software — vedi Note sull'architettura), attende un tempo di raffreddamento e rilega. Il dispositivo attende quindi la successiva transizione a configured.

Hardware

Componente	Nota
Raspberry Pi Zero 2 W	Testato sulla revisione hardware del 2026-05. Anche il vecchio Pi Zero W con il driver BCM2835 dwc_otg funziona in linea di principio, ma questo README presuppone il 2 W con dwc2.
Cavo micro-USB verso USB-A	Oppure un adattatore con fattore di forma "chiavetta USB" che permette al Pi di collegarsi direttamente a una porta dell'host.
Opzionale: caricatore separato	Se si vuole alimentare il Pi da una sorgente non-host così che il listener possa avviarsi prima di essere collegato a un target (in caso contrario, la porta dell'host fornisce l'alimentazione).

Il Pi Zero 2 W ha due porte micro-USB:

PWR IN — solo alimentazione, non espone le linee dati USB al blocco dwc2 OTG.
USB — la porta dati OTG; è qui che ci si collega al target.

Software

Requisito	Motivo
Raspberry Pi OS (Debian Bookworm o Trixie, Lite 64-bit consigliato)	Lo script di installazione scrive in `/boot/firmware/...` su Bookworm+ e ripiega su `/boot/...` nelle immagini più vecchie.
Python 3	Incluso con Pi OS.
`mkfs.vfat`	Per formattare l'immagine di supporto dell'archiviazione di massa al primo avvio. Da saltare se si disabilita l'archiviazione di massa.
Accesso root per l'installazione	Modifica systemd, udev e `/boot/firmware/config.txt`.

Installazione

Clona o copia il repository nel Pi, quindi esegui l'installer:

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

Dopo il riavvio, abilita e avvia il servizio:

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

install.sh è idempotente — rieseguilo ogni volta che modifichi i file del progetto. Esso:

Rileva /boot/firmware (Bookworm+) rispetto a /boot (più vecchio).
Garantisce che dtoverlay=dwc2,dr_mode=otg sia attivo in un blocco [all] in config.txt. Le impostazioni predefinite di Raspberry Pi Imager mettono questa riga dentro un filtro [cm5] che non si applica al Pi Zero 2 W; l'installer aggiunge un override contrassegnato da sentinella così che le riesecuzioni non lo duplichino.
Garantisce che modules-load=dwc2 sia presente in cmdline.txt.
Avvisa se g_ether è ancora presente in cmdline.txt (ruba la UDC a libcomposite e rompe la modalità gadget).
Installa l'unità systemd in /etc/systemd/system/badusb.service.
Installa la regola udev in /etc/udev/rules.d/99-badusb-hidg.rules così che /dev/hidg0 sia scrivibile dal gruppo plugdev.
Aggiunge l'utente pi al gruppo plugdev.
Crea /var/badusb/ per l'immagine di supporto dell'archiviazione di massa.

Operazioni quotidiane

# 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

# Tune timings (creates an override drop-in)
sudo systemctl edit badusb
# (paste an [Service] block with Environment="BADUSB_REARM_COOLDOWN_S=8" etc)
sudo systemctl restart badusb

Pi-Zero-2W-Bad-USB

Più Popolari