USBCoercer: Ein TinyUSB-basiertes WPAD-Coercion-Gerät

USBCoercer verwandelt ein ESP32-Entwicklungsboard mit nativem USB-OTG in ein Ethernet-over-USB-Gadget, das in der Lage ist, die Proxy-Konfiguration über WPAD zu erzwingen. Es baut auf dem TinyUSB Network Control Model (NCM)-Beispiel auf und ergänzt einen minimalistischen DHCP-Server, der DHCP-Option 252 (WPAD/PAC) und zusätzlich klassenlose statische Routen (Option 121) injiziert, um bei Bedarf EDR-Telemetrie zu blockieren.

Das Projekt ist für Sicherheitstests und Labordemonstrationen gedacht. Holen Sie vor der Verwendung immer eine ausdrückliche Genehmigung ein.

Hauptfunktionen

• TinyUSB-basiertes USB-NCM-Ethernet-Gadget
• Eingebetteter DHCP-Server, der optionale klassenlose statische Routen (Option 121) und eine konfigurierbare WPAD/PAC-URL (Option 252) bereitstellt.
• Status-LED-Anzeige, die grün wird, sobald der Netzwerk-Stack auf der AtomS3U-Hardware aktiv ist, gelb nach der DHCP-Discovery/Offer-Phase und blau, wenn DHCP Request/ACK abgeschlossen ist.

Anforderungen

Hardware

• ESP32-S3-Board mit nativem USB-OTG
• (Bei einigen Modellen) USB-Kabel, das den OTG-Port des SoC mit dem Zielrechner verbindet.

Software

• Espressif ESP-IDF v5.5 (oder neuer) mit aktivierter TinyUSB-Unterstützung.
• ESP-IDF-Toolchain und Python-Umgebung, installiert über die standardmäßigen Skripte install.sh/export.sh.
• Wichtig: Diese Firmware wurde mit dem 1.x-Zweig von espressif/esp_tinyusb entwickelt und wurde nicht auf den 2.x-Zweig portiert. Die Verwendung des 2.x-Zweigs führt zu Kompilierungsfehlern. Die maximal unterstützte Version ist espressif/esp_tinyusb 1.6.0.

Schnellstart

1. ESP-IDF einrichten
   root@kitploit:~

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

2. Projekt konfigurieren (optional)
   root@kitploit:~

   idf.py menuconfig
   

   Überprüfen Sie das Menü USBCoercer Configuration, um die lokale IP, den DHCP-Pool, die WPAD-Einstellungen usw. anzupassen.
3. Erstellen
   root@kitploit:~

   idf.py build
   

4. Flashen
   root@kitploit:~

   idf.py flash
   

Konfigurationsreferenz

Das Projekt stellt ein eigenes Menü USBCoercer Configuration innerhalb von idf.py menuconfig bereit:

• Interface – Legen Sie die USB-seitige IPv4-Adresse, Subnetzmaske und das Gateway sowie die lokal verwaltete MAC-Adresse fest, die dem Host angekündigt wird.
• DHCP-Server – Steuern Sie Start/Ende des Lease-Pools, die Lease-Zeit, den optionalen DNS-Server und das Domain-Suffix (Option 15).
• WPAD – Option 252 ein-/ausschalten und die URL definieren, die verbundenen Hosts bereitgestellt wird.
• Statische Routen – Aktivieren Sie Option 121 und geben Sie eine durch Semikolons getrennte Liste von Routen in der Syntax destination/prefix,gateway an (z. B. 3.121.6.180/32,192.168.7.1). Lassen Sie die Liste leer, um die Option wegzulassen.

Standardkonfiguration

sdkconfig.defaults bietet ein laborfreundliches Setup:

• Lokale IP: 192.168.7.1/24 ohne Standard-Gateway.
• DHCP-Pool mit drei Adressen (192.168.7.2 – 192.168.7.4).
• DHCP-Domain: badnet.
• WPAD aktiviert, das auf http://192.168.7.1/wpad.dat verweist. Stellen Sie eine PAC-Datei auf dem konfigurierten Ursprung bereit oder passen Sie die URL bei Bedarf an.
• DNS-Option deaktiviert (Hosts behalten ihre vorhandenen DNS-Server).
• Statische Routen standardmäßig deaktiviert (Option 121 wird nur gesendet, wenn konfiguriert).

Passen Sie sdkconfig.defaults an oder verwenden Sie menuconfig, um die Umgebung an Ihre Tests anzupassen. Erstellen Sie die Firmware nach Änderungen an Parametern neu (idf.py build).

Netzwerkverhalten

• Das Gerät präsentiert sich als USB-NCM-Ethernet-Adapter mit der konfigurierten MAC-Adresse.
• Der eingebettete DHCP-Server beantwortet DISCOVER/REQUEST-Nachrichten mit den konfigurierten Parametern.
• Wenn klassenlose Routen aktiviert sind, wird Option 121 dynamisch generiert.
• WPAD ist aktiviert und eine nicht-leere URL wird bereitgestellt, sodass der Host die PAC-Datei vom angegebenen Ursprung abruft und die Proxy-Einstellungen anwendet.

Verwenden eines NTLM-Coercion-Mechanismus

Derzeit erfordert die Bereitstellung einen externen Server, um den NTLM-authentifizierten Proxy bereitzustellen und die Authentifizierung zu erzwingen. Responder ist für diese Aufgabe nützlich. Ein externer Server zum Ausliefern der WPAD.DAT-Datei ist optional.

Warnhinweise

• Die Manipulation von WPAD oder statischen Routen kann den Datenverkehr des verbundenen Rechners umleiten. Verwenden Sie diese Firmware nur in kontrollierten Umgebungen mit informierter Einwilligung.
• Das Projekt zielt auf Laborszenarien ab; es implementiert keine zusätzlichen Sicherheitskontrollen oder Konfigurationspersistenz.

Tests

Diese Firmware wurde auf dem M5Stack AtomS3U getestet und funktionierte einwandfrei.

Danksagungen

• Mehr oder weniger eng, oder auch entfernt, basierend auf den offiziellen ESP-IDF-TinyUSB-NCM-Beispielen.
• Refaktoriert und verbessert mit Codex.

Viel Spaß beim (verantwortungsvollen) Hacken!