Supported Targets	ESP32-S3

USBCoercer: Un Dispositivo de Coerción WPAD Basado en TinyUSB

USBCoercer convierte una placa de desarrollo ESP32 con USB-OTG nativo en un gadget Ethernet-over-USB capaz de coaccionar la configuración de proxy mediante WPAD. Se basa en el ejemplo TinyUSB Network Control Model (NCM) y añade un servidor DHCP minimalista que inyecta la opción DHCP 252 (WPAD/PAC) y, adicionalmente, rutas estáticas sin clase (opción 121) para bloquear la telemetría de EDR si es necesario.

El proyecto está pensado para pruebas de seguridad y demostraciones de laboratorio. Obtenga siempre autorización explícita antes de utilizarlo.

Características Principales

• Gadget Ethernet USB NCM basado en TinyUSB
• Servidor DHCP integrado que proporciona rutas estáticas sin clase opcionales (opción 121) y una URL WPAD/PAC configurable (opción 252).
• Indicador LED de estado que se pone verde cuando la pila de red está activa en el hardware AtomS3U, amarillo durante la fase DHCP Discovery/Offer y azul cuando se completa DHCP Request/ACK.

Requisitos

Hardware

• Placa ESP32-S3 con USB-OTG nativo
• (En algunos modelos) Cable USB que conecta el puerto OTG del SoC a la máquina objetivo.

Software

• Espressif ESP-IDF v5.5 (o superior) con soporte TinyUSB habilitado.
• Cadena de herramientas ESP-IDF y entorno Python instalados mediante los scripts estándar install.sh/export.sh.
• Importante: Este firmware ha sido desarrollado con la rama 1.x de espressif/esp_tinyusb y no se ha portado a la rama 2.x. El uso de la rama 2.x dará lugar a errores de compilación. La versión máxima compatible es espressif/esp_tinyusb 1.6.0.

Inicio Rápido

1. Configurar ESP-IDF

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

2. Configurar el proyecto (opcional)

   idf.py menuconfig
   

   Revise el menú USBCoercer Configuration para ajustar la IP local, el pool DHCP, los ajustes WPAD, etc.
3. Compilar

   idf.py build
   

4. Grabar

   idf.py flash
   

Referencia de Configuración

El proyecto expone un menú dedicado USBCoercer Configuration dentro de idf.py menuconfig:

• Interface – establezca la dirección IPv4 orientada a USB, la máscara de subred y la puerta de enlace, así como la dirección MAC administrada localmente que se anuncia al host.
• DHCP server – controle el inicio/fin del pool de concesiones, el tiempo de concesión, el servidor DNS opcional y el sufijo de dominio (opción 15).
• WPAD – active la opción 252 y defina la URL servida a los hosts conectados.
• Static routes – habilite la opción 121 y proporcione una lista de rutas separadas por punto y coma utilizando la sintaxis destination/prefix,gateway (por ejemplo, 3.121.6.180/32,192.168.7.1). Deje la lista vacía para omitir la opción.

Configuración por Defecto

sdkconfig.defaults proporciona una configuración pensada para laboratorio:

• IP local: 192.168.7.1/24 sin puerta de enlace predeterminada.
• Pool DHCP de tres direcciones (192.168.7.2 – 192.168.7.4).
• Dominio DHCP: badnet.
• WPAD habilitado, apuntando a http://192.168.7.1/wpad.dat. Aloje un archivo PAC en el origen configurado o adapte la URL según sea necesario.
• Opción DNS deshabilitada (los hosts conservan sus servidores DNS existentes).
• Rutas estáticas deshabilitadas por defecto (la opción 121 solo se envía cuando está configurada).

Ajuste sdkconfig.defaults o use menuconfig para adaptar el entorno a sus pruebas. Recompile el firmware (idf.py build) después de cambiar cualquier parámetro.

Comportamiento de Red

• El dispositivo se presenta como un adaptador Ethernet USB NCM usando la dirección MAC configurada.
• El servidor DHCP integrado responde a los mensajes DISCOVER/REQUEST con los parámetros configurados.
• Cuando las rutas sin clase están habilitadas, la opción 121 se genera dinámicamente.
• WPAD está habilitado y se proporciona una URL no vacía, por lo que el host recupera el archivo PAC desde el origen especificado y aplica la configuración de proxy.

Uso de un Mecanismo de Coerción NTLM

Actualmente, el despliegue requiere un servidor externo para proporcionar el proxy autenticado con NTLM y coaccionar la autenticación. Responder es útil para esta tarea. Un servidor externo para servir el archivo WPAD.DAT es opcional.

Advertencias

• La manipulación de WPAD o de las rutas estáticas puede redirigir el tráfico de la máquina conectada. Use este firmware solo en entornos controlados con consentimiento informado.
• El proyecto está orientado a escenarios de laboratorio; no implementa controles de seguridad adicionales ni persistencia de configuración.

Pruebas

Este firmware ha sido probado en M5Stack AtomS3U y funcionó correctamente.

Agradecimientos

• Basado más o menos estrechamente, o remotamente, en los ejemplos oficiales TinyUSB NCM de ESP-IDF.
• Refactorizado y mejorado con Codex.

¡Feliz (y responsable) hacking!