eBPF-hid_guard

eBPF-hid_guard

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.

O que isso faz

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.

Estrutura de Ramificação

main — Prova de Conceito Funcional

Pipeline funcional de ponta a ponta, testado contra um emulador de teclado baseado em ESP32:

• Tira instantâneo dos dispositivos pré-existentes na inicialização; os ignora
• Threads paralelas de descoberta USB e BLE — a primeira a detectar um novo dispositivo vence
• Anexa um programa HID-BPF struct_ops ao dispositivo descoberto
• O lado BPF captura bytes brutos do relatório HID, timestamp, fornecedor/produto/barramento via ring buffer
• O espaço do usuário calcula deltas entre toques de tecla, rastreia um contador de suspeita e desvincula o dispositivo via sysfs quando o limite é ultrapassado

Limitações conhecidas que motivaram a reescrita:

• Tamanho do relatório codificado em 8 ou 9 bytes (apenas teclados de protocolo de inicialização padrão) — quebra em descritores não padrão
• Sem análise do descritor de relatório HID — o tipo de dispositivo é assumido, não verificado; irá disparar erroneamente em mouses, touchpads ou dispositivos compostos
• A lógica de detecção reside inteiramente no espaço do usuário — o BPF é usado apenas como um pipe de dados brutos
• hid_id derivado do número menor do sysfs, que não é estável entre reinicializações

v0.1 — Reescrita Limpa (Suspensa)

Base portátil construída antes de reconectar a camada BPF:

• Enumera todos os dispositivos HID via /sys/bus/hid/devices/
• Lê e exibe em hex dump os descritores de relatório brutos do sysfs
• Analisador de descritor de relatório HID em andamento (hid_desc_parse.c) — identificação do tipo de dispositivo não concluída
• Limpeza de memória (verificada com AddressSanitizer)

Por que isso foi arquivado

Ambos 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].

O que isso faz

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.

Estrutura de Ramificação

main — Prova de Conceito Funcional

Pipeline funcional de ponta a ponta, testado contra um emulador de teclado baseado em ESP32:

• Tira instantâneo dos dispositivos pré-existentes na inicialização; os ignora
• Threads paralelas de descoberta USB e BLE — a primeira a detectar um novo dispositivo vence
• Anexa um programa HID-BPF struct_ops ao dispositivo descoberto
• O lado BPF captura bytes brutos do relatório HID, timestamp, fornecedor/produto/barramento via ring buffer
• O espaço do usuário calcula deltas entre toques de tecla, rastreia um contador de suspeita e desvincula o dispositivo via sysfs quando o limite é ultrapassado

Limitações conhecidas que motivaram a reescrita:

• Tamanho do relatório codificado em 8 ou 9 bytes (apenas teclados de protocolo de inicialização padrão) — quebra em descritores não padrão
• Sem análise do descritor de relatório HID — o tipo de dispositivo é assumido, não verificado; irá disparar erroneamente em mouses, touchpads ou dispositivos compostos
• A lógica de detecção reside inteiramente no espaço do usuário — o BPF é usado apenas como um pipe de dados brutos
• hid_id derivado do número menor do sysfs, que não é estável entre reinicializações

v0.1 — Reescrita Limpa (Desenvolvimento Ativo)

Base portátil sendo construída antes de reconectar a camada BPF:

• Enumera todos os dispositivos HID via /sys/bus/hid/devices/
• Lê e exibe em hex dump os descritores de relatório brutos do sysfs
• Analisador de descritor de relatório HID em andamento (hid_desc_parse.c) — irá identificar o tipo de dispositivo antes de anexar
• Limpeza de memória (verificada com AddressSanitizer)

Arquitetura Pretendida

┌─────────────────────────────────────────────────────┐
│                    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.

Requisitos

• Linux kernel ≥ 6.3 (HID-BPF struct_ops estável)
• cabeçalhos de desenvolvimento libbpf
• LLVM/Clang (para compilação BPF)
• cabeçalhos de desenvolvimento libelf e zlib
• Privilégios de root

Compilação

make

Uso

# 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/

Ajustes de Detecção (main.c)

Status

Testes

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.

Licença

GPL v2