eBPF-hid_guard

eBPF-hid_guard

Véase Por Qué Esto Fue Archivado más abajo.

Un monitor de seguridad en espacio de kernel de Linux para detectar y bloquear ataques de inyección HID (Rubber Ducky, O.MG Cable, emuladores de teclado basados en ESP32) usando eBPF HID-BPF struct_ops.

Qué Hace Esto

Los dispositivos HID maliciosos emulan teclados e inyectan pulsaciones de teclas mucho más rápido que cualquier mecanógrafo humano. Esta herramienta detecta esa anomalía temporal y desvincula el dispositivo infractor del controlador HID del kernel antes de que el ataque se complete.

Al iniciarse, la herramienta captura una instantánea de todos los dispositivos HID actualmente conectados y los ignora; solo se monitorizan los dispositivos recién conectados. Soporta tanto dispositivos HID USB como Bluetooth.

Estructura de Ramas

main — Prueba de Concepto Funcional

Pipeline funcional de principio a fin, probado contra un emulador de teclado basado en ESP32:

• Toma instantánea de los dispositivos existentes al inicio; los ignora
• Hilos de descubrimiento USB y BLE paralelos: el primero en detectar un nuevo dispositivo gana
• Adjunta un programa HID-BPF struct_ops al dispositivo descubierto
• El lado BPF captura los bytes brutos del informe HID, timestamp, vendedor/producto/bus a través de ring buffer
• El espacio de usuario calcula los deltas entre pulsaciones, lleva un contador de sospecha y desvincula el dispositivo a través de sysfs cuando se supera el umbral

Limitaciones conocidas que desencadenaron la reescritura:

• Tamaño de informe hardcodeado a 8 o 9 bytes (solo teclados estándar de protocolo de arranque): se rompe con descriptores no estándar
• Sin análisis del descriptor de informe HID: el tipo de dispositivo se asume, no se verifica; fallará en ratones, paneles táctiles o dispositivos compuestos
• La lógica de detección reside completamente en el espacio de usuario: BPF se usa solo como tubería de datos brutos
• hid_id derivado del número menor de sysfs, que no es estable entre reinicios

v0.1 — Reescritura Limpia (Detenida)

Fundación portátil construida antes de reconectar la capa BPF:

• Enumera todos los dispositivos HID a través de /sys/bus/hid/devices/
• Lee y vuelca en hexadecimal los descriptores de informe brutos desde sysfs
• Analizador de descriptores de informe HID en progreso (hid_desc_parse.c) — identificación de tipo de dispositivo no completada
• Limpio en memoria (verificado con AddressSanitizer)

Por Qué Esto Fue Archivado

Ambas ramas chocaron con el mismo muro: HID-BPF opera sobre arreglos de bytes brutos, por lo que todo el análisis de descriptores y la verificación del tipo de dispositivo deben residir en el espacio de usuario, independientemente de cómo se divida la lógica de detección. En lugar de seguir construyendo ese andamiaje desde cero, me mudé a [udev-hid-bpf].

Qué Hace Esto

Los dispositivos HID maliciosos emulan teclados e inyectan pulsaciones de teclas mucho más rápido que cualquier mecanógrafo humano. Esta herramienta detecta esa anomalía temporal y desvincula el dispositivo infractor del controlador HID del kernel antes de que el ataque se complete.

Al iniciarse, la herramienta captura una instantánea de todos los dispositivos HID actualmente conectados y los ignora; solo se monitorizan los dispositivos recién conectados. Soporta tanto dispositivos HID USB como Bluetooth.

Estructura de Ramas

main — Prueba de Concepto Funcional

Pipeline funcional de principio a fin, probado contra un emulador de teclado basado en ESP32:

• Toma instantánea de los dispositivos existentes al inicio; los ignora
• Hilos de descubrimiento USB y BLE paralelos: el primero en detectar un nuevo dispositivo gana
• Adjunta un programa HID-BPF struct_ops al dispositivo descubierto
• El lado BPF captura los bytes brutos del informe HID, timestamp, vendedor/producto/bus a través de ring buffer
• El espacio de usuario calcula los deltas entre pulsaciones, lleva un contador de sospecha y desvincula el dispositivo a través de sysfs cuando se supera el umbral

Limitaciones conocidas que desencadenaron la reescritura:

• Tamaño de informe hardcodeado a 8 o 9 bytes (solo teclados estándar de protocolo de arranque): se rompe con descriptores no estándar
• Sin análisis del descriptor de informe HID: el tipo de dispositivo se asume, no se verifica; fallará en ratones, paneles táctiles o dispositivos compuestos
• La lógica de detección reside completamente en el espacio de usuario: BPF se usa solo como tubería de datos brutos
• hid_id derivado del número menor de sysfs, que no es estable entre reinicios

v0.1 — Reescritura Limpia (Desarrollo Activo)

Fundación portátil que se está construyendo antes de reconectar la capa BPF:

• Enumera todos los dispositivos HID a través de /sys/bus/hid/devices/
• Lee y vuelca en hexadecimal los descriptores de informe brutos desde sysfs
• Analizador de descriptores de informe HID en progreso (hid_desc_parse.c) — identificará el tipo de dispositivo antes de adjuntar
• Limpio en memoria (verificado con AddressSanitizer)

Arquitectura Prevista

┌─────────────────────────────────────────────────────┐
│                    Espacio de usuario                 │
│                                                      │
│  monitor udev → analizar descriptor → ¿teclado?      │
│       ↓                                              │
│  poblar mapas de configuración BPF (umbrales, info)  │
│       ↓                                              │
│  adjuntar struct_ops HID-BPF a hid_id                │
│       ↓                                              │
│  consumidor de ring buffer → desvincular por sysfs   │
└──────────────────────────┬──────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│                  BPF (lado del kernel)               │
│                                                      │
│  hid_device_event → cálculo temporal (varianza       │
│  online de Welford, punto fijo) → mapas de timestamp │
│  por tecla → envío a ring buffer ante anomalía       │
└─────────────────────────────────────────────────────┘

La lógica de detección se mueve a BPF. El espacio de usuario maneja el análisis de descriptores, el poblamiento de mapas de configuración y la respuesta de desvinculación. La ventana de enumeración entre la conexión del dispositivo y la adjunción de BPF es una limitación documentada y acotada: las herramientas reales de inyección HID incluyen retardos deliberados posteriores a la enumeración dentro de los cuales cae esta ventana.

Requisitos

• Kernel de Linux ≥ 6.3 (HID-BPF struct_ops estable)
• Cabeceras de desarrollo de libbpf
• LLVM/Clang (para compilación BPF)
• Cabeceras de desarrollo de libelf y zlib
• Privilegios de root

Compilación

make

Uso

# Detección automática: conecta o empareja el dispositivo cuando se solicite
sudo ./hid_guard

# Anulación manual con hid_id conocido
sudo ./hid_guard <hid_id>

# Listar dispositivos HID disponibles
ls /sys/bus/hid/devices/

Parámetros de Detección Ajustables (main.c)

Estado

Pruebas

Se usó ESP32-S2 para transmisión de pulsaciones BLE. Próximamente, probar con hardware como rubber ducky o ESP32-S3, apuntando a puertos USB.

Licencia

GPL v2