USBCoercer: un dispositivo di coercizione WPAD basato su TinyUSB

USBCoercer trasforma una scheda di sviluppo ESP32 con USB-OTG nativo in un gadget Ethernet-over-USB in grado di forzare la configurazione del proxy tramite WPAD. Si basa sull'esempio TinyUSB Network Control Model (NCM) e aggiunge un server DHCP minimalista che inietta l'opzione DHCP 252 (WPAD/PAC) e, opzionalmente, le route statiche classless (opzione 121) per bloccare la telemetria EDR se necessario.

Il progetto è pensato per test di sicurezza e dimostrazioni in laboratorio. Ottenere sempre un'autorizzazione esplicita prima di utilizzarlo.

Caratteristiche principali

• Gadget Ethernet USB NCM basato su TinyUSB
• Server DHCP integrato che fornisce route statiche classless opzionali (opzione 121) e URL WPAD/PAC configurabile (opzione 252).
• LED di stato che diventa verde dopo l'avvio dello stack di rete su hardware AtomS3U, giallo dopo la fase DHCP Discovery/Offer e blu quando DHCP Request/ACK è completato.

Requisiti

Hardware

• Scheda ESP32-S3 con USB-OTG nativo
• (In alcuni modelli) cavo USB che collega la porta OTG del SoC alla macchina target.

Software

• Espressif ESP-IDF v5.5 (o successiva) con supporto TinyUSB abilitato.
• Toolchain ESP-IDF e ambiente Python installati tramite gli script standard install.sh/export.sh.
• Importante: questo firmware è stato sviluppato con il branch 1.x di espressif/esp_tinyusb e non è stato portato al branch 2.x. L'utilizzo del branch 2.x causerà errori di compilazione. La versione massima supportata è espressif/esp_tinyusb 1.6.0.

Avvio rapido

1. Configurare ESP-IDF
   root@kitploit:~

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

2. Configurare il progetto (opzionale)
   root@kitploit:~

   idf.py menuconfig
   

   Esaminare il menu USBCoercer Configuration per personalizzare l'IP locale, il pool DHCP, le impostazioni WPAD, ecc.
3. Compilare
   root@kitploit:~

   idf.py build
   

4. Flashing
   root@kitploit:~

   idf.py flash
   

Riferimento di configurazione

Il progetto espone un menu dedicato USBCoercer Configuration all'interno di idf.py menuconfig:

• Interface – imposta l'indirizzo IPv4 verso USB, la subnet mask e il gateway, oltre all'indirizzo MAC amministrato localmente pubblicizzato verso l'host.
• DHCP server – controlla inizio/fine del pool di lease, tempo di lease, server DNS opzionale e suffisso di dominio (opzione 15).
• WPAD – attiva/disattiva l'opzione 252 e definisce l'URL servito agli host collegati.
• Static routes – abilita l'opzione 121 e fornisce un elenco di route separato da punto e virgola usando la sintassi destination/prefix,gateway (ad esempio, 3.121.6.180/32,192.168.7.1). Lasciare l'elenco vuoto per omettere l'opzione.

Configurazione predefinita

sdkconfig.defaults fornisce una configurazione adatta al laboratorio:

• IP locale: 192.168.7.1/24 senza gateway predefinito.
• Pool DHCP di tre indirizzi (192.168.7.2 – 192.168.7.4).
• Dominio DHCP: badnet.
• WPAD abilitato, che punta a http://192.168.7.1/wpad.dat. Ospitare un file PAC sull'origine configurata o adattare l'URL come richiesto.
• Opzione DNS disabilitata (gli host mantengono i loro server DNS esistenti).
• Route statiche disabilitate per impostazione predefinita (l'opzione 121 viene inviata solo quando configurata).

Adattare sdkconfig.defaults o usare menuconfig per adeguare l'ambiente ai propri test. Ricompilare il firmware (idf.py build) dopo aver modificato qualsiasi parametro.

Comportamento di rete

• Il dispositivo si presenta come un adattatore Ethernet USB NCM usando l'indirizzo MAC configurato.
• Il server DHCP integrato risponde ai messaggi DISCOVER/REQUEST con i parametri configurati.
• Quando le route classless sono abilitate, l'opzione 121 viene generata dinamicamente.
• WPAD è abilitato e viene fornito un URL non vuoto, quindi l'host recupera il file PAC dall'origine specificata e applica le impostazioni del proxy.

Utilizzo di un meccanismo di coercizione NTLM

Attualmente, la distribuzione richiede un server esterno per fornire il proxy autenticato NTLM e forzare l'autenticazione. Responder è utile per questo scopo. Un server esterno per servire il file WPAD.DAT è opzionale.

Avvertenze

• Manipolare WPAD o le route statiche può reindirizzare il traffico dalla macchina collegata. Utilizzare questo firmware solo in ambienti controllati e con consenso informato.
• Il progetto è pensato per scenari di laboratorio; non implementa controlli di sicurezza aggiuntivi né persistenza della configurazione.

Test

Questo firmware è stato testato su M5Stack AtomS3U e ha funzionato correttamente.

Riconoscimenti

• Basato più o meno fedelmente, o liberamente, sugli esempi ufficiali TinyUSB NCM di ESP-IDF.
• Refactoring e miglioramenti con Codex.

Buon hacking (e responsabile)!