eBPF-hid_guard

eBPF-hid_guard

См. раздел Почему этот репозиторий архивирован ниже.

Монитор безопасности на уровне ядра Linux для обнаружения и блокировки атак с внедрением HID (Rubber Ducky, O.MG Cable, эмуляторы клавиатуры на ESP32) с использованием eBPF HID-BPF struct_ops.

Что это делает

Вредоносные HID-устройства эмулируют клавиатуры и внедряют нажатия клавиш значительно быстрее, чем любой человек-машинист. Этот инструмент обнаруживает такую временную аномалию и отключает вредоносное устройство от драйвера HID ядра до завершения атаки.

При запуске инструмент делает снимок всех текущих подключенных HID-устройств и игнорирует их — отслеживаются только новые подключенные устройства. Поддерживаются как USB-, так и Bluetooth-HID-устройства.

Структура веток

main — Рабочий прототип

Функциональный сквозной конвейер, протестированный на эмуляторе клавиатуры на ESP32:

• Создает снимок существующих устройств при запуске; игнорирует их
• Параллельные потоки обнаружения USB и BLE — первое устройство, обнаружившее новое устройство, выигрывает
• Подключает программу HID-BPF struct_ops к обнаруженному устройству
• Сторона BPF захватывает сырые байты HID-отчета, временную метку, идентификатор поставщика/продукта/шину через кольцевой буфер
• Пользовательское пространство вычисляет дельты между нажатиями клавиш, отслеживает счетчик подозрений и отключает устройство через sysfs при превышении порога

Известные ограничения, вызвавшие переписывание:

• Размер отчета жестко закодирован (8 или 9 байт, только для стандартных загрузочных протоколов клавиатуры) — не работает с нестандартными дескрипторами
• Отсутствует разбор дескриптора HID-отчета — тип устройства предполагается, а не проверяется; возможны ложные срабатывания на мышах, тачпадах или составных устройствах
• Логика обнаружения полностью находится в пользовательском пространстве — BPF используется только как канал сырых данных
• hid_id получается из номера младшего устройства sysfs, который нестабилен при перезагрузках

v0.1 — Чистый переписывание (остановлено)

Переносимая основа, созданная до переподключения BPF-уровня:

• Перечисляет все HID-устройства через /sys/bus/hid/devices/
• Читает и выводит в hex сырые дескрипторы отчетов из sysfs
• Парсер дескрипторов HID-отчетов в процессе (hid_desc_parse.c) — идентификация типа устройства не завершена
• Чисто по памяти (проверено с помощью AddressSanitizer)

Почему этот репозиторий архивирован

Обе ветки столкнулись с одной и той же стеной: HID-BPF работает с сырыми байтовыми массивами, поэтому весь разбор дескрипторов и проверка типа устройства должны находиться в пользовательском пространстве, независимо от того, как разделена логика обнаружения. Вместо того чтобы продолжать строить эту инфраструктуру с нуля, я перешел на [udev-hid-bpf].

Что это делает

Вредоносные HID-устройства эмулируют клавиатуры и внедряют нажатия клавиш значительно быстрее, чем любой человек-машинист. Этот инструмент обнаруживает такую временную аномалию и отключает вредоносное устройство от драйвера HID ядра до завершения атаки.

При запуске инструмент делает снимок всех текущих подключенных HID-устройств и игнорирует их — отслеживаются только новые подключенные устройства. Поддерживаются как USB-, так и Bluetooth-HID-устройства.

Структура веток

main — Рабочий прототип

Функциональный сквозной конвейер, протестированный на эмуляторе клавиатуры на ESP32:

• Создает снимок существующих устройств при запуске; игнорирует их
• Параллельные потоки обнаружения USB и BLE — первое устройство, обнаружившее новое устройство, выигрывает
• Подключает программу HID-BPF struct_ops к обнаруженному устройству
• Сторона BPF захватывает сырые байты HID-отчета, временную метку, идентификатор поставщика/продукта/шину через кольцевой буфер
• Пользовательское пространство вычисляет дельты между нажатиями клавиш, отслеживает счетчик подозрений и отключает устройство через sysfs при превышении порога

Известные ограничения, вызвавшие переписывание:

• Размер отчета жестко закодирован (8 или 9 байт, только для стандартных загрузочных протоколов клавиатуры) — не работает с нестандартными дескрипторами
• Отсутствует разбор дескриптора HID-отчета — тип устройства предполагается, а не проверяется; возможны ложные срабатывания на мышах, тачпадах или составных устройствах
• Логика обнаружения полностью находится в пользовательском пространстве — BPF используется только как канал сырых данных
• hid_id получается из номера младшего устройства sysfs, который нестабилен при перезагрузках

v0.1 — Чистый переписывание (активная разработка)

Переносимая основа, создаваемая до переподключения BPF-уровня:

• Перечисляет все HID-устройства через /sys/bus/hid/devices/
• Читает и выводит в hex сырые дескрипторы отчетов из sysfs
• Парсер дескрипторов HID-отчетов в процессе (hid_desc_parse.c) — будет определять тип устройства перед подключением
• Чисто по памяти (проверено с помощью AddressSanitizer)

Предполагаемая архитектура

┌─────────────────────────────────────────────────────┐
│                    Пользовательское пространство      │
│                                                      │
│  udev-монитор → разбор дескриптора → клавиатура?     │
│       ↓                                              │
│  заполнение конфигурационных карт BPF (пороги,       │
│  информация об устройстве)                           │
│       ↓                                              │
│  подключение HID-BPF struct_ops к hid_id             │
│       ↓                                              │
│  потребитель кольцевого буфера → отключение через   │
│  sysfs при атаке                                     │
└──────────────────────────┬──────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│                  BPF (сторона ядра)                   │
│                                                      │
│  hid_device_event → временные вычисления             │
│  (онлайн-дисперсия Уэлфорда, фиксированная точка)    │
│  → карты временных меток на клавишу                 │
│  → отправка в кольцевой буфер при аномалии          │
└─────────────────────────────────────────────────────┘

Логика обнаружения переходит в BPF. Пользовательское пространство обрабатывает разбор дескрипторов, заполнение конфигурационных карт и реакцию отключения. Окно перечисления между подключением устройства и подключением BPF является документированным, ограниченным ограничением — реальные инструменты внедрения HID включают преднамеренные задержки после перечисления, в которые это окно укладывается.

Требования

• Ядро Linux ≥ 6.3 (HID-BPF struct_ops стабильно)
• Заголовочные файлы разработки libbpf
• LLVM/Clang (для компиляции BPF)
• Заголовочные файлы разработки libelf и zlib
• Права root

Сборка

make

Использование

# Автообнаружение: подключите или сопрягите устройство, когда будет предложено
sudo ./hid_guard

# Ручное переопределение с известным hid_id
sudo ./hid_guard <hid_id>

# Список доступных HID-устройств
ls /sys/bus/hid/devices/

Настраиваемые параметры обнаружения (main.c)

Статус

Тестирование

ESP32-S2 использовался для передачи нажатий клавиш по BLE. Далее планируется тестирование на аппаратных устройствах, таких как rubber ducky или ESP32-S3, с нацеливанием на USB-порты.

Лицензия

GPL v2