USBCoercer : un dispositif de coercition WPAD basé sur TinyUSB

USBCoercer transforme une carte de développement ESP32 avec USB-OTG natif en un gadget Ethernet-over-USB capable de forcer la configuration du proxy via WPAD. Il s'appuie sur l'exemple TinyUSB Network Control Model (NCM) et ajoute un serveur DHCP minimaliste qui injecte l'option DHCP 252 (WPAD/PAC) ainsi que, en complément, des routes statiques sans classe (option 121) pour bloquer la télémétrie EDR si nécessaire.

Ce projet est destiné aux tests de sécurité et aux démonstrations en laboratoire. Obtenez toujours une autorisation explicite avant de l'utiliser.

Fonctionnalités clés

• Gadget Ethernet USB NCM basé sur TinyUSB
• Serveur DHCP intégré fournissant des routes statiques sans classe facultatives (option 121) et une URL WPAD/PAC configurable (option 252).
• Indicateur LED d'état qui devient vert une fois la pile réseau active sur le matériel AtomS3U, jaune après la phase DHCP Discovery/Offer et bleu lorsque DHCP Request/ACK est terminé.

Prérequis

Matériel

• Carte ESP32-S3 avec USB-OTG natif
• (Sur certains modèles) câble USB reliant le port OTG du SoC à la machine cible.

Logiciel

• Espressif ESP-IDF v5.5 (ou plus récent) avec prise en charge de TinyUSB activée.
• Chaîne d'outils ESP-IDF et environnement Python installés via les scripts standards install.sh/export.sh.
• Important : ce firmware a été développé avec la branche 1.x de espressif/esp_tinyusb et n'a pas été porté vers la branche 2.x. L'utilisation de la branche 2.x entraînera des erreurs de compilation. La version maximale prise en charge est espressif/esp_tinyusb 1.6.0.

Démarrage rapide

1. Configurer ESP-IDF
   root@kitploit:~

   . $HOME/esp/esp-idf/export.sh
   

2. Configurer le projet (facultatif)
   root@kitploit:~

   idf.py menuconfig
   

   Examinez le menu USBCoercer Configuration pour personnaliser l'IP locale, le pool DHCP, les paramètres WPAD, etc.
3. Compiler
   root@kitploit:~

   idf.py build
   

4. Flasher
   root@kitploit:~

   idf.py flash
   

Référence de configuration

Le projet expose un menu dédié USBCoercer Configuration dans idf.py menuconfig :

• Interface – définit l'adresse IPv4 côté USB, le masque de sous-réseau et la passerelle ainsi que l'adresse MAC administrée localement annoncée à l'hôte.
• Serveur DHCP – contrôle le début/fin du pool de bail, la durée du bail, le serveur DNS facultatif et le suffixe de domaine (option 15).
• WPAD – active/désactive l'option 252 et définit l'URL servie aux hôtes connectés.
• Routes statiques – active l'option 121 et fournit une liste séparée par des points-virgules de routes utilisant la syntaxe destination/prefix,gateway (par exemple, 3.121.6.180/32,192.168.7.1). Laissez la liste vide pour omettre l'option.

Configuration par défaut

sdkconfig.defaults fournit une configuration adaptée au laboratoire :

• IP locale : 192.168.7.1/24 sans passerelle par défaut.
• Pool DHCP de trois adresses (192.168.7.2 – 192.168.7.4).
• Domaine DHCP : badnet.
• WPAD activé, pointant vers http://192.168.7.1/wpad.dat. Hébergez un fichier PAC sur l'origine configurée ou adaptez l'URL selon vos besoins.
• Option DNS désactivée (les hôtes conservent leurs serveurs DNS existants).
• Routes statiques désactivées par défaut (l'option 121 n'est envoyée que lorsqu'elle est configurée).

Adaptez sdkconfig.defaults ou utilisez menuconfig pour ajuster l'environnement à vos tests. Recompilez le firmware (idf.py build) après avoir modifié des paramètres.

Comportement réseau

• L'appareil se présente comme un adaptateur Ethernet USB NCM utilisant l'adresse MAC configurée.
• Le serveur DHCP intégré répond aux messages DISCOVER/REQUEST avec les paramètres configurés.
• Lorsque les routes sans classe sont activées, l'option 121 est générée dynamiquement.
• WPAD est activé et une URL non vide est fournie, de sorte que l'hôte récupère le fichier PAC depuis l'origine spécifiée et applique les paramètres du proxy.

Utilisation d'un mécanisme de coercition NTLM

Actuellement, le déploiement nécessite un serveur externe pour fournir le proxy authentifié NTLM et forcer l'authentification. Responder est utile pour cette tâche. Un serveur externe pour servir le fichier WPAD.DAT est facultatif.

Avertissements

• La manipulation de WPAD ou des routes statiques peut rediriger le trafic de la machine connectée. N'utilisez ce firmware que dans des environnements contrôlés avec un consentement éclairé.
• Le projet vise des scénarios de laboratoire ; il ne met pas en œuvre de contrôles de sécurité supplémentaires ni de persistance de la configuration.

Tests

Ce firmware a été testé sur M5Stack AtomS3U et a fonctionné correctement.

Remerciements

• Basé de près ou de loin sur les exemples officiels ESP-IDF TinyUSB NCM.
• Refactorisé et amélioré avec Codex.

Bon hacking (et responsable) !