Поддерживаемые цели	ESP32-S3

USBCoercer: устройство для принуждения WPAD на базе TinyUSB

USBCoercer превращает плату разработки ESP32 с нативным USB-OTG в USB-устройство Ethernet-over-USB, способное принуждать к использованию прокси-конфигурации через WPAD. Оно построено на примере TinyUSB Network Control Model (NCM) и добавляет минималистичный DHCP-сервер, который внедряет DHCP-опцию 252 (WPAD/PAC) и, дополнительно, бесклассовые статические маршруты (опция 121) для блокировки телеметрии EDR при необходимости.

Проект предназначен для тестирования безопасности и лабораторных демонстраций. Всегда получайте явное разрешение перед его использованием.

Ключевые особенности

USB NCM Ethernet-устройство на базе TinyUSB
Встроенный DHCP-сервер с поддержкой необязательных бесклассовых статических маршрутов (опция 121) и настраиваемого WPAD/PAC URL (опция 252).
Светодиодный индикатор состояния: зелёный после поднятия сетевого стека на оборудовании AtomS3U, жёлтый во время фазы DHCP Discovery/Offer и синий после завершения DHCP Request/ACK.

Требования

Оборудование

Плата ESP32-S3 с нативным USB-OTG
(На некоторых моделях) USB-кабель, соединяющий OTG-порт SoC с целевой машиной.

Программное обеспечение

Espressif ESP-IDF v5.5 (или новее) с включённой поддержкой TinyUSB.
Инструментарий ESP-IDF и окружение Python, установленные с помощью стандартных скриптов install.sh/export.sh.
Важно: данная прошивка разработана для ветки 1.x репозитория espressif/esp_tinyusb и не портирована на ветку 2.x. Использование ветки 2.x приведёт к ошибкам компиляции. Максимальная поддерживаемая версия — espressif/esp_tinyusb 1.6.0.

Быстрый старт

Настройте ESP-IDF
```
. $HOME/esp/esp-idf/export.sh
```
Настройте проект (необязательно)
```
idf.py menuconfig
```
Просмотрите меню USBCoercer Configuration, чтобы настроить локальный IP, пул DHCP, параметры WPAD и т.д.
Соберите
```
idf.py build
```
Прошейте
```
idf.py flash
```

Справочник по конфигурации

Проект предоставляет выделенное меню USBCoercer Configuration внутри idf.py menuconfig:

Interface – задаёт IPv4-адрес для USB-интерфейса, маску подсети и шлюз, а также локально администрируемый MAC-адрес, сообщаемый хосту.
DHCP server – управляет началом/концом пула аренды, временем аренды, необязательным DNS-сервером и суффиксом домена (опция 15).
WPAD – включает/выключает опцию 252 и задаёт URL, который будет передан подключённым хостам.
Static routes – включает опцию 121 и позволяет указать разделённый точкой с запятой список маршрутов в синтаксисе destination/prefix,gateway (например, 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) после изменения любых параметров.

Сетевое поведение

Устройство представляется как USB NCM Ethernet-адаптер с настроенным MAC-адресом.
Встроенный DHCP-сервер отвечает на сообщения DISCOVER/REQUEST настроенными параметрами.
Когда бесклассовые маршруты включены, опция 121 генерируется динамически.
WPAD включён и предоставлен непустой URL, поэтому хост загружает PAC-файл с указанного источника и применяет настройки прокси.

Использование механизма принуждения NTLM

В настоящее время для развёртывания требуется внешний сервер, предоставляющий прокси с NTLM-аутентификацией и принуждающий к аутентификации. Для этой задачи полезен Responder. Внешний сервер для размещения файла WPAD.DAT необязателен.

Предупреждения

Манипуляции с WPAD или статическими маршрутами могут перенаправлять трафик подключённой машины. Используйте эту прошивку только в контролируемых средах с информированным согласием.
Проект нацелен на лабораторные сценарии; он не реализует дополнительные средства контроля безопасности или сохранение конфигурации.

Тестирование

Данная прошивка протестирована на M5Stack AtomS3U и работает корректно.

Благодарности

Основано, в большей или меньшей степени, на официальных примерах TinyUSB NCM из ESP-IDF.
Отрефакторено и улучшено с помощью Codex.

Удачного (и ответственного) взлома!

USBCoercer

Популярное