Raspberry Pi Zero 2 W BadUSB HID Toolkit

Una plataforma de ataque BadUSB / HID programable construida sobre una Raspberry Pi Zero 2 W. La Pi se enumera como un dispositivo compuesto USB (teclado más un volumen de almacenamiento masivo de solo lectura opcional) y ejecuta cargas útiles al estilo Ducky-Script contra el host al que está conectada. Diseñada para pruebas de penetración autorizadas, ejercicios de red-team y CTFs.

⚠️ Aviso legal. Úselo solo en sistemas que posea o para los que tenga permiso explícito por escrito. El acceso no autorizado es ilegal en la mayoría de las jurisdicciones, y fingir que no lo sabía no ayudará.

Características

Cargas útiles de pulsaciones de teclas programables en un dialecto compatible con Ducky-Script.
Detección confiable de conexión al host a través del estado configured del UDC — sin disparos de carga útil espurios al arrancar.
"Reinicio entre ataques" que realmente funciona en hardware Pi Zero 2 W. Desconecte, reconecte, dispare de nuevo — sin ciclo de energía.
Salvaguardas configurables contra bucles descontrolados si el dispositivo se deja conectado: intervalo mínimo entre disparos y límite de disparos por minuto, ambos anulables mediante variables de entorno.
Dispositivo de almacenamiento masivo compuesto opcional respaldado por un archivo de imagen plana (solo lectura por defecto — exponer la tarjeta SD en vivo era el antiguo problema difícil de depurar de corrupción del sistema de archivos).
Distribuciones de teclado US y UK seleccionables por carga útil con LAYOUT.
Variables, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, generadores RANDOM_*, STRING_BLOCK / STRINGLN_BLOCK, DEFINE.
Integración con systemd con ExecStop que desmonta el gadget limpiamente. Sin estado residual de configfs, el reinicio funciona sin necesidad de reiniciar el sistema.
Permisos gestionados por udev para /dev/hidg0 — sin nodos de dispositivo con escritura mundial.
Suite de pruebas pytest de 34 pruebas para el parser Ducky, ejecutable en cualquier host sin Pi conectada.
Indicador de estado LED ACT después de cada ejecución de carga útil.

Cómo funciona

+----------------+        Cable USB        +-------------+
|  Raspberry Pi  | ===================>>>  |  PC Host    |
|  Zero 2 W      |   (Pi emula HID +      |  (objetivo) |
|  (este dispositivo)|    unidad opcional)  |             |
+----------------+                         +-------------+
        |
        |  /home/pi/pi-badusb/
        |
        +-- badusb.service ----> monitor_and_run.py
                                   |
                                   |  on `state == configured`:
                                   v
                                 run_payload.py
                                   |
                                   v
                                 /dev/hidg0  (gadget HID USB)

Al arrancar, la unidad systemd badusb.service ejecuta gadget_setup.sh, que utiliza configfs/libcomposite para componer un gadget USB con una función de teclado HID y (opcionalmente) un LUN de almacenamiento masivo respaldado por un archivo de imagen plana en /var/badusb/storage.img.
Luego, la unidad ejecuta monitor_and_run.py. Sondea /sys/class/udc/<udc>/state y espera a configured — el estado de la especificación USB que significa que un host ha enumerado exitosamente el gadget. (NO usamos la existencia de /dev/hidg0 como señal: eso es cierto desde el momento en que el gadget se vincula al UDC en el arranque, independientemente de si hay algo conectado.)
Cuando el host se conecta, el escuchador ejecuta run_payload.py, que analiza payload.txt y escribe informes HID en /dev/hidg0.
Cuando la carga útil finaliza, el escuchador desvincula activamente el gadget del UDC (la Pi Zero 2 W no puede detectar la desconexión física mediante software — consulte Notas de arquitectura), espera un tiempo de enfriamiento y vuelve a vincular. El dispositivo entonces espera la siguiente transición a configured.

Hardware

Componente	Nota
Raspberry Pi Zero 2 W	Probada en la revisión de hardware de 2026-05. La Pi Zero W más antigua con el controlador dwc_otg BCM2835 también funciona en principio, pero este README asume 2 W con dwc2.
Cable micro-USB a USB-A	O un adaptador en formato "stick USB" que permita enchufar la Pi directamente a un puerto host.
Opcional: cargador separado	Si desea alimentar la Pi desde una fuente que no sea el host para que el escuchador pueda arrancar antes de conectarse a un objetivo (de lo contrario, el puerto host suministra la energía).

La Pi Zero 2 W tiene dos puertos micro-USB:

PWR IN — solo alimentación, no expone líneas de datos USB al bloque dwc2 OTG.
USB — el puerto de datos OTG; aquí es donde se conecta al objetivo.

Software

Requisito	Por qué
Raspberry Pi OS (Debian Bookworm o Trixie, 64-bit Lite recomendado)	El script de instalación escribe en `/boot/firmware/...` en Bookworm+ y retrocede a `/boot/...` en imágenes más antiguas.
Python 3	Viene con Pi OS.
`mkfs.vfat`	Para formatear la imagen de respaldo de almacenamiento masivo en la primera ejecución. Deshabilitar si no se usa almacenamiento masivo.
Acceso root para la configuración	Toca systemd, udev y `/boot/firmware/config.txt`.

Instalación

Clone o copie el repositorio en la Pi, luego ejecute el instalador:

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

Después del reinicio, habilite e inicie el servicio:

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

install.sh es idempotente — vuelva a ejecutarlo cada vez que cambie archivos del proyecto. Él:

Detecta /boot/firmware (Bookworm+) vs /boot (más antiguo).
Asegura que dtoverlay=dwc2,dr_mode=otg esté activo bajo un bloque [all] en config.txt. Los valores predeterminados de Raspberry Pi Imager colocan esta línea dentro de un filtro [cm5] que no aplica en Pi Zero 2 W; el instalador agrega una anulación marcada para que las re-ejecuciones no la dupliquen.
Asegura que modules-load=dwc2 esté en cmdline.txt.
Advierte si g_ether sigue presente en cmdline.txt (roba el UDC de libcomposite y rompe el modo gadget).
Instala la unidad systemd en /etc/systemd/system/badusb.service.
Instala la regla udev en /etc/udev/rules.d/99-badusb-hidg.rules para que /dev/hidg0 sea escribible por el grupo plugdev.
Agrega el usuario pi a plugdev.
Crea /var/badusb/ para la imagen de respaldo de almacenamiento masivo.

Operación diaria

# Iniciar / detener / reiniciar
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # seguro hacerlo mientras está conectado

# Ver en vivo
journalctl -u badusb -f

# Deshabilitar inicio automático al arrancar
sudo systemctl disable badusb

# Ajustar tiempos (crea un drop-in de anulación)
sudo systemctl edit badusb
# (pegue un bloque [Service] con Environment="BADUSB_REARM_COOLDOWN_S=8" etc.)
sudo systemctl restart badusb

Pi-Zero-2W-Bad-USB

Más Populares