USBCoercer: Um Dispositivo de Coerção WPAD Baseado em TinyUSB

USBCoercer transforma uma placa de desenvolvimento ESP32 com USB-OTG nativo em um gadget Ethernet-over-USB capaz de coagir a configuração de proxy via WPAD. Ele se baseia no exemplo TinyUSB Network Control Model (NCM) e adiciona um servidor DHCP mínimo que injeta a opção DHCP 252 (WPAD/PAC) e, adicionalmente, rotas estáticas sem classe (opção 121) para bloquear telemetria EDR, se necessário.

O projeto é destinado a testes de segurança e demonstrações em laboratório. Sempre obtenha autorização explícita antes de usá-lo.

Principais Funcionalidades

• Gadget Ethernet USB NCM baseado em TinyUSB
• Servidor DHCP embutido fornecendo rotas estáticas sem classe opcionais (opção 121) e URL WPAD/PAC configurável (opção 252).
• Indicador LED de status que fica verde após a pilha de rede estar ativa no hardware AtomS3U, amarelo após a fase de Descoberta/Oferta DHCP e azul quando a Solicitação/ACK DHCP é concluída.

Requisitos

Hardware

• Placa ESP32-S3 com USB-OTG nativo
• (Em alguns modelos) Cabo USB conectando a porta OTG do SoC à máquina alvo.

Software

• Espressif ESP-IDF v5.5 (ou mais recente) com suporte TinyUSB habilitado.
• Toolchain ESP-IDF e ambiente Python instalados via os scripts padrão install.sh/export.sh.
• Importante: Este firmware foi desenvolvido com o branch 1.x do espressif/esp_tinyusb e não foi portado para o branch 2.x. Usar o branch 2.x resultará em erros de compilação. A versão máxima suportada é espressif/esp_tinyusb 1.6.0.

Início Rápido

1. Configurar ESP-IDF
   root@kitploit:~

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

2. Configurar o projeto (opcional)
   root@kitploit:~

   idf.py menuconfig
   

   Revise o menu USBCoercer Configuration para ajustar o IP local, pool DHCP, configurações WPAD, etc.
3. Compilar
   root@kitploit:~

   idf.py build
   

4. Gravar
   root@kitploit:~

   idf.py flash
   

Referência de Configuração

O projeto expõe um menu dedicado USBCoercer Configuration dentro de idf.py menuconfig:

• Interface – defina o endereço IPv4 voltado para USB, máscara de sub-rede e gateway, bem como o endereço MAC administrado localmente anunciado ao host.
• Servidor DHCP – controle o início/fim do pool de leases, tempo de concessão, servidor DNS opcional e sufixo de domínio (opção 15).
• WPAD – ative/desative a opção 252 e defina a URL servida aos hosts conectados.
• Rotas estáticas – ative a opção 121 e forneça uma lista separada por ponto e vírgula de rotas usando a sintaxe destino/prefixo,gateway (por exemplo, 3.121.6.180/32,192.168.7.1). Deixe a lista vazia para omitir a opção.

Configuração Padrão

sdkconfig.defaults fornece uma configuração amigável para laboratório:

• IP local: 192.168.7.1/24 sem gateway padrão.
• Pool DHCP de três endereços (192.168.7.2 – 192.168.7.4).
• Domínio DHCP: badnet.
• WPAD habilitado, apontando para http://192.168.7.1/wpad.dat. Hospede um arquivo PAC na origem configurada ou adapte a URL conforme necessário.
• Opção DNS desabilitada (os hosts mantêm seus servidores DNS existentes).
• Rotas estáticas desabilitadas por padrão (a opção 121 só é enviada quando configurada).

Ajuste sdkconfig.defaults ou use menuconfig para adaptar o ambiente aos seus testes. Recompile o firmware (idf.py build) após alterar qualquer parâmetro.

Comportamento de Rede

• O dispositivo se apresenta como um adaptador Ethernet USB NCM usando o endereço MAC configurado.
• O servidor DHCP embutido responde a mensagens DISCOVER/REQUEST com os parâmetros configurados.
• Quando as rotas sem classe estão habilitadas, a opção 121 é gerada dinamicamente.
• WPAD está habilitado e uma URL não vazia é fornecida, então o host recupera o arquivo PAC da origem especificada e aplica as configurações de proxy.

Usando um Mecanismo de Coerção NTLM

Atualmente, a implantação requer um servidor externo para fornecer o proxy autenticado por NTLM e coagir a autenticação. Responder é útil para essa tarefa. Um servidor externo para servir o arquivo WPAD.DAT é opcional.

Avisos

• Manipular WPAD ou rotas estáticas pode redirecionar o tráfego da máquina conectada. Use este firmware apenas em ambientes controlados com consentimento informado.
• O projeto visa cenários de laboratório; ele não implementa controles de segurança adicionais ou persistência de configuração.

Testes

Este firmware foi testado no M5Stack AtomS3U e funcionou corretamente.

Agradecimentos

• Baseado mais ou menos de perto, ou remotamente, nos exemplos oficiais do ESP-IDF TinyUSB NCM.
• Refatorado e melhorado com Codex.

Feliz (e responsável) hacking!