Network Extension: プロキシ設定なしで Mac の通信をキャプチャ
5 分で読めます
Proxyman が Network Extension に対応しました 🎉
Mac 上のアプリやスクリプトの HTTP/HTTPS 通信をキャプチャできます。システムのプロキシを無視するアプリも対象です。アプリごとにプロキシを設定する必要はありません。
このブログでは、次の内容を解説します：
- 通常のプロキシモードの問題点。
- Network Extension が取りこぼした通信をキャプチャする仕組み。
- 有効にする方法と、既存のデバッグツールの使い方。
- Automatic Setup を使って、Node.js、Ruby、Python の SSL エラーを解決する方法。
Network Extension は BETA で、デフォルトではオフになっています。Proxyman PRO と macOS 26 以降 が必要です。
1. 通常のプロキシモードの問題点
通常のプロキシモードは、macOS に HTTP/HTTPS プロキシを設定して動作します。この設定に従うアプリは、リクエストを Proxyman 経由で送信します。
ただし、システムのプロキシを使わないアプリやライブラリもあります：
- リクエストの取りこぼし: ブラウザの通信は表示されるのに、スクリプトやバックエンドサーバーからのリクエストが表示されないことがあります。
- 個別のプロキシ設定: Node.js、Ruby、Python、コマンドラインツールは、ライブラリによっては独自のプロキシ設定が必要になる場合があります。
- コードの変更: ライブラリによっては、コード内でプロキシアドレスを直接渡す必要があります。
- 設定の繰り返し: 別のプロジェクトや HTTP ライブラリに切り替えるたびに、プロキシを設定し直す必要があります。
リクエスト自体はサーバーに届きますが、Proxyman は経由しません。ライブラリごとに手作業で設定すると時間がかかり、設定ミスの原因にもなります。
2. 解決策: Network Extension ✅
Network Extension は、システムレベルで HTTP/HTTPS 接続をキャプチャし、Proxyman 経由にルーティングします。アプリが macOS のプロキシ設定を無視していても、リクエストをキャプチャできます。
- アプリごとにプロキシアドレスを入力する必要はありません。
- Proxyman 経由にするためだけに、アプリのコードを変更する必要はありません。
- 上のスクリーンショットのように、
--proxyフラグなしで cURL を実行できます。 - Proxyman がリクエストをキャプチャしている間も、アプリやスクリプトを普段どおり使えます。
これはトランスペアレントプロキシと呼ばれる方式です。接続のルーティングは macOS が行うため、アプリ自身がプロキシを管理する必要はありません。
Apple の公式 Network Extension API を基盤に
- Apple の公式な トランスペアレントプロキシ用 Network Extension API を使用しています。
- Proxyman が開発・保守する、ネイティブの macOS システム拡張 として動作します。
- 当社の TablePlus Inc Developer ID 証明書 で署名され、Apple の公証 (notarization) を受けています。
- macOS の標準的な拡張機能の設定からインストールし、承認します。
目標は、Apple のネイティブなネットワーク API を使って高速かつ効率的にキャプチャし、デバッグを始める前の設定を減らすことです。
Network Extension は通信のキャプチャを担当します。HTTPS の内容を読むには、アプリが Proxyman の証明書を信頼している必要があり、アプリまたはドメインで SSL Proxying が有効になっている必要があります。
3. 何ができるのか？
キャプチャしたリクエストは、普段お使いの Proxyman のツールでそのまま扱えます：
- 🔎 リクエストとレスポンスの確認: URL、クエリパラメータ、ヘッダー、Cookie、ボディを確認できます。サーバーが返したレスポンスのステータスとデータも確認できます。
- 🧹 通信のフィルタリング: デバッグしたいアプリやドメインに絞り込み、無関係なリクエストを一覧から非表示にできます。
- 📁 Map Local: 保存したレスポンスを返すことで、バックエンドを変更せずにさまざまなデータをテストできます。
- ✍️ Breakpoint: リクエストまたはレスポンスを一時停止して編集し、アプリがその変更をどのように処理するか確認できます。
- ⚙️ Scripting: テスト中に独自のルールを適用して、リクエストとレスポンスを変更できます。
次のような場合に役立ちます：
- ローカルのバックエンドサーバーが行う API 呼び出しを確認したいとき。
- Ruby や Python のスクリプトがサービスに送信している内容を確認したいとき。
- プロキシ設定のない Mac アプリの通信をキャプチャしたいとき。
- 複数のアプリのリクエストを、アプリごとに設定せずにデバッグしたいとき。
4. Network Extension を有効にする方法
- 最新の macOS 版 Proxyman をダウンロードして開きます。
- Settings → Network Extension を開きます。
- Enable Network Extension をオンにし、表示された場合は Install and Enable をクリックします。
- macOS の指示に従って、System Settings → General → Login Items & Extensions → Network Extensions で Proxyman を有効にします。
- macOS からネットワーク構成の追加を求められたら、Allow をクリックします。
- Proxyman を開いたままにして、アプリまたはスクリプトから新しいリクエストを送信します。
HTTPS を確認する場合は、次の手順を行います：
- Mac に Proxyman の証明書をインストールして信頼します。
- 確認したいアプリまたはドメインで SSL Proxying を有効にします。
- 新しいリクエストを送信し、Proxyman でそのリクエストを選択して内容を確認します。
覚えておきたい点がいくつかあります：
- 拡張機能を有効にする前から起動しているアプリは、再起動してください。新しい接続を開くようになります。
- Network Extension 経由のキャプチャを止めたいときは、Settings で Enable Network Extension をオフにします。
- この機能が対象とするのは、Mac 上のアプリの通信です。iPhone や Android デバイスの場合は、別のデバイス設定ガイドに従ってください。
インストール時のスクリーンショットはすべて、Network Extension のドキュメント をご覧ください。
5. トラブルシューティング: Node.js、Ruby、Python の SSL エラー
問題
HTTPS の確認を有効にしたあと、スクリプトで SSL または証明書のエラーが報告されます。
- これらのランタイムは、独自の証明書設定を使っている場合があります。
- macOS で Proxyman の自己署名証明書を信頼するだけでは、使用しているライブラリには不十分な場合があります。
- Network Extension は通信を Proxyman 経由にしますが、すべてのランタイムで証明書の信頼設定を自動的に行うわけではありません。
解決策: Automatic Setup スクリプトを使う ✅
Proxyman の Automatic Setup は、対応しているライブラリ向けに、プロキシと証明書の設定を準備します。
- Proxyman → Setup → Automatic Setup を開きます。
- Open New Terminal をクリックします。
- 必要に応じて、権限の確認を承認します。
- その新しいターミナルでスクリプトを実行するか、バックエンドサーバーを再起動します。
- アプリまたはドメインで SSL Proxying を有効にしたまま、もう一度リクエストを試してください。
注意点：
- この設定は、Proxyman が開いたターミナルセッションにのみ適用されます。
- 別のターミナルで実行中のスクリプトやサーバーには、この設定は反映されません。停止して、新しいターミナルで実行し直してください。
- Automatic Setup は、普段お使いのシェルの設定ファイルを変更しません。
- Automatic Setup で通信をキャプチャしている場合は、Network Extension をオフにしても、設定済みのターミナルでコードの実行を続けられます。
それでもエラーが続く場合は、Automatic Setup のトラブルシューティングガイド を確認してください。
関連ブログ
