ApiCatcher 即時同步使用說明

把手機抓到的 HTTP/HTTPS 流量，即時送到電腦或其他系統。

1. 功能說明

ApiCatcher 在 iOS、Android 上用 VPN 抓包後，會透過 WebSocket 把資料串流送到區網裡的接收端。一開始抓就會送，不必等這次抓包結束再匯出檔案。

接收端	用途	怎麼接
ApiCatcher Desktop	在電腦上檢視、分析及重送封包	掃描 Desktop 的 QR Code
Burp Suite 擴充套件	在 Burp 做安全測試	掃描擴充頁面上的 QR Code
自訂接收端	接到自己的服務或內部系統	填 `ws://` 並測通

一次只能開一種。打開其中一個，另外兩個會關掉。

2. 可以做什麼

在電腦上看封包。 JSON 很大、Header 很長、Body 是二進位時，手機不好讀。接到 Desktop 之後可以在電腦上解析、比對、重放。

送到 Burp Suite。 安裝 ApiCatcher for Burp Suite Extension，手機抓到的封包可以進 Site map 或 Proxy History，再丟到 Repeater、Intruder。手機用 VPN 抓，電腦不用設系統代理。

接到 API 安全檢測或 DLP。 測試 App 時打開抓包和即時同步，流量進你們自己的檢測平台，掃身分證字號、手機號碼、Token、金鑰，找出可能造成資料外洩的 API，再把報告寄給開發或測試。

用真實流量更新 API 文件。 接收端對照歷史欄位，發現請求或回應裡可能多出來的欄位，再用大型語言模型補用途和註解，寄信通知文件負責人。

給自動化或 Mock 用。 把完整請求存起來當測試資料，或拿去產生 Mock。

3. 開始之前

要解密 HTTPS，請先安裝並完全信任 ApiCatcher 根憑證。
手機和接收端連同一個 Wi-Fi。基於資料安全，目前只支援區網 ws://，不支援 wss://，流量不會離開區網。
電腦或伺服器防火牆要放行接收埠（例如 8080）。
先把接收端跑起來，再到 App 裡測連線。

4. 打開即時同步

打開 ApiCatcher，進入抓包首頁。
點右上角「+」。
選擇 Real-time Sync。
上方有三個分頁：Desktop / Burp Suite / Custom Receiver。

開啟後，首頁會顯示 Real-time Sync Active，以及接收端的 Online 或 Offline 狀態。點這則提示可以回到設定頁。

5. 接到 ApiCatcher Desktop

到 apicatcher.net 下載並打開 ApiCatcher Desktop。
在 Desktop 啟動即時同步接收端，畫面上會出現 QR Code。
手機開啟 Real-time Sync → Desktop。
點選 Scan QR Code，掃描 Desktop 上的 QR Code。
掃描成功後會看到接收端位址和 Online 狀態。
開啟 Enable。
回首頁，啟動 VPN 抓包，去目標 App 操作，Desktop 上應該陸續出現請求。

若顯示 Offline，先確認 Desktop 還在執行、手機和電腦在同一網段，再點選 Rescan。

ApiCatcher Desktop 即時同步接收端

6. 接到 Burp Suite

擴充說明：ApiCatcher for Burp Suite Extension

下載擴充套件 .jar（或自行編譯），在 Burp 的 Extensions → Installed → Add 以 Java 擴充載入。
打開上方的 ApiCatcher 分頁，確認 WebSocket 服務已啟動；沒有的話按 Start Server。
手機開啟 Real-time Sync → Burp Suite，掃描擴充頁面上的 QR Code。
開啟 Enable，再開始抓包。
預設進 Target → Site map。要看完整請求／回應，把同步目標改成 Proxy → HTTP history。進 History 的請求會帶 X-ApiCatcher-RequestId。
之後可以送到 Repeater、Intruder。

同步有問題時，到 Extensions → Installed 選這個擴充，看下方的 Output / Errors。

ApiCatcher for Burp Suite 擴充設定

7. 接到自訂接收端

先在電腦或內網把接收端跑起來（見第 8 節）。位址類似 ws://192.168.1.75:8080。
手機開啟 Real-time Sync → Custom Receiver。
在 Remote URL 填入 ws://IP:連接埠。欄位旁的 Documentation 會開啟協議說明。
點選 Test Connection，成功後位址會儲存。
開啟 Enable Real-time Streaming。位址空白或連線測試失敗時，無法開啟這個選項。
修改位址後，這個選項會關閉；請重新測試連線後再開啟。
開始抓包，接收端應該開始收到 JSON 文字訊框。

不要填 http:// 或 wss://。也不要填 127.0.0.1，那是手機自己。

8. 自訂接收端怎麼實作協議

說明：README_zh.md
倉庫：apicatcher-realtime-sync-protocol
Java SDK：apicatcher-sync-sdk-java

8.1 連線

角色	誰
WebSocket Client	ApiCatcher App
WebSocket Server	你的接收端

用區網 ws://（基於資料安全，不支援 wss://，流量不離開區網）
斷線後 App 會自己重連
斷線期間抓到的資料，以及只傳送一部分的資料片段，都會丟棄且不會補傳
一條連線上會交錯推多個請求，一定要用 requestId 分組

8.2 訊息格式

每則都是 JSON Text Frame：

{
  "type": "http",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "event": "req_start",
  "timestamp": 1711268370123,
  "payload": {}
}

欄位	意思
`type`	目前是 `http`
`requestId`	一筆請求的 UUID，資料片段依此分組
`event`	見下面幾個事件
`timestamp`	毫秒時間戳記
`payload`	這個事件的資料

8.3 事件

一筆請求通常是：

req_start → req_body* → res_start → res_body* → req_end

req_body / res_body 可能不會出現，也可能出現多次。沒有 Body 就不會送出對應事件。

req_start，請求送出：

{
  "type": "http",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "event": "req_start",
  "timestamp": 1711268370123,
  "payload": {
    "url": "https://api.example.com/data",
    "method": "POST",
    "httpVersion": "HTTP/1.1",
    "headers": [{"name": "User-Agent", "value": "ApiCatcher/1.0"}]
  }
}

收到後依 requestId 建立一筆快取紀錄，記下 URL、方法和請求標頭。

req_body / res_body，Body 資料片段：

{
  "type": "http",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "event": "res_body",
  "timestamp": 1711268370123,
  "payload": {
    "data": "eyBzdWNjZXNz..."
  }
}

payload.data 是經 Base64 編碼的二進位資料。資料會依序送出；WebSocket 建立在 TCP 上，因此接收順序就是傳送順序。請依抵達順序解碼並串接。大型 Body 會拆成多個資料片段（約 16KB～32KB），不要等到完整 Body 全部到齊後才處理。

res_start，回應標頭到了：

{
  "type": "http",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "event": "res_start",
  "timestamp": 1711268370123,
  "payload": {
    "status": 200,
    "httpVersion": "HTTP/1.1",
    "headers": [{"name": "Content-Type", "value": "application/json"}]
  }
}

req_end，這筆請求結束：

{
  "type": "http",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "event": "req_end",
  "timestamp": 1711268370123,
  "payload": {
    "error": null,
    "timings": {
      "send": 0,
      "wait": 150,
      "receive": 5
    }
  }
}

error 為 null 表示正常結束，否則是 "Timeout"、"Connection Aborted" 這類說明
timings 單位是毫秒：送出、等待回應、接收回應
收到 req_end 再拼成完整紀錄，然後清掉這筆快取
WebSocket 斷開時，還沒收到 req_end 的紀錄全部丟掉

8.4 組裝

連線建立
  └─ map: requestId → 組裝中的請求

收到 JSON 文字訊框
  ├─ req_start  → 新建，寫入 url / method / headers
  ├─ req_body   → Base64 解碼，接到請求 Body
  ├─ res_start  → 寫入 status / 回應標頭
  ├─ res_body   → Base64 解碼，接到回應 Body
  └─ req_end    → 寫入 error / timings，交給後續業務邏輯，從 map 刪掉

連線中斷
  └─ 清空 map，半成品不要當成完整請求

掃描、寫入資料庫或更新文件，都要等到收到 req_end 之後再做。接收資料片段時，Body 還不完整。

8.5 用 Java SDK

apicatcher-sync-sdk-java 負責 WebSocket 服務和資料片段組裝。一筆請求完整後，會透過回呼傳回一筆 HAR 1.2 entry 格式的 JSON（不是完整的 HAR 檔案）。

環境：JDK 11+，Maven 3.x+。

實作監聽：

import com.apicatcher.sync.TrafficListener;

public class StandardConsoleListener implements TrafficListener {
    @Override
    public void onTrafficReceived(String harJson) {
        System.out.println("收到一筆完整請求:");
        System.out.println(harJson);
    }
}

啟動：

import com.apicatcher.sync.ApiCatcherReceiver;

public class App {
    public static void main(String[] args) {
        int port = 8080;
        ApiCatcherReceiver receiver =
            new ApiCatcherReceiver(port, new StandardConsoleListener());
        receiver.start();
        System.out.println("監聽連接埠 " + port);
    }
}

手機填 ws://<這台電腦的區網 IP>:8080，防火牆要放行這個埠。

在 onTrafficReceived 裡可以掃敏感欄位、跟文件做 diff、轉給分析服務，或寫進訊息佇列。

8.6 自己解析時注意

只處理 Text Frame，依 requestId 分組
Body 照到達順序拼接，不要用 timestamp 重排
同時進行的請求會交錯推送，map 必須依 requestId 分開
連線斷了就清掉還沒結束的紀錄，協議不補傳
規範目前是 1.0.0-Draft，不認識的 event 略過即可，不要直接結束程式

9. 常見做法

抓包做安全檢測

先啟動內網接收端
手機掃碼或填 ws://，測通後啟用
開始抓包，依測試案例操作 App
平台對完整請求掃敏感欄位
透過電子郵件或即時通訊軟體寄送報告，寫明 URL、欄位，以及欄位出現在請求標頭 / Query / Body 的哪個部分

用流量補文件

接收端保存每個 API 最近幾次請求／回應
依路徑 + 方法比對欄位
新增或型別有變的欄位，交給大型語言模型產生註解
整理一份更新清單，寄給 API 負責人

用 Burp 做安全測試

裝擴充套件，Start Server
App 掃碼，啟用 Burp 同步
抓包後在 Site map 看 API，在 History 裡挑請求繼續測

10. 常見問題

測連線失敗
接收端有沒有開、IP 是不是這台電腦的區網位址、埠有沒有放行、是不是同一網段。不要填 127.0.0.1，不要用 http://。

無法開啟 Enable Real-time Streaming
Remote URL 不能是空白。自訂接收端一定要先通過 Test Connection。

首頁顯示離線，接收端其實在跑
電腦休眠、切換 Wi-Fi 或接收端處理程序結束，都會顯示 Offline。回設定頁查看狀態；Desktop / Burp 可以點選 Rescan 重新掃描。

有的請求電腦上看不到
斷線期間的封包不會補傳，確認同步開著再抓。過濾規則、網域黑名單也可能讓部分流量不走 MITM。

三種接收端能一起開嗎
不行。優先順序是 Desktop → Burp Suite → 自訂，只連一個。

為什麼不直接傳一份 HAR
在 VPN 處理程序中把大型 Body 包成一個巨大的 JSON，容易造成記憶體不足。協議會以資料片段傳送；Java SDK 會在接收端重新組裝成 HAR entry。

首頁狀態一直轉圈
App 正在檢查 WebSocket 連線。若一直沒有結果，請檢查網路和接收端處理程序。

11. 相關連結

協議說明（中文）：https://github.com/apicatcher/apicatcher-realtime-sync-protocol/blob/main/README_zh.md
協議倉庫：https://github.com/apicatcher/apicatcher-realtime-sync-protocol
Java 接收端 SDK：https://github.com/apicatcher/apicatcher-sync-sdk-java
Burp Suite 擴充說明：https://apicatcher.net/zh-TW/burpsuite-extension
官網：https://apicatcher.net