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
   root@kitploit:~

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

2. Configurar el proyecto (opcional)
   root@kitploit:~

   idf.py menuconfig
   

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

   idf.py build
   

4. Grabar
   root@kitploit:~

   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!