HN 日本語サマリー

← 一覧へ戻る
プログラミング

ESP32-C3 Adblock

ESP32-C3 Adblock (github.com)

154 pointsby jayhoon60 コメント

要約

ESP32-C3マイクロコントローラー上で動作する、Pi-holeスタイルのDNS広告ブロッカー「ESP32-C3 Adblock」が開発されました。このプロジェクトは、ブロックリストをRAMに保持する必要がなく、フラッシュメモリにソートされた40ビットハッシュとして保存することで、PSRAM不要で約0.7MBのフラッシュと約50KBのRAMで140,000以上のドメインを約10ミリ秒で処理できる革新的な手法を採用しています。

全文翻訳

esp32-c3-adblock

日本語 README

2ドルのESP32-C3で動作するPi-holeスタイルのDNS広告ブロッカー — PSRAM不要。

📰 Tom's Hardware, XDA Developers, および Korben で紹介されました。

みんなが見落としているトリック:ブロックリストをRAMに保持する必要はありません。ドメインをフラッシュメモリにソート済みの40ビットハッシュとして保存し、バイナリサーチします。140,000件以上のドメインが約0.7MBのフラッシュに収まり、約50KBのRAMを使用して約10ミリ秒でマッチングできます。

クエリ入力 ──▶ ドメイン抽出 ──▶ FNV-1aハッシュ (+親サフィックス)
         ──▶ フラッシュハッシュテーブルのバイナリサーチ
              ├─ ヒット ──▶ 0.0.0.0 を応答 (シンクホール)
              └─ ミス ──▶ アップストリームリゾルバに転送、応答を中継

なぜこれが興味深いのか

ほとんどのESP32 DNSシンクホールはブロックリスト(ドメイン文字列)をRAMにロードするため、PSRAMを要求します。このプロジェクトは代わりに、固定の5バイト(40ビット)ハッシュをフラッシュメモリに保存します。

RAM上の文字列アプローチこちら(フラッシュ上のハッシュ)
ハードウェアESP32 + PSRAM (約8ドル)ESP32-C3、PSRAM不要 (約2ドル)
141kドメイン約2.5MBのRAM0.67MBのフラッシュ
使用RAMそのほとんど約50KB
ルックアップ文字列比較約18回のフラッシュ読み込み(WiFi RTT込みで約10ms)
コリジョンなし141kで0、537kで1(つまり、1つの不運なドメインが過剰にブロックされる)

なぜ40ビットなのか? このフラッシュ予算にとって最適なビット数です。コリジョンはバースデー問題に従います — 141kドメインで約0、537kで約1(つまり、1つの不運なドメインが過剰にブロックされます)。32ビットに落とすとフラッシュの20%が節約できますが、250kで約7回のコリジョンが発生します。64ビットにすると、問題がないのにドメインあたり3バイトが無駄になります。

同じトリックはより大きなチップでも機能します — これはC3固有の回避策ではありません。16MBのESP32-S3では、これらのハッシュは8MBのPSRAMの文字列の場合の約466kに対し、約2.7Mドメインを保持します。フラッシュ上のハッシュはPSRAM上の文字列よりも基本的にあらゆる面で優れています。C3はそれを否定できないものにしているだけです。

ハードウェア

  • ESP32-C3ボード(C3 SuperMiniでテスト済み)、4MBフラッシュ、PSRAM不要
  • クラシックなESP32(DevKit / WROOM、4MB)もビルド可能:pio run -e esp32dev -t upload(コミュニティ提供、コンパイルテスト済み;C3がテスト対象)
  • 安定したUSB電源(携帯充電器またはルーターのUSBポート)から給電してください。安価で緩いUSB-C→Aアダプターは、WiFi送信中に無線機を不安定にする可能性があります。
  • USB-A → USB-Cドングルを使用すると、ほとんどのルーターの空きUSBポートに直接接続できます — 電源不要、追加の箱不要。
エンクロージャー

C3 SuperMini用のプリント可能なケース:hardware/esp32-c3-supermini-enclosure.stl

印刷のヒント:

  • サポート不要;0.2mmレイヤー、約15%のインフィルで十分です。
  • アンテナ端をクリアに保ってください。 C3のPCBアンテナはUSB-Cポートの反対側の短いエッジにあるジグザグトレースです — 固体プラスチックに埋め込んだり、金属を近づけたりしないでください。そうしないと、RSSIが悪化します。
  • 通気孔を開けておいてください:ボードはアイドル時に約45~55℃です。

ビルドとフラッシュ(PlatformIO)

最初のUSBフラッシュで起動できます — その後は、ファームウェアとブロックリストの両方がWiFi経由で更新されます(下記参照)。

⚠️ 最新のPlatformIOを使用してください — VSCode PlatformIO拡張機能のバンドルコア、またはvenvでpip install -U platformioを使用してください。ディストリビューション/aptのplatformioパッケージ(例: 4.3.4)は古すぎてAttributeError: ... 'resultcallback'(issue #4)で失敗します。ワンクリックブラウザインストーラーが準備中です(ホスティングは未定)。

# 1. secretsテンプレートをコピー(gitignoreされており、ローカルに留まります)して編集します:
#    - WIFI_SSID / WIFI_PASS はオプションです — プレースホルダーを残して、
#      代わりにオンデバイスセットアップポータルを使用してください(下記参照)。
#    - WEB_USER / WEB_PASS / OTA_PASS は必須です:これらはダッシュボードの
#      状態変更エンドポイント(/ban, /addblock, /upload, /update, /setupdate,
#      /forgetwifi)およびネットワークOTAを保護します。実際の値を設定してください — これらは以前はLAN上の誰でもアクセス可能でした。
cp src/secrets.example.h src/secrets.h
#    その後 src/secrets.h を編集します

# 2. ブロックリストハッシュテーブルをビルドします(デフォルト = StevenBlackベース + Hagezi Light、
#    約100kエントリ、WhatsApp/ソーシャルメディア対応)
python3 tools/build_blocklist.py data/blocklist.bin

# 3. ファームウェア + ブロックリストファイルシステムをフラッシュします(最初で最後のUSBフラッシュ)
pio run -t upload
pio run -t uploadfs

# 4. 起動を監視し、IPをメモするかダッシュボードを開きます
pio device monitor          # -> http://c3adblock.local
独自のブロックリスト

build_blocklist.py OUT.bin [SOURCE ...] は、URLとローカルファイルの任意の組み合わせを受け付けます。以下のいずれかの形式です:

  • hostsファイル — 0.0.0.0 ads.example.com tracker.example.com(行内のすべてのドメインが含まれます)
  • プレーンなドメインリスト — 1行に1ドメイン
  • AdGuard / Adblock基本ルール — ||ads.example.com^はブロック、@@||ok.example.com^はドメインを許可(例: AdGuard Homeの許可リストをミラーリング)

ブロックされたドメインはサブドメインもブロックします。DNSハッシュリストでは表現できないルール(正規表現、ワイルドカード、$修飾子、コスメティック##ルール)はスキップされ、カウントされます。@@ルールはそのエントリのみを許可します — ブロックされた親からサブドメインを切り出すことはできません。ソースがダウンロードできない場合、ビルドはリストをサイレントに生成する代わりに停止します(--allow-missingで上書き可能)。

WiFiセットアップ(再フラッシュ不要)

接続できない場合(またはsecrets.hを設定しなかった場合)、オープンアクセスポイントC3-AdBlock-XXXXとキャプティブポータルが起動します — スマートフォンから接続し、ネットワークを選択してパスワードを入力すれば完了です。後で新しいネットワークに移動するには、ダッシュボードのForget WiFiをクリックするか、電源投入時にBOOTボタンを押し続けると、セットアップポータルが再度表示されます。(/forgetwifiは現在認証が必要なため、単にアクセスできるURLではなくなりました。セキュリティを参照してください。)

オーバー・ザ・エア(OTA)アップデート(USB不要)

http://c3adblock.local のダッシュボードですべてを行います:

  • ブロックリスト — 新しくビルドしたblocklist.binをBlocklist → Uploadにドロップするか、Remote auto-updateでURLを設定すると、デバイスはスケジュールに従ってプリビルドされたblocklist.binを取得します。デフォルトの新しいリストは毎週月曜日にGitHub Actionsによって再ビルドされ、安定したURLで公開されるため、これを一度貼り付けるだけでデバイスは自動的に最新の状態に保たれます:https://github.com/M-Abozaid/esp32-c3-adblock/releases/download/blocklist/blocklist.bin

  • ファームウェア — Firmware → OTA updateの下で.pio/build/c3/firmware.binをアップロードします。デバイスはそれを検証して新しいイメージにリブートします。またはCLIからWiFi経由でプッシュします:

    pio run -t upload --upload-port c3adblock.local --upload-protocol espota
    

4MBフラッシュのトレードオフ: ファームウェアOTAには2つのアプリスロットが必要で、ブロックリストには約1.3MBが残ります(最大約250kドメイン)。アグレッシブな537k「アルティメット」リストは、シングルアプリパーティションテーブル(ファームウェアOTAなし)にのみ収まります。partitions.csvでトレードオフを選択してください。

セキュリティ

ダッシュボードの読み取り専用ビュー(/, /stats.json)は公開されたままですが、状態を変更するすべてのエンドポイントにはHTTP Basic Auth(secrets.hのWEB_USER/WEB_PASS)が必要です:

  • /ban, /addblock, /unblock, /forgetwifi
  • /upload, /update(ブロックリストとファームウェアOTA)
  • /setupdate, /fetchnow

ネットワークOTA(ArduinoOTA、例: pio run -t upload --upload-port c3adblock.local --upload-protocol espota)には、同じファイルのOTA_PASSが必要です。

これがないと、LAN上のデバイスに到達できる誰でも、認証なしで任意のファームウェアにリフラッシュしたり、ブロックリストを書き換えたりできます — ネットワーク上のすべてのDNSクエリのパスにデバイスが存在することを考えると、知っておく価値があります。カスタムブロックドメイン名もダッシュボードに表示される前にHTMLエスケープされるため、マークアップを含むドメイン文字列(/addblock経由で追加されたもの)がビューアのブラウザで実行される可能性があった格納型XSSパスが閉じられます。

ここでのBasic Authは暗号化ではなく、LANトラスト境界の制御です。 すべては:80でプレーンHTTPです — このチップにはTLSサーバーを実行する現実的な予算がありません。Basic Authの認証情報はBase64(暗号化されていない)で、認証された各リクエストで送信されます。LANトラフィックをスニッフィングできる人(オープン/ゲストWiFi、ARPスプーフィング)は、ワイヤーから読み取ることができます。これは、認証情報なしでAPIにアクセスするネットワーク上の他のデバイス、またはそれをCSRFするブラウザタブに対する一般的なケースを強化するものであり、オンパスネットワーク攻撃者に対するものではありません。

キャッシュされたBasic AuthによるCSRF: ブラウザは、既に認証されたオリジンへのあらゆる後続リクエストに、キャッシュされたBasic Auth認証情報を自動的に添付します — 同じブラウザが後でアクセスする全く関係のないページ(例: <img src="http://c3adblock.local/forgetwifi">、JS不要)であってもです。これにより、ダッシュボードに一度ログインすると、LAN上に誰がいるかに関わらず、任意のウェブページがこのAPIをサイレントに操作できるようになります。上記のすべての変更エンドポイントは、カスタムX-Requested-With: c3-adblockヘッダーも必要とします。これはプレーンな<img>/自動送信された<form>CSRFでは添付できません(同じオリジンのfetch()のみが可能で、ダッシュボード自身のJSが行うことです)。これが、/forgetwifiが直接アクセスできるプレーンなURLではなくなった理由です。代わりにダッシュボードボタンを使用してください。

デフォルトの認証情報: secrets.hにsecrets.example.hからのプレースホルダーCHANGE_ME_WEB_PASSWORD / CHANGE_ME_OTA_PASSWORD値がまだ残っている場合、デバイスはパブリックな「パスワード」で起動します(このリポジトリの例ファイルにあります)。ファームウェアはシリアル経由で警告ログを記録し、ダッシュボードにバナーを表示しますが、それでも起動して実行されるため、完全に制御していないネットワークでこれを信頼する前に、secrets.hに実際の値を設定することをスキップしないでください。

現時点では対象外:WiFiセットアップポータルのアクセスポイント(C3-AdBlock-XXXX)は、設計上まだオープン(暗号化なし)です — パスワードを知らなくても接続できる必要があります。ポータルで入力する実際のWiFiパスワードは、セットアップウィンドウ中のローカル無線リンクと同じくらい安全です。

使用方法

デバイスのDNSをC3のIPにポイントするか、メインDNSのセカンダリリゾルバとして追加します。テスト:

dig @<c3-ip> doubleclick.net   # -> 0.0.0.0  (ブロック済み)
dig @<c3-ip> github.com        # -> 実IP  (転送済み)

注意点(苦労して学んだこと)

  • ModemManager(Fedora/Ubuntuのデフォルト)は/dev/ttyACM0を掴み、DTR/RTSをトグルするため、C3をリセットし、シリアルをブロックします。修正方法:

    sudo systemctl stop ModemManager
    echo 'ATTRS{idVendor}==