ApiCatcher Echtzeit-Sync – Anleitung

HTTP/HTTPS-Traffic vom Handy live an einen Rechner oder ein anderes System schicken.

Protokollbeschreibung: Real-time Sync Protocol

1. Was das ist

ApiCatcher fängt auf iOS und Android per VPN mit und schickt die Daten per WebSocket an einen Empfänger im selben LAN. Der Strom beginnt, sobald die Aufnahme läuft. Sie warten nicht, bis die Session vorbei ist, und exportieren dann eine Datei.

Empfänger	Nutzen	Verbindung
ApiCatcher Desktop	Am Rechner anschauen, vergleichen, wiederholen	QR-Code von Desktop scannen
Burp-Suite-Erweiterung	Sicherheitstests in Burp	QR-Code auf der Erweiterungsseite scannen
Eigener Empfänger	Eigener Dienst oder internes System	`ws://` eintragen und Verbindung testen

Nur einer gleichzeitig. Wer einen einschaltet, schaltet die anderen aus.

2. Wofür sich das eignet

Traffic am Rechner lesen. Großes JSON, lange Header, binäre Bodies: am Handy unbequem. An Desktop angebunden können Sie parsen, vergleichen und wiederholen.

Nach Burp Suite schicken. ApiCatcher for Burp Suite Extension installieren. Anfragen vom Handy landen in Site map oder Proxy History und von dort in Repeater oder Intruder. Die Aufnahme läuft über das VPN am Handy; am Rechner brauchen Sie keinen System-Proxy.

In eine API-Sicherheitsprüfung oder DLP speisen. Tester schalten Aufnahme und Echtzeit-Sync ein. Der Traffic geht in Ihre eigene Plattform, die Ausweise, Telefonnummern, Tokens und Schlüssel sucht, APIs mit möglichem Leak findet und den Bericht an Entwicklung oder Test schickt.

API-Doku aus echtem Traffic nachziehen. Der Empfänger vergleicht mit bekannten Feldern, merkt neue Felder in Request oder Response, kann einen Entwurf von einem Modell schreiben lassen und mailt den Doku-Verantwortlichen.

Automatisierung oder Mocks. Fertige Requests als Fixtures ablegen oder daraus Mocks bauen.

3. Vor dem Start

Um HTTPS zu entschlüsseln, das ApiCatcher-Stammzertifikat installieren und vollständig vertrauen.
Handy und Empfänger ins selbe WLAN. Aus Datenschutzgründen nur LAN-ws://. Kein wss://. Der Traffic bleibt im LAN.
Den Empfängerport in der Firewall von Rechner oder Server freigeben (zum Beispiel 8080).
Empfänger zuerst starten, dann in der App die Verbindung testen.

4. Echtzeit-Sync einschalten

ApiCatcher öffnen, zur Capture-Startseite.
Oben rechts auf +.
Echtzeit-Sync wählen.
Tabs: Desktop / Burp Suite / Eigener Empfänger.

Ist es an, steht auf der Startseite, dass Echtzeit-Sync aktiv ist, plus online oder offline. Tippen auf diese Zeile führt zurück zu den Einstellungen.

5. ApiCatcher Desktop anbinden

ApiCatcher Desktop von apicatcher.net holen und starten.
In Desktop den Echtzeit-Empfänger starten. Es erscheint ein QR-Code.
Am Handy: Echtzeit-Sync → Desktop.
QR-Code scannen und den Code auf Desktop anvisieren.
Nach erfolgreichem Scan sehen Sie Empfängeradresse und Online-Status.
Aktivieren einschalten.
Zurück zur Startseite, VPN-Aufnahme starten, Ziel-App bedienen. Die Requests sollten auf Desktop auftauchen.

Steht dort offline: prüfen, ob Desktop noch läuft und beide im selben Subnetz sind, dann neu scannen.

ApiCatcher Desktop Echtzeit-Empfänger

6. Burp Suite anbinden

Anleitung zur Erweiterung: ApiCatcher for Burp Suite Extension

Die .jar holen (oder selbst bauen), in Burp unter Extensions → Installed → Add als Java-Erweiterung laden.
Oben den Tab ApiCatcher öffnen. Der WebSocket-Server muss laufen; sonst Start Server.
Am Handy Echtzeit-Sync → Burp Suite, QR-Code auf der Erweiterungsseite scannen.
Schalter einschalten, dann aufnehmen.
Standardziel ist Target → Site map. Für volle Request/Response das Ziel auf Proxy → HTTP history stellen. History-Einträge tragen X-ApiCatcher-RequestId.
Von dort nach Repeater oder Intruder.

Wenn die Sync hakt: Extensions → Installed, die Erweiterung wählen, unten Output / Errors prüfen.

Einstellungen der ApiCatcher-for-Burp-Suite-Erweiterung

7. Eigenen Empfänger anbinden

Empfänger zuerst auf dem Rechner oder im Intranet starten (Abschnitt 8). Adresse etwa ws://192.168.1.75:8080.
Am Handy: Echtzeit-Sync → Eigener Empfänger.
Als Remote-Adresse ws://IP:Port eintragen. Der Link Dokumentation daneben ist die Protokollbeschreibung.
Verbindung testen. Bei Erfolg wird die Adresse gespeichert.
Echtzeit-Stream aktivieren einschalten. Ist die Adresse leer oder der Test fehlgeschlagen, bleibt der Schalter aus.
Eine geänderte Adresse schaltet den Schalter aus. Erst neu testen, dann wieder an.
Aufnahme starten. Der Empfänger sollte JSON-Frames bekommen.

Kein http://, kein wss://. Kein 127.0.0.1 – das ist das Handy selbst.

8. Protokoll im eigenen Empfänger umsetzen

Beschreibung: README.md
Repository: apicatcher-realtime-sync-protocol
Java-SDK: apicatcher-sync-sdk-java

8.1 Verbindung

Rolle	Wer
WebSocket-Client	ApiCatcher-App
WebSocket-Server	Ihr Empfänger

LAN-ws:// (aus Datenschutzgründen kein wss://; Traffic bleibt im LAN)
Nach einem Abbruch verbindet die App von selbst neu
Während der Trennung aufgenommene Daten und halb gesendete Brocken werden verworfen. Kein Nachschieben
Viele Requests teilen sich eine Verbindung. Immer nach requestId gruppieren

8.2 Nachrichtenformat

Jede Nachricht ist ein JSON-Textframe:

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

Feld	Bedeutung
`type`	Derzeit `http`
`requestId`	UUID eines Requests; Brocken gehören darüber zusammen
`event`	Siehe die Ereignisse unten
`timestamp`	Millisekunden
`payload`	Daten des Ereignisses

8.3 Ereignisse

Typischer Ablauf:

req_start → req_body* → res_start → res_body* → req_end

req_body / res_body können fehlen oder mehrfach kommen. Ohne Body keine Body-Ereignisse.

req_start — Request geht raus:

{
  "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"}]
  }
}

Danach Cache-Eintrag für diese requestId anlegen und URL, Methode, Request-Header merken.

req_body / res_body — Body-Brocken:

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

payload.data ist Binärdaten in Base64. Die Sende-Reihenfolge bleibt. WebSocket sitzt auf TCP, Ankunftsreihenfolge = Sendereihenfolge. In Ankunftsreihenfolge dekodieren und anhängen. Große Bodies werden zerlegt (etwa 16–32 KB). Nicht auf ein Riesenpaket warten.

res_start — Response-Header da:

{
  "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 — dieser Request ist fertig:

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

error ist null bei Erfolg, sonst etwa "Timeout" oder "Connection Aborted"
timings in Millisekunden: Senden, Warten auf die Antwort, Empfangen
Nach req_end den Datensatz zusammenbauen und den Cache-Eintrag löschen
Bei WebSocket-Abbruch alle Datensätze ohne req_end verwerfen

8.4 Zusammenbau

Bei Verbindung
  └─ map: requestId → Request im Aufbau

Bei JSON-Frame
  ├─ req_start  → anlegen; url / method / headers speichern
  ├─ req_body   → Base64 dekodieren, an den Request-Body hängen
  ├─ res_start  → status / Response-Header speichern
  ├─ res_body   → Base64 dekodieren, an den Response-Body hängen
  └─ req_end    → error / timings speichern, an die Fachlogik, aus der map löschen

Bei Abbruch
  └─ map leeren; Halbfertiges nicht als fertigen Request behandeln

Scannen, speichern, Doku aktualisieren erst nach req_end. Während der Brocken ist der Body unvollständig.

8.5 Java-SDK

apicatcher-sync-sdk-java betreibt den WebSocket-Server und setzt die Brocken zusammen. Ist ein Request komplett, kommt ein HAR-1.2-Entry als JSON zurück (keine ganze HAR-Datei).

Voraussetzung: JDK 11+, Maven 3.x+.

Listener:

import com.apicatcher.sync.TrafficListener;

public class StandardConsoleListener implements TrafficListener {
    @Override
    public void onTrafficReceived(String harJson) {
        System.out.println("Received a complete request:");
        System.out.println(harJson);
    }
}

Start:

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("Listening on port " + port);
    }
}

Am Handy: ws://<LAN-IP dieses Rechners>:8080. Port in der Firewall freigeben.

In onTrafficReceived können Sie nach Geheimnissen suchen, gegen die Doku diffen, an einen Analysedienst schicken oder in eine Queue schreiben.

8.6 Wenn Sie selbst parsen

Nur Textframes, gruppieren nach requestId
Body in Ankunftsreihenfolge anhängen, nicht nach timestamp umsortieren
Parallele Requests kommen vermischt; nach requestId trennen
Bei Abbruch unfertige Datensätze verwerfen. Das Protokoll sendet nicht nach
Die Spec ist 1.0.0-Draft. Unbekannte event-Werte ignorieren, den Prozess nicht beenden

9. Typische Abläufe

Aufnehmen für einen Sicherheitsscan

Internen Empfänger starten
QR scannen oder ws:// eintragen, testen, dann einschalten
Aufnahme starten und die App durchklicken
Die Plattform sucht in fertigen Requests nach sensiblen Feldern
Bericht per Mail / IM: URL, Feld, und ob Header / Query / Body

Doku aus Traffic nachziehen

Empfänger hält die letzten Request/Response-Beispiele pro API
Felder nach Pfad + Methode vergleichen
Neue oder typgeänderte Felder an ein Modell für Kommentare
Aktualisierungsliste an den API-Verantwortlichen

Sicherheitstests in Burp

Erweiterung installieren, Start Server
In der App QR scannen, Burp-Sync einschalten
Nach der Aufnahme APIs in Site map ansehen, Requests in History wählen

10. Häufige Fragen

Verbindungstest fehlgeschlagen
Läuft der Empfänger? Ist die IP die LAN-Adresse dieses Rechners? Port offen? Gleiches Subnetz? Kein 127.0.0.1. Kein http://.

Der Schalter bleibt nicht an
Die Adresse darf nicht leer sein. Ein eigener Empfänger muss den Test zuerst bestehen.

Startseite zeigt offline, Empfänger läuft aber
Ruhezustand, WLAN-Wechsel, beendeter Prozess setzen den Status auf offline. Status in den Einstellungen prüfen. Bei Desktop / Burp den QR neu scannen.

Manche Requests kommen am Rechner nicht an
Während einer Trennung Aufgenommenes wird nicht nachgeschickt. Sync einschalten, bevor Sie aufnehmen. Filter und Domain-Blacklists können MITM umgehen.

Kann ich alle drei Empfänger gleichzeitig anmachen?
Nein. Reihenfolge: Desktop → Burp Suite → eigener Empfänger. Nur eine Verbindung.

Warum nicht eine HAR-Datei schicken?
Ein großer Body als ein JSON im VPN-Prozess sprengt leicht den Speicher. Das Protokoll schickt Brocken. Das Java-SDK setzt am Empfänger einen HAR-Entry zusammen.

Der Status auf der Startseite dreht sich dauernd
Die App prüft den WebSocket. Wird das nicht fertig, Netzwerk und Empfängerprozess prüfen.

11. Links

Protokollbeschreibung: https://github.com/apicatcher/apicatcher-realtime-sync-protocol/blob/main/README.md
Protokoll-Repository: https://github.com/apicatcher/apicatcher-realtime-sync-protocol
Java-Empfänger-SDK: https://github.com/apicatcher/apicatcher-sync-sdk-java
Burp-Suite-Erweiterung: https://apicatcher.net/de/burpsuite-extension
Website: https://apicatcher.net