eBPF-hid_guard

eBPF-hid_guard

Voir Pourquoi ce dépôt a été archivé ci-dessous.

Un moniteur de sécurité dans l'espace noyau Linux pour détecter et bloquer les attaques par injection HID (Rubber Ducky, O.MG Cable, émulateurs de clavier basés sur ESP32) en utilisant eBPF HID-BPF struct_ops.

Ce que ça fait

Les périphériques HID malveillants émulent des claviers et injectent des frappes bien plus rapidement qu'aucun humain ne peut taper. Cet outil détecte cette anomalie temporelle et désactive le périphérique incriminé du pilote HID du noyau avant que l'attaque ne se termine.

Au démarrage, l'outil prend un instantané de tous les périphériques HID actuellement connectés et les ignore — seuls les périphériques nouvellement connectés sont surveillés. Il prend en charge les périphériques HID USB et Bluetooth.

Structure des branches

main — Preuve de concept fonctionnelle

Pipeline fonctionnel de bout en bout, testé contre un émulateur de clavier basé sur ESP32 :

• Prend un instantané des périphériques préexistants au démarrage ; les ignore
• Threads de découverte USB et BLE en parallèle — le premier qui détecte un nouveau périphérique gagne
• Attache un programme struct_ops HID-BPF au périphérique découvert
• Le côté BPF capture les octets bruts du rapport HID, l'horodatage, le vendeur/produit/bus via un tampon circulaire
• L'espace utilisateur calcule les écarts inter-frappes, suit un compteur de suspicion et désactive le périphérique via sysfs lorsque le seuil est dépassé

Limitations connues ayant déclenché la réécriture :

• Taille du rapport codée en dur sur 8 ou 9 octets (claviers standard en protocole boot uniquement) — plante sur les descripteurs non standard
• Aucun analyseur de descripteur de rapport HID — le type de périphérique est supposé, non vérifié ; déclenchera des faux positifs sur les souris, pavés tactiles ou périphériques composites
• La logique de détection réside entièrement dans l'espace utilisateur — BPF n'est utilisé que comme un tuyau de données brutes
• hid_id dérivé du numéro mineur sysfs, qui n'est pas stable entre les redémarrages

v0.1 — Réécriture propre (arrêtée)

Fondation portable construite avant de rebrancher la couche BPF :

• Énumère tous les périphériques HID via /sys/bus/hid/devices/
• Lit et affiche en hexadécimal les descripteurs de rapport bruts depuis sysfs
• Analyseur de descripteur de rapport HID en cours (hid_desc_parse.c) — identification du type de périphérique non terminée
• Propre en mémoire (vérifié avec AddressSanitizer)

Pourquoi ce dépôt a été archivé

Les deux branches se sont heurtées au même mur : HID-BPF opère sur des tableaux d'octets bruts, donc toute analyse de descripteurs et vérification de type de périphérique doit résider dans l'espace utilisateur, quelle que soit la façon dont la logique de détection est répartie. Plutôt que de continuer à construire cet échafaudage à partir de zéro, j'ai migré vers [udev-hid-bpf].

Ce que ça fait

Les périphériques HID malveillants émulent des claviers et injectent des frappes bien plus rapidement qu'aucun humain ne peut taper. Cet outil détecte cette anomalie temporelle et désactive le périphérique incriminé du pilote HID du noyau avant que l'attaque ne se termine.

Au démarrage, l'outil prend un instantané de tous les périphériques HID actuellement connectés et les ignore — seuls les périphériques nouvellement connectés sont surveillés. Il prend en charge les périphériques HID USB et Bluetooth.

Structure des branches

main — Preuve de concept fonctionnelle

Pipeline fonctionnel de bout en bout, testé contre un émulateur de clavier basé sur ESP32 :

• Prend un instantané des périphériques préexistants au démarrage ; les ignore
• Threads de découverte USB et BLE en parallèle — le premier qui détecte un nouveau périphérique gagne
• Attache un programme struct_ops HID-BPF au périphérique découvert
• Le côté BPF capture les octets bruts du rapport HID, l'horodatage, le vendeur/produit/bus via un tampon circulaire
• L'espace utilisateur calcule les écarts inter-frappes, suit un compteur de suspicion et désactive le périphérique via sysfs lorsque le seuil est dépassé

Limitations connues ayant déclenché la réécriture :

• Taille du rapport codée en dur sur 8 ou 9 octets (claviers standard en protocole boot uniquement) — plante sur les descripteurs non standard
• Aucun analyseur de descripteur de rapport HID — le type de périphérique est supposé, non vérifié ; déclenchera des faux positifs sur les souris, pavés tactiles ou périphériques composites
• La logique de détection réside entièrement dans l'espace utilisateur — BPF n'est utilisé que comme un tuyau de données brutes
• hid_id dérivé du numéro mineur sysfs, qui n'est pas stable entre les redémarrages

v0.1 — Réécriture propre (développement actif)

Fondation portable en cours de construction avant de rebrancher la couche BPF :

• Énumère tous les périphériques HID via /sys/bus/hid/devices/
• Lit et affiche en hexadécimal les descripteurs de rapport bruts depuis sysfs
• Analyseur de descripteur de rapport HID en cours (hid_desc_parse.c) — identifiera le type de périphérique avant attachement
• Propre en mémoire (vérifié avec AddressSanitizer)

Architecture prévue

┌─────────────────────────────────────────────────────┐
│                    Espace utilisateur                 │
│                                                      │
│  moniteur udev → analyse descripteur → clavier ?     │
│       ↓                                              │
│  remplir les maps de configuration BPF (seuils, info périph.) │
│       ↓                                              │
│  attacher struct_ops HID-BPF à hid_id                │
│       ↓                                              │
│  consommateur du tampon circulaire → désactiver sysfs en attaque │
└──────────────────────────┬──────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│                  BPF (côté noyau)                    │
│                                                      │
│  hid_device_event → calcul temporel (variance en    │
│  ligne de Welford, virgule fixe) → maps d'horodatage│
│  par touche → soumission au tampon circulaire en    │
│  cas d'anomalie                                     │
└─────────────────────────────────────────────────────┘

La logique de détection passe dans BPF. L'espace utilisateur gère l'analyse des descripteurs, le remplissage des maps de configuration et la réponse de désactivation. La fenêtre d'énumération entre la connexion du périphérique et l'attachement BPF est une limitation documentée et bornée — les outils d'injection HID réels incluent des délais volontaires après l'énumération dans lesquels cette fenêtre s'inscrit.

Prérequis

• Noyau Linux ≥ 6.3 (HID-BPF struct_ops stable)
• En-têtes de développement libbpf
• LLVM/Clang (pour la compilation BPF)
• En-têtes de développement libelf et zlib
• Privilèges root

Compilation

make

Utilisation

# Détection automatique : branchez ou appariez le périphérique lorsque demandé
sudo ./hid_guard

# Surcharge manuelle avec un hid_id connu
sudo ./hid_guard <hid_id>

# Liste des périphériques HID disponibles
ls /sys/bus/hid/devices/

Paramètres de détection (main.c)

Statut

Tests

Un ESP32-S2 a été utilisé pour la transmission de frappes BLE. Prochaine étape : tester avec du matériel comme un rubber ducky ou ESP32-S3, ciblant les ports USB.

Licence

GPL v2