지원 대상	ESP32-S3

USBCoercer: TinyUSB 기반 WPAD 강제 장치

USBCoercer는 네이티브 USB-OTG를 갖춘 ESP32 개발 보드를 WPAD를 통해 프록시 구성을 강제할 수 있는 Ethernet-over-USB 가젯으로 전환합니다. 이 프로젝트는 TinyUSB Network Control Model (NCM) 예제를 기반으로 하며, DHCP 옵션 252(WPAD/PAC)를 주입하는 초소형 DHCP 서버를 추가하고, 필요 시 EDR 텔레메트리를 차단하기 위해 클래스리스 정적 경로(옵션 121)도 추가합니다.

이 프로젝트는 보안 테스트 및 실험실 데모를 위해 제작되었습니다. 사용하기 전에 항상 명시적인 승인을 받으십시오.

주요 기능

TinyUSB 기반 USB NCM 이더넷 가젯
선택적 클래스리스 정적 경로(옵션 121)와 구성 가능한 WPAD/PAC URL(옵션 252)을 제공하는 내장 DHCP 서버
AtomS3U 하드웨어에서 네트워크 스택이 올라온 후 녹색, DHCP Discovery/Offer 단계 후 노란색, DHCP Request/ACK 완료 시 파란색으로 켜지는 상태 LED 표시등

요구 사항

하드웨어

네이티브 USB-OTG를 갖춘 ESP32-S3 보드
(일부 모델의 경우) SoC OTG 포트를 대상 머신에 연결하는 USB 케이블

소프트웨어

TinyUSB 지원이 활성화된 Espressif ESP-IDF v5.5(또는 그 이상)
표준 install.sh/export.sh 스크립트를 통해 설치된 ESP-IDF 툴체인 및 Python 환경
중요: 이 펌웨어는 espressif/esp_tinyusb의 1.x 브랜치로 개발되었으며 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
```

구성 참조

이 프로젝트는 idf.py menuconfig 안에 전용 USBCoercer Configuration 메뉴를 제공합니다:

인터페이스 – USB 측 IPv4 주소, 서브넷 마스크, 게이트웨이 및 호스트에 광고되는 로컬 관리 MAC 주소를 설정합니다.
DHCP 서버 – 임대 풀 시작/종료, 임대 시간, 선택적 DNS 서버 및 도메인 접미사(옵션 15)를 제어합니다.
WPAD – 옵션 252를 토글하고 연결된 호스트에 제공되는 URL을 정의합니다.
정적 경로 – 옵션 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)하십시오.

네트워크 동작

장치는 구성된 MAC 주소를 사용하여 USB NCM 이더넷 어댑터로 노출됩니다.
내장 DHCP 서버는 구성된 매개변수로 DISCOVER/REQUEST 메시지에 응답합니다.
클래스리스 경로가 활성화되면 옵션 121이 동적으로 생성됩니다.
WPAD가 활성화되고 비어 있지 않은 URL이 제공되므로 호스트는 지정된 오리진에서 PAC 파일을 검색하고 프록시 설정을 적용합니다.

NTLM 강제 메커니즘 사용

현재 배포는 NTLM 인증 프록시를 제공하고 인증을 강제하기 위해 외부 서버가 필요합니다. 이 작업에는 Responder가 유용합니다. WPAD.DAT 파일을 제공하는 외부 서버는 선택 사항입니다.

경고

WPAD 또는 정적 경로를 조작하면 연결된 머신의 트래픽이 리디렉션될 수 있습니다. 이 펌웨어는 정보에 입각한 동의가 있는 통제된 환경에서만 사용하십시오.
이 프로젝트는 실험실 시나리오를 대상으로 하며 추가 보안 제어나 구성 영속성을 구현하지 않습니다.

테스트

이 펌웨어는 M5Stack AtomS3U에서 테스트되었으며 정상적으로 작동했습니다.

감사의 말

공식 ESP-IDF TinyUSB NCM 예제를 가깝게든 멀리든 어느 정도 기반으로 합니다.
Codex로 리팩터링 및 개선되었습니다.

즐겁고(그리고 책임 있는) 해킹 되세요!

USBCoercer

인기