メインコンテンツまでスキップ

Proxyman の WebSocket キャプチャ

Web ブラウザ、iOS の実機とシミュレータ、Android、NodeJS や Python のサーバーから、Proxyman で WebSocket（WS/WSS）通信をキャプチャして復号できます。

1. 概要​

Proxyman では、WebSocket（WS）と Secure WebSocket（WSS）の通信をキャプチャして、簡単にプレビューできます。

  • iOS の実機と iOS シミュレータから WS/WSS をキャプチャ（Atlantis framework が必要）
  • Web ブラウザと Mac アプリから WS/WSS をキャプチャ
  • Android の実機と Android エミュレータから WS/WSS をキャプチャ
  • WebSocket メッセージを整形して表示
  • All / Sent / Received でメッセージをフィルタ
  • JSON / Tree Preview / HEX 形式で内容を表示
  • カラムをカスタマイズ：Frame、Length、Data、Time など
  • 可能な場合、バイナリメッセージを JSON に自動でデコード
  • Sublime や VS Code などの外部エディタで WebSocket メッセージを開く
  • Scripting で WebSocket メッセージを編集、ドロップ、送信（macOS 版 Proxyman 26.2.0 以降、Windows/Linux 版 Proxyman 26.1.0 以降）

2. Web ブラウザから WS/WSS をキャプチャ​

localhost の WebSocket​

Proxyman は、Automatic Setup を使えば、Google Chrome から ws://localhost:3000 などの localhost WebSocket をキャプチャできます。

  1. Setup メニュー → Automatic Setup… を開きます
  2. Google Chrome を選択します（New Profile または Current Profile）。新しい Google Chrome のウィンドウが開きます
  3. このウィンドウで localhost の WebSocket ページを開きます。Proxyman がキャプチャします

本番環境の WebSocket​

Proxyman は、設定なしで Google Chrome からの WS/WSS 通信を自動的にキャプチャします。

  1. Proxyman と Google Chrome を開きます
  2. WS/WSS の通信を発生させます。たとえば https://echo.websocket.org/.ws を開きます
  3. Proxyman で WS/WSS のデータを確認します

Protobuf ペイロードを含む WebSocket​

Proxyman macOS 6.5.0 以降では、WebSocket メッセージ内の Protobuf をデコードできます。

  1. まず、Proxyman で WebSocket 通信をキャプチャできる状態にします
  2. WebSocket の Protobuf メッセージを右クリック → Protobuf → Decode Raw Text… または Decode with Message Type… を選択します
  • Raw mode：Protobuf の desc ファイルがない場合に便利です。
  • Message Type：Protobuf の desc ファイルにある Message Type を使用します。
バイナリの WebSocket メッセージを右クリックした Proxyman のメニューで、Protobuf、Decode Raw Text、Decode with Message Type が表示されている画面

Protobuf で WebSocket のペイロードをデコード

3. iOS から WS/WSS をキャプチャ​

アプリが URLSessionWebSocketTask や、Starscream、SocketRocket などの iOS 向け WebSocket ライブラリを使っている場合、Proxyman では WS/WSS 通信をキャプチャできないことがあります。

  • 理由：これは Apple の設計によるものです。URLSessionWebSocketTask はシステムの HTTP プロキシを使用しません。WS/WSS の通信はすべてインターネットに直接送られるため、Proxyman や Charles Proxy ではキャプチャできません。
  • サンプルアプリ：https://github.com/ProxymanApp/websocket-example-ios-app

✅ 解決策 1（iOS 17 以降向け、推奨）​

  1. iOS デバイスまたは iOS シミュレータ のセットアップガイドに従ってください。証明書がデバイスにインストールされ、信頼されていることを確認します。
  2. Proxyman で Tools → Proxy Settings → SOCKS Proxy Settings… を開き、有効にします。ポート番号を控えておきます。
  3. Proxyman のメインウィンドウのツールバーで、現在の IP アドレスを確認します。
IP 192.168.64.4、Proxy Port 9090、Recording、macOS proxy と Network Extension のトグルが表示されている Proxyman のステータスポップオーバー

Proxyman の現在の IP を確認

  1. アプリで SOCKS プロキシを設定します。スイッチなどで切り替えられるようにし、デバッグビルドでのみ有効にしてください。リリースビルドにはこの設定を含めないでください。
  • NWConnection の場合
let parameters = webSocketURL.scheme == "wss" ? NWParameters.tls : NWParameters.tcp

let options = NWProtocolWebSocket.Options()
options.autoReplyPing = true

parameters.defaultProtocolStack.applicationProtocols.insert(options, at: 0)

if #available(iOS 17.0, *) {
    let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) //  Please replace x.x.x.x with a real Proxyman IP
    let config = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy)
    let context = NWParameters.PrivacyContext(description: "my socksv5Proxy")
    context.proxyConfigurations = [config]

    parameters.setPrivacyContext(context)
}

let connection = NWConnection(to: .url(webSocketURL), using: parameters)
connection.start(queue: .main)
  • URLSession と URLSessionWebSocketTask の場合
private lazy var urlSession: URLSession = {
    let config = URLSessionConfiguration.default
    if #available(iOS 17.0, *) {
        let socksv5Proxy = NWEndpoint.hostPort(host: "x.x.x.x", port: 8889) //  Please replace x.x.x.x with a real Proxyman IP
        let proxyConfig = ProxyConfiguration.init(socksv5Proxy: socksv5Proxy)
        config.proxyConfigurations = [proxyConfig]
    }

    return URLSession(configuration: config, delegate: nil, delegateQueue: nil)
}()
  1. 完了です ✅
iOS シミュレータで URLSessionWebSocketTask を使うアプリの wss://echo.websocket.org の WebSocket メッセージを、Proxyman がキャプチャしている画面

Proxyman で iOS の WebSocket をキャプチャ

✅ 解決策 2​

Atlantis Framework（Proxyman 開発）を使うと、iOS の URLSessionWebSocketTask による WS/WSS 通信をキャプチャできます。

詳しくは Atlantis の WS/WSS 通信ガイド をご覧ください。

4. Web ブラウザ（Chrome、Safari など）から WebSocket をキャプチャ​

  • Proxyman は、設定なしで Web ブラウザからの WS/WSS 通信をキャプチャできます。
  • 使い方：Google Chrome を開く → WS/WSS 接続を行う Web サイトにアクセスする → Proxyman を開き、WebSocket のドメインを探す → Response パネルで、これらのドメインの Enable SSL Proxying をクリックする。ブラウザで Web サイトを再読み込みします。Proxyman が WS/WSS をキャプチャして復号します ✅

5. NodeJS、Golang、Python サーバーから WebSocket をキャプチャ​

  • Proxyman は、NodeJS、Golang、Python、Ruby のサーバーからの WS/WSS 通信をキャプチャできます。
  • 使い方：automatic-setup.md に従い、Proxyman が開くターミナルでサーバーを起動 → WS/WSS 接続を行う → Proxyman が自動的にキャプチャして復号します ✅

6. localhost と本番環境の間で WebSocket をマップ​

localhost と本番環境の間の WebSocket 通信もマップできます。詳しくは Map Remote ツール をご覧ください。

7. Scripting で WebSocket メッセージを変更​

macOS 版 Proxyman 26.2.0 以降、および Windows/Linux 版 Proxyman 26.1.0 以降では、数行の JavaScript で WebSocket メッセージをその場で変更できます。Scripting のルールで Modify WebSocket Messages にチェックを入れ、onWebsocket() を使って次のことができます：

  • テキストまたはバイナリのメッセージを、両方向で編集する
  • メッセージをドロップし、相手に届かないようにする
  • クライアントまたはサーバーに新しいメッセージを送信する
  • WebSocket を閉じて、アプリの再接続の動作をテストする
function onWebsocket(context, url, request, response, message) {
  if (message.from === "server" && message.type === "text") {
    message.data = message.data.replace("staging.example.com", "api.example.com");
  }
  return message;
}

WebSocket メッセージを変更するProxyman Scripting の onWebsocket() で、WebSocket（WS/WSS）メッセージをその場で編集、ドロップ、送信できます。テキストとバイナリの両方向に対応しています。

関連情報​

に最終更新