USBCoercer：基于TinyUSB的WPAD强制设备

USBCoercer 将具备原生USB-OTG功能的ESP32开发板转变为以太网-over-USB 设备，能够通过WPAD强制代理配置。它基于 TinyUSB 网络控制模型（NCM） 示例构建，并添加了一个极简的DHCP服务器，用于注入 DHCP 选项 252（WPAD/PAC），此外还可以根据需要注入无类别静态路由（选项 121）以阻止EDR遥测。

该项目适用于安全测试和实验室演示。使用前务必获得明确授权。

主要特点

• 基于TinyUSB的USB NCM以太网设备
• 嵌入式DHCP服务器，提供可选的无类别静态路由（选项 121）和可配置的WPAD/PAC URL（选项 252）。
• 状态LED指示灯：AtomS3U硬件上网络栈启动后变为绿色，DHCP发现/提供阶段变为黄色，DHCP请求/确认完成后变为蓝色。

要求

硬件

• 带有原生USB-OTG功能的ESP32-S3开发板
• （某些型号）将SoC OTG端口连接到目标主机的USB线缆

软件

• Espressif ESP-IDF v5.5（或更新版本），启用了TinyUSB支持
• 通过标准 install.sh/export.sh 脚本安装的ESP-IDF工具链和Python环境
• 重要提示： 本固件基于 espressif/esp_tinyusb 的 1.x 分支开发，尚未移植到 2.x 分支。使用 2.x 分支会导致编译错误。最高支持版本为 espressif/esp_tinyusb 1.6.0。

快速开始

1. 设置ESP-IDF
   root@kitploit:~

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

2. 配置项目（可选）
   root@kitploit:~

   idf.py menuconfig
   

   查看 USBCoercer Configuration 菜单，调整本地IP、DHCP池、WPAD设置等。
3. 编译
   root@kitploit:~

   idf.py build
   

4. 烧录
   root@kitploit:~

   idf.py flash
   

配置参考

项目在 idf.py menuconfig 中提供专门的 USBCoercer Configuration 菜单：

• 接口 – 设置面向USB的IPv4地址、子网掩码和网关，以及向主机通告的本地管理MAC地址。
• DHCP服务器 – 控制租约池起始/结束地址、租约时间、可选的DNS服务器和域名后缀（选项 15）。
• WPAD – 启用选项 252，并定义向连接受理主机提供的URL。
• 静态路由 – 启用选项 121，并使用 目的地/前缀,网关 语法提供以分号分隔的路由列表（例如 3.121.6.180/32,192.168.7.1）。留空列表则省略该选项。

默认配置

sdkconfig.defaults 提供了一个适合实验室的配置：

• 本地IP：192.168.7.1/24，无默认网关。
• DHCP 池包含三个地址（192.168.7.2 – 192.168.7.4）。
• DHCP 域名：badnet。
• WPAD 已启用，指向 http://192.168.7.1/wpad.dat。在配置的源上托管 PAC 文件，或根据需要调整 URL。
• DNS 选项已禁用（主机保留其原有的 DNS 服务器）。
• 静态路由默认禁用（仅在配置后才发送选项 121）。

调整 sdkconfig.defaults 或使用 menuconfig 来适应您的测试环境。更改参数后重新编译固件（idf.py build）。

网络行为

• 设备使用配置的MAC地址将自己暴露为USB NCM以太网适配器。
• 嵌入式DHCP服务器使用配置的参数响应 DISCOVER/REQUEST 消息。
• 当启用无类别路由时，动态生成选项 121。
• 启用WPAD并提供非空URL，因此主机从指定源获取PAC文件并应用代理设置。

使用NTLM强制机制

目前，部署需要外部服务器提供经过NTLM认证的代理并强制进行身份验证。Responder 可用于此任务。提供WPAD.DAT文件的外部服务器是可选的。

警告

• 操纵WPAD或静态路由可能会重定向来自已连接主机的流量。仅在受控环境且获得知情同意的情况下使用本固件。
• 该项目面向实验室场景，未实现额外的安全控制或配置持久化。

测试

本固件已在 M5Stack AtomS3U 上测试并正常工作。

致谢

• 或多或少基于官方ESP-IDF TinyUSB NCM示例。
• 借助 Codex 重构和优化。

祝您（且负责任地）快乐黑客！