Raspberry Pi Zero 2 W BadUSB HID Toolkit

Программируемая платформа для атак BadUSB / HID, построенная на Raspberry Pi Zero 2 W. Pi эмулирует составное USB-устройство (клавиатуру плюс опциональный доступный только для чтения том массового хранения) и выполняет пейлоады в стиле Ducky-Script на хосте, к которому она подключена. Предназначена для авторизованных заданий red-команд, тестирования на проникновение и CTF.

⚠️ Юридическое уведомление. Используйте только на системах, которыми вы владеете или на которые имеете явное письменное разрешение на тестирование. Несанкционированный доступ незаконен в большинстве юрисдикций, и притворство, что вы не знали, не поможет.

Возможности

Программируемые пейлоады нажатий клавиш в диалекте, совместимом с Ducky-Script.
Надёжное обнаружение подключения хоста через состояние UDC configured — никаких ложных запусков пейлоада при загрузке.
«Сброс между атаками», который действительно работает на оборудовании Pi Zero 2 W. Отключи, подключи снова, запусти — без перезагрузки.
Настраиваемые меры защиты от бесконечных циклов, если устройство остаётся подключённым: минимальный интервал между срабатываниями и ограничение частоты срабатываний в минуту, оба переопределяются переменными окружения.
Опциональное составное устройство массового хранения на основе плоского образа файла (по умолчанию только чтение — открытие вашей живой SD-карты было старой, трудно отлаживаемой ловушкой повреждения файловой системы).
Раскладки клавиатуры US и UK, выбираемые для каждого пейлоада с помощью LAYOUT.
Переменные, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, генераторы RANDOM_*, STRING_BLOCK / STRINGLN_BLOCK, DEFINE.
Интеграция с systemd с ExecStop, который корректно отключает гаджет. Никаких остаточных состояний configfs, перезапуск работает без перезагрузки.
Управление правами через udev для /dev/hidg0 — никаких узлов устройств, доступных на запись всем.
Набор из 34 тестов pytest для парсера Ducky, запускаемый на любом хосте без подключённого Pi.
Индикатор состояния на ACT LED после каждого выполнения пейлоада.

Как это работает

+----------------+        USB cable        +-------------+
|  Raspberry Pi  | ===================>>>  |  Host PC    |
|  Zero 2 W      |   (Pi эмулирует HID +  |  (целевой)  |
|  (это устройство)|    опциональный диск)  |             |
+----------------+                         +-------------+
        |
        |  /home/pi/pi-badusb/
        |
        +-- badusb.service ----> monitor_and_run.py
                                   |
                                   |  при `state == configured`:
                                   v
                                 run_payload.py
                                   |
                                   v
                                 /dev/hidg0  (USB HID гаджет)

При загрузке systemd-юнит badusb.service запускает gadget_setup.sh, который с помощью configfs/libcomposite собирает USB-гаджет с функцией HID-клавиатуры и (опционально) LUN массового хранения на основе плоского образа файла в /var/badusb/storage.img.
Затем юнит запускает monitor_and_run.py. Он опрашивает /sys/class/udc/<udc>/state и ждёт configured — состояние USB-спецификации, означающее, что хост успешно перечислил гаджет. (Мы не используем существование /dev/hidg0 как сигнал: оно истинно в момент привязки гаджета к UDC при загрузке, независимо от того, что-либо подключено или нет.)
Когда хост подключается, слушатель запускает run_payload.py, который разбирает payload.txt и записывает HID-отчёты в /dev/hidg0.
Когда пейлоад завершается, слушатель активно отвязывает гаджет от UDC (Pi Zero 2 W не может обнаружить физическое отключение программно — см. Заметки по архитектуре), ждёт время остывания и повторно привязывает. Затем устройство ждёт следующего перехода в configured.

Аппаратное обеспечение

Компонент	Примечание
Raspberry Pi Zero 2 W	Протестировано на ревизии оборудования 2026-05. Более старые Pi Zero W с драйвером BCM2835 dwc_otg также работают в принципе, но этот README предполагает 2 W с dwc2.
Кабель micro-USB → USB-A	Или переходник в форм-факторе «USB-флешки», позволяющий подключить Pi напрямую к порту хоста.
Опционально: отдельное зарядное устройство	Если вы хотите питать Pi от источника, отличного от хоста, чтобы слушатель мог загрузиться до подключения к целевому устройству (в противном случае питание подаётся от порта хоста).

Pi Zero 2 W имеет два micro-USB порта:

PWR IN — только питание, не выставляет линии данных USB на блок OTG dwc2.
USB — порт данных OTG; сюда подключаетесь к целевому устройству.

Программное обеспечение

Требование	Зачем
Raspberry Pi OS (Debian Bookworm или Trixie, рекомендуется 64-битная Lite)	Скрипт установки пишет в `/boot/firmware/...` на Bookworm+ и делает откат к `/boot/...` на старых образах.
Python 3	Поставляется с Pi OS.
`mkfs.vfat`	Для форматирования образа массового хранения при первом запуске. Отключите, если массовое хранение не используется.
Доступ root для настройки	Затрагивает systemd, udev и `/boot/firmware/config.txt`.

Установка

Клонируйте или скопируйте репозиторий на Pi, затем запустите установщик:

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

После перезагрузки включите и запустите сервис:

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

install.sh идемпотентен — запускайте его повторно при изменении файлов проекта. Он:

Определяет /boot/firmware (Bookworm+) vs /boot (старые версии).
Убеждается, что dtoverlay=dwc2,dr_mode=otg активен под блоком [all] в config.txt. По умолчанию Raspberry Pi Imager помещает эту строку внутрь фильтра [cm5], который не применяется на Pi Zero 2 W; установщик добавляет переопределение с меткой, чтобы повторные запуски не дублировали её.
Убеждается, что modules-load=dwc2 присутствует в cmdline.txt.
Предупреждает, если g_ether всё ещё присутствует в cmdline.txt (он перехватывает UDC у libcomposite и ломает режим гаджета).
Устанавливает systemd-юнит в /etc/systemd/system/badusb.service.
Устанавливает правило udev в /etc/udev/rules.d/99-badusb-hidg.rules, чтобы /dev/hidg0 был доступен для записи группе plugdev.
Добавляет пользователя pi в группу plugdev.
Создаёт /var/badusb/ для образа массового хранения.

Ежедневная эксплуатация

# Запуск / остановка / перезапуск
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # безопасно, даже если подключено

# Просмотр лога в реальном времени
journalctl -u badusb -f

# Отключение автозапуска при загрузке
sudo systemctl disable badusb

# Настройка таймингов (создаёт переопределение drop-in)
sudo systemctl edit badusb
# (вставьте блок [Service] с Environment="BADUSB_REARM_COOLDOWN_S=8" и т.д.)
sudo systemctl restart badusb

Сервис зависит от sys-kernel-config.mount и наличия UDC, поэтому он не сможет запустить пейлоады, пока гаджет не будет действительно готов.

Pi-Zero-2W-Bad-USB

Популярное