fusion1110/ebpf-hid_guardDetector de ataques de injeção HID no espaço do kernel Linux usando eBPF. Monitora dispositivos HID USB e Bluetooth em busca de temporização anômala de teclas e desvincula automaticamente dispositivos maliciosos antes da conclusão do ataque.
Veja Por que isso foi arquivado abaixo.
Um monitor de segurança no espaço do kernel Linux para detectar e bloquear ataques de injeção HID (Rubber Ducky, Cabo O.MG, emuladores de teclado baseados em ESP32) usando eBPF HID-BPF struct_ops.
Dispositivos HID maliciosos emulam teclados e injetam toques de tecla muito mais rápido do que qualquer digitador humano. Esta ferramenta detecta essa anomalia de tempo e desvincula o dispositivo ofensivo do driver HID do kernel antes que o ataque seja concluído.
Na inicialização, a ferramenta tira um instantâneo de todos os dispositivos HID atualmente conectados e os ignora — apenas dispositivos recém-conectados são monitorados. Ela suporta dispositivos HID USB e Bluetooth.
main — Prova de Conceito FuncionalPipeline funcional de ponta a ponta, testado contra um emulador de teclado baseado em ESP32:
struct_ops ao dispositivo descobertoLimitações conhecidas que motivaram a reescrita:
hid_id derivado do número menor do sysfs, que não é estável entre reinicializaçõesv0.1 — Reescrita Limpa (Suspensa)Base portátil construída antes de reconectar a camada BPF:
/sys/bus/hid/devices/hid_desc_parse.c) — identificação do tipo de dispositivo não concluídaAmbos os ramos esbarraram no mesmo obstáculo: o HID-BPF opera em arrays de bytes brutos, portanto, toda a análise de descritores e verificação de tipo de dispositivo tem que ficar no espaço do usuário, independentemente de como a lógica de detecção é dividida. Em vez de continuar construindo essa estrutura do zero, migrei para [udev-hid-bpf].
Dispositivos HID maliciosos emulam teclados e injetam toques de tecla muito mais rápido do que qualquer digitador humano. Esta ferramenta detecta essa anomalia de tempo e desvincula o dispositivo ofensivo do driver HID do kernel antes que o ataque seja concluído.
Na inicialização, a ferramenta tira um instantâneo de todos os dispositivos HID atualmente conectados e os ignora — apenas dispositivos recém-conectados são monitorados. Ela suporta dispositivos HID USB e Bluetooth.
main — Prova de Conceito FuncionalPipeline funcional de ponta a ponta, testado contra um emulador de teclado baseado em ESP32:
struct_ops ao dispositivo descobertoLimitações conhecidas que motivaram a reescrita:
hid_id derivado do número menor do sysfs, que não é estável entre reinicializaçõesv0.1 — Reescrita Limpa (Desenvolvimento Ativo)Base portátil sendo construída antes de reconectar a camada BPF:
/sys/bus/hid/devices/hid_desc_parse.c) — irá identificar o tipo de dispositivo antes de anexar┌─────────────────────────────────────────────────────┐
│ Userspace │
│ │
│ udev monitor → descriptor parse → keyboard? │
│ ↓ │
│ populate BPF config maps (thresholds, device info) │
│ ↓ │
│ attach HID-BPF struct_ops to hid_id │
│ ↓ │
│ ring buffer consumer → sysfs unbind on attack │
└──────────────────────────┬──────────────────────────┘
│
┌──────────────────────────▼──────────────────────────┐
│ BPF (kernel side) │
│ │
│ hid_device_event → timing math (Welford's online │
│ variance, fixed-point) → per-key timestamp maps │
│ → ring buffer submit on anomaly │
└─────────────────────────────────────────────────────┘
A lógica de detecção se move para o BPF. O espaço do usuário lida com a análise de descritores, a população de mapas de configuração e a resposta de desvinculação. A janela de enumeração entre a conexão do dispositivo e a anexação do BPF é uma limitação documentada e limitada — ferramentas reais de injeção HID incluem atrasos deliberados pós-enumeração que se enquadram nessa janela.
libbpflibelf e zlibmake
# Auto-detect: plug in or pair the device when prompted
sudo ./hid_guard
# Manual override with known hid_id
sudo ./hid_guard <hid_id>
# List available HID devices
ls /sys/bus/hid/devices/
main.c)| Parâmetro | Padrão | Significado |
|---|---|---|
ATTACK_MAX_MS | 5 ms | Intervalo entre toques de tecla indicando injeção |
HUMAN_MIN_MS | 30 ms | Intervalo mínimo para digitação humana |
ALERT_THRESHOLD | 3 | Eventos suspeitos consecutivos antes do bloqueio |
| Componente | Estado |
|---|---|
| Enumeração de dispositivos | Concluído |
| Leitura do descritor de relatório | Concluído |
| Analisador de descritor (identificação de teclado) | Em andamento |
| População de mapa de configuração BPF | Planejado |
| Anexação HID-BPF struct_ops | Concluído (ramo main) |
| Detecção de temporização (variância de Welford, lado BPF) | Planejado |
| Bloqueio de desvinculação via sysfs | Concluído (ramo main) |
O ESP32-S2 foi usado para transmissão de toques de tecla via BLE. Em seguida, teste com hardware como rubber ducky ou ESP32-S3, visando portas USB.
GPL v2