Kit de Menace BadUSB HID pour Raspberry Pi Zero 2 W

Une plateforme programmable d'attaque BadUSB / HID construite sur un Raspberry Pi Zero 2 W. Le Pi s'énumère en tant que périphérique composite USB (clavier plus un volume de stockage de masse optionnel en lecture seule) et exécute des charges utiles de style Ducky-Script sur l'hôte auquel il est branché. Conçu pour des engagements d'équipe rouge autorisés, des tests de pénétration et des CTF.

⚠️ Avis légal. Utilisez uniquement sur des systèmes dont vous êtes propriétaire ou pour lesquels vous disposez d'une autorisation écrite explicite de test. L'accès non autorisé est illégal dans la plupart des juridictions, et faire semblant de l'ignorer ne vous aidera pas.

Fonctionnalités

Charges utiles de frappe programmables dans un dialecte compatible Ducky-Script.
Détection fiable de l'attachement hôte via l'état configured de l'UDC — pas de déclenchement intempestif de charge utile au démarrage.
"Réinitialisation entre les attaques" qui fonctionne réellement sur le matériel Pi Zero 2 W. Débranchez, rebranchez, tirez à nouveau — pas de cycle d'alimentation.
Protections configurables contre les boucles incontrôlées si l'appareil reste branché : intervalle minimum par tir et limite de tirs par minute, tous deux modifiables via des variables d'environnement.
Gadget de stockage de masse composite optionnel basé sur un fichier image plat (lecture seule par défaut — exposer votre carte SD live était l'ancien piège à corruption de système de fichiers difficile à déboguer).
Dispositions de clavier US et UK sélectionnables par charge utile avec LAYOUT.
Variables, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, générateurs RANDOM_*, STRING_BLOCK / STRINGLN_BLOCK, DEFINE.
Intégration systemd avec ExecStop qui démonte proprement le gadget. Pas d'état résiduel de configfs, le redémarrage fonctionne sans redémarrer.
Permissions gérées par udev pour /dev/hidg0 — pas de nœuds de périphérique accessibles en écriture par tout le monde.
Suite de tests pytest de 34 tests pour l'analyseur Ducky, exécutable sur n'importe quel hôte sans Pi connecté.
Indicateur d'état via la LED ACT après chaque exécution de charge utile.

Fonctionnement

+----------------+        Câble USB        +-------------+
|  Raspberry Pi  | ===================>>>  |  PC hôte    |
|  Zero 2 W      |   (Pi émule HID +       |  (cible)    |
|  (cet appareil)|    optionnel lecteur)   |             |
+----------------+                         +-------------+
        |
        |  /home/pi/pi-badusb/
        |
        +-- badusb.service ----> monitor_and_run.py
                                   |
                                   |  sur `state == configured` :
                                   v
                                 run_payload.py
                                   |
                                   v
                                 /dev/hidg0  (gadget HID USB)

Au démarrage, l'unité systemd badusb.service exécute gadget_setup.sh, qui utilise configfs/libcomposite pour composer un gadget USB avec une fonction clavier HID et (optionnellement) un LUN de stockage de masse basé sur un fichier image plat à /var/badusb/storage.img.
L'unité exécute ensuite monitor_and_run.py. Il interroge /sys/class/udc/<udc>/state et attend configured — l'état USB-spec qui signifie qu'un hôte a énuméré avec succès le gadget. (Nous n'utilisons pas l'existence de /dev/hidg0 comme signal : celui-ci est vrai dès que le gadget se lie à l'UDC au démarrage, qu'un câble soit branché ou non.)
Lorsque l'hôte s'attache, l'écouteur exécute run_payload.py, qui analyse payload.txt et écrit des rapports HID vers /dev/hidg0.
Lorsque la charge utile se termine, l'écouteur délie activement le gadget de l'UDC (le Pi Zero 2 W ne peut pas détecter une déconnexion physique par logiciel — voir Notes d'architecture), attend un délai de refroidissement, puis relie. L'appareil attend ensuite la prochaine transition vers configured.

Matériel

Composant	Remarque
Raspberry Pi Zero 2 W	Testé sur révision matérielle 2026-05. Les anciens Pi Zero W avec le pilote dwc_otg BCM2835 fonctionnent également en principe, mais ce README suppose un Zero 2 W avec dwc2.
Câble micro-USB vers USB-A	Ou un adaptateur au format "clé USB" qui permet de brancher le Pi directement sur un port hôte.
Optionnel : chargeur séparé	Si vous voulez alimenter le Pi depuis une source non-hôte afin que l'écouteur puisse démarrer avant d'être branché sur une cible (sinon le port hôte fournit l'alimentation).

Le Pi Zero 2 W possède deux ports micro-USB :

PWR IN — alimentation uniquement, n'expose pas les lignes de données USB au bloc dwc2 OTG.
USB — le port de données OTG ; c'est là que vous branchez sur la cible.

Logiciel

Prérequis	Pourquoi
Raspberry Pi OS (Debian Bookworm ou Trixie, 64-bit Lite recommandé)	Le script d'installation écrit dans `/boot/firmware/...` sur Bookworm+ et utilise `/boot/...` sur les images plus anciennes.
Python 3	Fourni avec Pi OS.
`mkfs.vfat`	Pour formater l'image de stockage de masse lors de la première exécution. Désactivez si vous désactivez le stockage de masse.
Accès root pour l'installation	Touche systemd, udev et `/boot/firmware/config.txt`.

Installation

Clonez ou copiez le dépôt dans le Pi, puis exécutez l'installateur :

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

Après redémarrage, activez et démarrez le service :

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

install.sh est idempotent — réexécutez-le à chaque modification des fichiers du projet. Il :

Détecte /boot/firmware (Bookworm+) vs /boot (plus ancien).
Vérifie que dtoverlay=dwc2,dr_mode=otg est actif sous un bloc [all] dans config.txt. Les valeurs par défaut de Raspberry Pi Imager placent cette ligne dans un filtre [cm5] qui ne s'applique pas sur Pi Zero 2 W ; l'installateur ajoute une surcouche marquée par un repère pour que les réexécutions ne la dupliquent pas.
Vérifie que modules-load=dwc2 est présent dans cmdline.txt.
Avertit si g_ether est toujours présent dans cmdline.txt (il vole l'UDC à libcomposite et casse le mode gadget).
Installe l'unité systemd dans /etc/systemd/system/badusb.service.
Installe la règle udev dans /etc/udev/rules.d/99-badusb-hidg.rules pour que /dev/hidg0 soit accessible en écriture par le groupe plugdev.
Ajoute l'utilisateur pi au groupe plugdev.
Crée /var/badusb/ pour l'image de stockage de masse.

Utilisation quotidienne

# Démarrer / arrêter / redémarrer
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # sûr à faire pendant que le câble est branché

# Voir les logs en direct
journalctl -u badusb -f

# Désactiver le démarrage automatique au boot
sudo systemctl disable badusb

# Régler les temporisations (crée un fichier de remplacement)
sudo systemctl edit badusb
# (collez un bloc [Service] avec Environment="BADUSB_REARM_COOLDOWN_S=8" etc.)
sudo systemctl restart badusb

Pi-Zero-2W-Bad-USB

Populaires