eBPF-hid_guard

eBPF-hid_guard

Siehe unten Warum dies archiviert wurde.

Ein Linux-Kernel-Space-Sicherheitsmonitor zur Erkennung und Blockierung von HID-Injektionsangriffen (Rubber Ducky, O.MG Cable, ESP32-basierte Tastaturemulatoren) mittels eBPF HID-BPF struct_ops.

Was dies tut

Bösartige HID-Geräte emulieren Tastaturen und injizieren Tastenanschläge weit schneller als jeder menschliche Schreibende. Dieses Tool erkennt diese Zeitabnormalität und trennt das angreifende Gerät vom Kernel-HID-Treiber, bevor der Angriff abgeschlossen ist.

Beim Start erstellt das Tool eine Momentaufnahme aller derzeit angeschlossenen HID-Geräte und ignoriert sie – nur neu verbundene Geräte werden überwacht. Es unterstützt sowohl USB- als auch Bluetooth-HID-Geräte.

Branch-Struktur

main – Arbeitsfähiger Proof of Concept

Funktionale End-to-End-Pipeline, getestet gegen einen ESP32-basierten Tastaturemulator:

• Erstellt beim Start eine Momentaufnahme vorhandener Geräte; ignoriert sie
• Parallele USB- und BLE-Erkennungsthreads – wer zuerst ein neues Gerät erkennt, gewinnt
• Hängt ein HID-BPF struct_ops-Programm an das entdeckte Gerät an
• BPF-Seite erfasst rohe HID-Berichtsbytes, Zeitstempel, Hersteller/Produkt/Bus über Ringbuffer
• Userspace berechnet Zwischen-Tastenanschlags-Deltas, führt einen Verdachtszähler und trennt das Gerät über sysfs, wenn der Schwellenwert überschritten wird

Bekannte Einschränkungen, die die Neufassung auslösten:

• Berichtsgröße fest codiert auf 8 oder 9 Bytes (nur Standard-Boot-Protokoll-Tastaturen) – bricht bei nicht standardkonformen Deskriptoren
• Keine HID-Berichtsdeskriptor-Parsing – Gerätetyp wird angenommen, nicht verifiziert; wird bei Mäusen, Touchpads oder zusammengesetzten Geräten Fehlalarme auslösen
• Erkennungslogik befindet sich vollständig im Userspace – BPF wird nur als rohe Datenleitung verwendet
• hid_id wird von der sysfs-Minor-Nummer abgeleitet, die über Neustarts hinweg nicht stabil ist

v0.1 – Saubere Neufassung (angehalten)

Tragfähiges Fundament, erstellt bevor die BPF-Schicht neu verdrahtet wird:

• Zählt alle HID-Geräte über /sys/bus/hid/devices/ auf
• Liest und dump-t rohe Berichtsdeskriptoren von sysfs als Hex
• HID-Berichtsdeskriptor-Parser in Bearbeitung (hid_desc_parse.c) – Gerätetyp-Identifikation nicht abgeschlossen
• Speicherbereinigt (mit AddressSanitizer verifiziert)

Warum dies archiviert wurde

Beide Zweige stießen auf die gleiche Hürde: HID-BPF arbeitet mit rohen Byte-Arrays, daher muss das gesamte Deskriptor-Parsing und die Gerätetyp-Überprüfung unabhängig von der Aufteilung der Erkennungslogik im Userspace stattfinden. Anstatt dieses Gerüst von Grund auf neu zu bauen, bin ich zu [udev-hid-bpf] gewechselt.

Was dies tut

Bösartige HID-Geräte emulieren Tastaturen und injizieren Tastenanschläge weit schneller als jeder menschliche Schreibende. Dieses Tool erkennt diese Zeitabnormalität und trennt das angreifende Gerät vom Kernel-HID-Treiber, bevor der Angriff abgeschlossen ist.

Beim Start erstellt das Tool eine Momentaufnahme aller derzeit angeschlossenen HID-Geräte und ignoriert sie – nur neu verbundene Geräte werden überwacht. Es unterstützt sowohl USB- als auch Bluetooth-HID-Geräte.

Branch-Struktur

main – Arbeitsfähiger Proof of Concept

Funktionale End-to-End-Pipeline, getestet gegen einen ESP32-basierten Tastaturemulator:

• Erstellt beim Start eine Momentaufnahme vorhandener Geräte; ignoriert sie
• Parallele USB- und BLE-Erkennungsthreads – wer zuerst ein neues Gerät erkennt, gewinnt
• Hängt ein HID-BPF struct_ops-Programm an das entdeckte Gerät an
• BPF-Seite erfasst rohe HID-Berichtsbytes, Zeitstempel, Hersteller/Produkt/Bus über Ringbuffer
• Userspace berechnet Zwischen-Tastenanschlags-Deltas, führt einen Verdachtszähler und trennt das Gerät über sysfs, wenn der Schwellenwert überschritten wird

Bekannte Einschränkungen, die die Neufassung auslösten:

• Berichtsgröße fest codiert auf 8 oder 9 Bytes (nur Standard-Boot-Protokoll-Tastaturen) – bricht bei nicht standardkonformen Deskriptoren
• Keine HID-Berichtsdeskriptor-Parsing – Gerätetyp wird angenommen, nicht verifiziert; wird bei Mäusen, Touchpads oder zusammengesetzten Geräten Fehlalarme auslösen
• Erkennungslogik befindet sich vollständig im Userspace – BPF wird nur als rohe Datenleitung verwendet
• hid_id wird von der sysfs-Minor-Nummer abgeleitet, die über Neustarts hinweg nicht stabil ist

v0.1 – Saubere Neufassung (aktive Entwicklung)

Tragfähiges Fundament im Aufbau, bevor die BPF-Schicht neu verdrahtet wird:

• Zählt alle HID-Geräte über /sys/bus/hid/devices/ auf
• Liest und dump-t rohe Berichtsdeskriptoren von sysfs als Hex
• HID-Berichtsdeskriptor-Parser in Bearbeitung (hid_desc_parse.c) – wird vor dem Anhängen den Gerätetyp identifizieren
• Speicherbereinigt (mit AddressSanitizer verifiziert)

Beabsichtigte Architektur

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

Die Erkennungslogik wird in BPF verlagert. Der Userspace übernimmt das Parsen der Deskriptoren, die Befüllung der Konfigurations-Maps und die Unbind-Antwort. Das Zeitfenster zwischen Geräteverbindung und BPF-Anhängung ist eine dokumentierte, begrenzte Einschränkung – reale HID-Injektionswerkzeuge enthalten absichtliche Verzögerungen nach der Enumeration, in die dieses Fenster fällt.

Voraussetzungen

• Linux-Kernel ≥ 6.3 (HID-BPF struct_ops stabil)
• libbpf-Entwicklungsheader
• LLVM/Clang (für BPF-Kompilierung)
• libelf- und zlib-Entwicklungsheader
• Root-Rechte

Bauen

make

Verwendung

# Auto-Erkennung: Gerät einstecken oder koppeln, wenn aufgefordert
sudo ./hid_guard

# Manuelle Überschreibung mit bekannter hid_id
sudo ./hid_guard <hid_id>

# Verfügbare HID-Geräte auflisten
ls /sys/bus/hid/devices/

Erkennungsparameter (main.c)

Status

Testen

ESP32-S2 wurde für BLE-Tastenanschlagsübertragung verwendet. Als nächstes Test mit Hardware wie Rubber Ducky oder ESP32-S3, auf USB-Ports abzielend.

Lizenz

GPL v2