Target supportati	ESP32-S3

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

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

2. Configurare il progetto (opzionale)

   idf.py menuconfig
   

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

   idf.py build
   

4. Flashing

   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)!