USBCoercer: TinyUSBベースのWPAD強制デバイス

USBCoercerは、ネイティブUSB-OTGを備えたESP32開発ボードを、WPADを介してプロキシ設定を強制できるEthernet-over-USBガジェットに変えます。これは**TinyUSB Network Control Model (NCM)**のサンプルに基づいており、必要に応じてEDRテレメトリをブロックするために、DHCPオプション252（WPAD/PAC）と、さらにクラスレス静的ルート（オプション121）を注入するミニマルなDHCPサーバーを追加しています。

このプロジェクトは、セキュリティテストとラボデモを目的としています。使用する前に必ず明示的な許可を得てください。

主な機能

• TinyUSBベースのUSB NCM Ethernetガジェット
• オプションのクラスレス静的ルート（オプション121）と設定可能なWPAD/PAC URL（オプション252）を提供する組み込みDHCPサーバー
• ステータスLEDインジケーター：AtomS3Uハードウェアでネットワークスタックが起動すると緑に、DHCP Discovery/Offerフェーズ後に黄色に、DHCP Request/ACKが完了すると青に変わります。

要件

ハードウェア

• ネイティブ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です。

クイックスタート

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メニューを公開しています。

• Interface – ホストに通知されるUSB側のIPv4アドレス、サブネットマスク、ゲートウェイ、およびローカル管理MACアドレスを設定します。
• DHCP server – リースプールの開始/終了、リース時間、オプションの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プール：3アドレス（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 Ethernetアダプターとして認識されます。
• 組み込みDHCPサーバーは、DISCOVER/REQUESTメッセージに設定されたパラメータで応答します。
• クラスレスルートが有効な場合、オプション121が動的に生成されます。
• WPADが有効で空でないURLが提供されるため、ホストは指定されたオリジンからPACファイルを取得し、プロキシ設定を適用します。

NTLM強制メカニズムの使用

現在、このデプロイには、NTLM認証プロキシを提供し認証を強制するための外部サーバーが必要です。Responderがこの用途に役立ちます。WPAD.DATファイルを配信する外部サーバーはオプションです。

警告

• WPADや静的ルートを操作すると、接続されたマシンからのトラフィックがリダイレクトされる可能性があります。このファームウェアは、インフォームドコンセントを得た管理された環境でのみ使用してください。
• このプロジェクトはラボシナリオを対象としており、追加のセキュリティ制御や設定の永続化は実装されていません。

テスト

このファームウェアはM5Stack AtomS3Uでテストされ、正常に動作しました。

謝辞

• 公式のESP-IDF TinyUSB NCMサンプルに、多かれ少なかれ基づいています。
• Codexを使用してリファクタリングおよび改善されました。

楽しく（そして責任を持って）ハッキングしましょう！