Raspberry Pi Zero 2 W BadUSB HID Toolkit

Uma plataforma de ataque BadUSB / HID programável construída em um Raspberry Pi Zero 2 W. O Pi se enumera como um dispositivo USB composto (teclado mais um volume de armazenamento em massa opcional somente leitura) e executa payloads no estilo Ducky-Script contra o host no qual está conectado. Projetado para engajamentos autorizados de red team, testes de penetração e CTFs.

⚠️ Aviso legal. Use apenas em sistemas que você possui ou para os quais possui permissão explícita por escrito para testar. Acesso não autorizado é ilegal na maioria das jurisdições, e fingir que não sabia não vai ajudar.

Funcionalidades

Payloads de teclas programáveis em um dialeto compatível com Ducky-Script.
Detecção confiável de conexão do host através do estado configured do UDC — sem disparos espúrios de payload na inicialização.
"Reinicialização entre ataques" que realmente funciona no hardware Pi Zero 2 W. Desconecte, reconecte, dispare novamente — sem necessidade de ciclo de energia.
Salvaguardas configuráveis contra loops descontrolados se o dispositivo permanecer conectado: intervalo mínimo entre disparos e limite de taxa de disparos por minuto, ambos sobreponíveis por variáveis de ambiente.
Dispositivo de armazenamento em massa composto opcional apoiado por um arquivo de imagem plana (somente leitura por padrão — expor seu cartão SD ao vivo era a velha fonte de corrupção de sistema de arquivos difícil de depurar).
Layouts de teclado EUA e Reino Unido selecionáveis por payload com LAYOUT.
Variáveis, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, geradores RANDOM_*, STRING_BLOCK / STRINGLN_BLOCK, DEFINE.
Integração com systemd com ExecStop que desmonta o gadget de forma limpa. Sem estado residual do configfs, a reinicialização funciona sem reiniciar.
Permissões gerenciadas por udev para /dev/hidg0 — sem nós de dispositivo com permissão de escrita mundial.
Conjunto de testes pytest com 34 testes para o parser Ducky, executável em qualquer host sem um Pi conectado.
Indicador de status com LED ACT após cada execução de payload.

Como funciona

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

Na inicialização, a unidade systemd badusb.service executa gadget_setup.sh, que usa configfs/libcomposite para compor um gadget USB com uma função de teclado HID e (opcionalmente) um LUN de armazenamento em massa apoiado por um arquivo de imagem plana em /var/badusb/storage.img.
Em seguida, a unidade executa monitor_and_run.py. Ele verifica /sys/class/udc/<udc>/state e aguarda o estado configured — o estado USB-spec que significa que um host enumerou o gadget com sucesso. (Nós não usamos a existência de /dev/hidg0 como sinal: isso é verdade no momento em que o gadget se liga ao UDC na inicialização, independentemente de algo estar conectado.)
Quando o host se conecta, o listener executa run_payload.py, que analisa payload.txt e escreve relatórios HID em /dev/hidg0.
Quando o payload termina, o listener desliga ativamente o gadget do UDC (o Pi Zero 2 W não pode detectar desconexão física via software — veja Notas de arquitetura), dorme um tempo de espera e religa. O dispositivo então aguarda a próxima transição configured.

Hardware

Componente	Nota
Raspberry Pi Zero 2 W	Testado na revisão de hardware de 2026-05. Pi Zero W mais antigo com o driver dwc_otg BCM2835 também funciona em princípio, mas este README assume o 2 W com dwc2.
Cabo micro-USB para USB-A	Ou um adaptador com formato de "pen drive" que permite ao Pi se conectar diretamente a uma porta do host.
Opcional: carregador separado	Se você quiser alimentar o Pi a partir de uma fonte não host para que o listener possa inicializar antes de ser conectado a um alvo (caso contrário, a porta do host fornece a energia).

O Pi Zero 2 W tem duas portas micro-USB:

PWR IN — apenas energia, não expõe linhas de dados USB ao bloco OTG dwc2.
USB — a porta de dados OTG; é aqui que você conecta ao alvo.

Software

Requisito	Por quê
Raspberry Pi OS (Debian Bookworm ou Trixie, 64-bit Lite recomendado)	O script de instalação escreve em `/boot/firmware/...` no Bookworm+ e volta para `/boot/...` em imagens mais antigas.
Python 3	Vem com Pi OS.
`mkfs.vfat`	Para formatar a imagem de apoio do armazenamento em massa na primeira execução. Desative se desabilitar o armazenamento em massa.
Acesso root para configuração	Mexe com systemd, udev e `/boot/firmware/config.txt`.

Instalação

Clone ou copie o repositório para o Pi, então execute o 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

Após a reinicialização, habilite e inicie o serviço:

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

install.sh é idempotente — execute-o novamente sempre que alterar os arquivos do projeto. Ele:

Detecta /boot/firmware (Bookworm+) vs /boot (mais antigo).
Garante que dtoverlay=dwc2,dr_mode=otg esteja ativo sob um bloco [all] em config.txt. Os padrões do Raspberry Pi Imager colocam esta linha dentro de um filtro [cm5] que não se aplica ao Pi Zero 2 W; o instalador anexa uma substituição marcada com sentinela para que execuções repetidas não a dupliquem.
Garante que modules-load=dwc2 esteja em cmdline.txt.
Avisa se g_ether ainda estiver presente em cmdline.txt (ele rouba o UDC do libcomposite e quebra o modo gadget).
Instala a unidade systemd em /etc/systemd/system/badusb.service.
Instala a regra udev em /etc/udev/rules.d/99-badusb-hidg.rules para que /dev/hidg0 seja gravável pelo grupo plugdev.
Adiciona o usuário pi ao grupo plugdev.
Cria /var/badusb/ para a imagem de apoio do armazenamento em massa.

Operação diária

# Iniciar / parar / reiniciar
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # seguro fazer enquanto conectado

# Acompanhar ao vivo
journalctl -u badusb -f

# Desabilitar início automático na inicialização
sudo systemctl disable badusb

# Ajustar temporizações (cria um drop-in de substituição)
sudo systemctl edit badusb
# (cole um bloco [Service] com Environment="BADUSB_REARM_COOLDOWN_S=8" etc.)
sudo systemctl restart badusb

O serviço depende de sys-kernel-config.mount e da presença de um UDC, portanto não pode disparar payloads antes do gadget estar realmente pronto.

Pi-Zero-2W-Bad-USB

Mais Populares