Guide de la synchronisation en temps réel d’ApiCatcher

Transmettez en temps réel le trafic HTTP/HTTPS capturé sur votre téléphone vers un ordinateur ou un autre système.

Spécification du protocole : Real-time Sync Protocol

1. Fonctionnement

Lorsqu’ApiCatcher capture du trafic via son VPN sur iOS ou Android, l’app le transmet en continu, par WebSocket, à un récepteur situé sur le même réseau local. La transmission commence dès le début de la capture : il n’est pas nécessaire d’attendre la fin de la session pour exporter un fichier.

Un seul récepteur peut être actif à la fois. L’activation de l’un désactive les deux autres.

2. Cas d’usage

Inspecter le trafic sur un ordinateur. Les documents JSON volumineux, les longs en-têtes et les corps binaires sont difficiles à examiner sur un téléphone. Avec Desktop, vous pouvez les analyser, les comparer et rejouer les échanges.

Transmettre le trafic à Burp Suite. Installez ApiCatcher for Burp Suite Extension. Les requêtes capturées sur le téléphone sont envoyées vers Site map ou Proxy → HTTP history, puis peuvent être transférées vers Repeater ou Intruder. Le VPN du téléphone se charge de la capture ; aucun proxy système n’est à configurer sur l’ordinateur.

Alimenter un outil de sécurité des API ou de DLP. Pendant les tests d’une app, activez la capture et la synchronisation en temps réel. Votre plateforme peut alors rechercher des données sensibles — numéros de pièce d’identité, numéros de téléphone, jetons ou clés —, repérer les API susceptibles de les exposer et transmettre un rapport aux équipes de développement ou de test.

Tenir la documentation des API à jour à partir du trafic réel. Le récepteur compare les champs observés à l’historique et détecte les champs potentiellement nouveaux dans les requêtes ou les réponses. Un grand modèle de langage peut ensuite proposer leur fonction et leur description, avant l’envoi d’une notification par e-mail au responsable de la documentation.

Alimenter des tests automatisés ou des mocks. Enregistrez les requêtes complètes comme jeux de données de test, ou utilisez-les pour générer des mocks.

3. Avant de commencer

1. Pour déchiffrer le trafic HTTPS, installez le certificat racine ApiCatcher et accordez-lui une confiance totale.
2. Connectez le téléphone et le récepteur au même réseau Wi-Fi. La synchronisation n’est disponible que sur le réseau local via ws:// ; wss:// n’est pas pris en charge. Les données transmises par la synchronisation restent ainsi sur le réseau local.
3. Ouvrez le port du récepteur dans le pare-feu de la machine (par exemple 8080).
4. Démarrez le récepteur, puis testez la connexion dans l’app.

4. Activer la synchronisation en temps réel

1. Ouvrez ApiCatcher et accédez à l’écran d’accueil de la capture.
2. Appuyez sur « + » en haut à droite.
3. Sélectionnez Real-time Sync.
4. Trois onglets sont disponibles : Desktop, Burp Suite et Custom Receiver.

Une fois la fonction activée, l’écran d’accueil affiche Real-time Sync Active ainsi que l’état du récepteur : Online ou Offline. Appuyez sur cette indication pour revenir aux réglages.

5. Connecter ApiCatcher Desktop

1. Téléchargez et lancez ApiCatcher Desktop depuis apicatcher.net.
2. Démarrez le récepteur de synchronisation en temps réel dans Desktop : un QR code s’affiche.
3. Sur le téléphone, ouvrez Real-time Sync → Desktop.
4. Appuyez sur Scan QR Code, puis scannez le QR code affiché dans Desktop.
5. Une fois le scan terminé, l’adresse du récepteur et l’état Online s’affichent.
6. Activez Enable.
7. Revenez à l’écran d’accueil, lancez la capture VPN et utilisez l’app cible. Les requêtes doivent apparaître progressivement dans Desktop.

Si l’état affiché est Offline, vérifiez que Desktop est toujours en cours d’exécution et que les deux appareils se trouvent sur le même sous-réseau, puis appuyez sur Rescan.

6. Connecter Burp Suite

Guide de l’extension : ApiCatcher for Burp Suite Extension

1. Téléchargez le fichier .jar de l’extension, ou compilez-le vous-même, puis chargez-le dans Burp via Extensions → Installed → Add en sélectionnant le type Java.
2. Ouvrez l’onglet ApiCatcher en haut de la fenêtre et vérifiez que le serveur WebSocket est démarré. Dans le cas contraire, cliquez sur Start Server.
3. Sur le téléphone, ouvrez Real-time Sync → Burp Suite, puis scannez le QR code affiché dans l’extension.
4. Activez Enable, puis lancez la capture.
5. Par défaut, le trafic est envoyé vers Target → Site map. Pour afficher l’intégralité des requêtes et des réponses, sélectionnez plutôt Proxy → HTTP history comme destination. Les requêtes ajoutées à l’historique comportent l’en-tête X-ApiCatcher-RequestId.
6. Vous pouvez ensuite les envoyer vers Repeater ou Intruder.

En cas de problème de synchronisation, ouvrez Extensions → Installed, sélectionnez l’extension, puis consultez les panneaux Output et Errors en bas de la fenêtre.

7. Connecter un récepteur personnalisé

1. Démarrez le récepteur sur un ordinateur ou un serveur du réseau interne, comme indiqué à la section 8. Son adresse doit être du type ws://192.168.1.75:8080.
2. Sur le téléphone, ouvrez Real-time Sync → Custom Receiver.
3. Dans Remote URL, saisissez une adresse au format ws://IP:port. Le lien Documentation situé à droite ouvre la spécification du protocole.
4. Appuyez sur Test Connection. Si le test réussit, l’adresse est enregistrée.
5. Activez Enable Real-time Streaming. Le commutateur ne peut pas être activé si l’adresse est vide ou si le test de connexion échoue.
6. Toute modification de l’adresse désactive le commutateur. Testez de nouveau la connexion avant de le réactiver.
7. Lancez la capture. Le récepteur doit commencer à recevoir des trames JSON.

N’utilisez ni http:// ni wss://. N’utilisez pas non plus 127.0.0.1, car cette adresse désigne le téléphone lui-même.

8. Implémenter le protocole côté récepteur

Spécification : README.md
Dépôt : apicatcher-realtime-sync-protocol
SDK Java : apicatcher-sync-sdk-java

8.1 Connexion

• Utilisez ws:// sur le réseau local. wss:// n’est pas pris en charge et les données synchronisées restent sur le réseau local
• Après une interruption, l’app tente automatiquement de se reconnecter
• Le trafic capturé pendant l’interruption et les fragments partiellement transmis sont abandonnés ; ils ne sont pas renvoyés
• Les fragments de plusieurs requêtes peuvent s’entrelacer sur une même connexion ; regroupez-les par requestId

8.2 Format des messages

Chaque message est une trame texte JSON :

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

8.3 Événements

Enchaînement typique :

req_start → req_body* → res_start → res_body* → req_end

Les événements req_body et res_body peuvent être absents ou se produire plusieurs fois. Lorsqu’il n’y a pas de corps, l’événement correspondant n’est pas envoyé.

req_start — envoi de la requête :

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

À réception, créez une entrée de cache pour ce requestId, puis enregistrez l’URL, la méthode et les en-têtes de la requête.

req_body / res_body — fragments du corps :

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

payload.data est une chaîne Base64 contenant les données binaires encodées. WebSocket reposant sur TCP, les fragments sont reçus dans leur ordre d’envoi. Décodez-les et concaténez-les dans cet ordre. Les corps volumineux sont découpés en fragments d’environ 16 à 32 Ko ; traitez chaque fragment sans attendre la reconstitution du corps complet.

res_start — en-têtes de réponse :

{
  "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 — cette requête est terminée :

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

• error vaut null si tout va bien, sinon une chaîne du type "Timeout" ou "Connection Aborted"
• timings en millisecondes : envoi, attente de la réponse, réception
• À la réception de req_end, assemblez l’enregistrement, puis supprimez du cache uniquement l’entrée associée à ce requestId
• Si la connexion WebSocket est interrompue, abandonnez tous les enregistrements qui n’ont pas encore reçu req_end

8.4 Assemblage

À la connexion
  └─ map : requestId → requête en cours

À chaque trame JSON
  ├─ req_start  → créer ; stocker url / method / headers
  ├─ req_body   → décoder le Base64, ajouter au corps de requête
  ├─ res_start  → stocker status / en-têtes de réponse
  ├─ res_body   → décoder le Base64, ajouter au corps de réponse
  └─ req_end    → stocker error / timings, transmettre à la logique applicative, retirer de la map

À la coupure
  └─ vider la map ; ne pas traiter une requête incomplète comme terminée

N’effectuez l’analyse, le stockage ou la mise à jour de la documentation qu’après la réception de req_end. Le corps reste incomplet tant que tous ses fragments n’ont pas été reçus.

8.5 SDK Java

apicatcher-sync-sdk-java gère le serveur WebSocket et assemble les fragments. Lorsqu’une requête est complète, le SDK appelle onTrafficReceived en lui transmettant la représentation JSON d’une entrée HAR 1.2, et non un fichier HAR complet.

Prérequis : JDK 11+, Maven 3.x+.

Écouteur :

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);
    }
}

Démarrage :

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);
    }
}

Sur le téléphone, saisissez ws://<IP locale de cette machine>:8080. Ouvrez ce port dans le pare-feu.

Dans onTrafficReceived, vous pouvez rechercher des champs sensibles, comparer les données à la documentation, les transmettre à un service d’analyse ou les publier dans une file de messages.

8.6 Si vous analysez vous-même le protocole

• Traitez uniquement les trames texte ; regroupez-les par requestId
• Concaténez le corps dans l’ordre d’arrivée ; ne réordonnez pas avec timestamp
• Les requêtes parallèles s’entrelacent ; isolez-les par requestId
• En cas d’interruption, abandonnez les enregistrements incomplets ; le protocole ne les renvoie pas
• La spécification est actuellement en version 1.0.0-Draft. Ignorez les valeurs event inconnues au lieu d’arrêter le processus

9. Scénarios d’utilisation courants

Capturer pour un scan de sécurité

1. Démarrez le récepteur interne
2. Scannez un QR code ou saisissez une adresse ws://, testez la connexion, puis activez la synchronisation
3. Lancez la capture et exécutez le scénario de test dans l’app
4. Analysez les requêtes complètes sur la plateforme afin de détecter les champs sensibles
5. Envoyez un rapport par e-mail ou messagerie instantanée en indiquant l’URL, le champ concerné et son emplacement : en-têtes, paramètres de requête ou corps

Mettre la documentation à jour à partir du trafic

1. Conservez dans le récepteur les derniers exemples de requêtes et de réponses de chaque endpoint
2. Comparez les champs par chemin et par méthode HTTP
3. Pour les champs nouveaux ou dont le type a changé, demandez à un grand modèle de langage de proposer une description
4. Envoyez la liste des modifications au responsable de l’API

Effectuer des tests de sécurité dans Burp

1. Installez l’extension, puis cliquez sur Start Server
2. Dans l’app, ouvrez Real-time Sync → Burp Suite, scannez le QR code et activez Enable
3. Après la capture, examinez les API dans Site map, puis sélectionnez dans HTTP history les requêtes à tester dans les autres outils de Burp

10. Questions fréquentes

Le test de connexion échoue
Vérifiez que le récepteur est démarré, que l’adresse IP correspond à l’adresse locale de la machine, que le port est ouvert et que les deux appareils se trouvent sur le même sous-réseau. N’utilisez ni 127.0.0.1 ni une adresse commençant par http://.

Le commutateur ne reste pas allumé
Le champ Remote URL ne peut pas être vide. Pour un récepteur personnalisé, vous devez d’abord réussir le test avec Test Connection.

L’écran d’accueil affiche Offline alors que le récepteur est démarré
La mise en veille de l’ordinateur, un changement de réseau Wi-Fi ou l’arrêt du processus peuvent faire passer le récepteur à l’état Offline. Consultez son état dans les réglages. Pour Desktop ou Burp Suite, utilisez Rescan.

Certaines requêtes n’apparaissent pas sur l’ordinateur
Le trafic capturé pendant une interruption n’est pas renvoyé. Activez la synchronisation avant de lancer la capture. Les règles de filtrage ou les listes noires de domaines peuvent également exclure une partie du trafic de l’interception MITM.

Puis-je activer les trois récepteurs ?
Non. L’ordre de priorité est Desktop → Burp Suite → récepteur personnalisé, et une seule connexion peut être active.

Pourquoi ne pas envoyer un fichier HAR ?
L’intégration d’un corps volumineux dans un unique document JSON peut saturer la mémoire du processus VPN. Le protocole transmet donc les corps par fragments. Le SDK Java reconstitue ensuite une entrée HAR côté récepteur.

L’indicateur d’état reste en cours de chargement sur l’écran d’accueil
L’app teste la connexion WebSocket. Si le test n’aboutit pas, vérifiez le réseau et le processus du récepteur.

11. Liens

• Spécification du protocole : https://github.com/apicatcher/apicatcher-realtime-sync-protocol/blob/main/README.md
• Dépôt du protocole : https://github.com/apicatcher/apicatcher-realtime-sync-protocol
• SDK Java côté récepteur : https://github.com/apicatcher/apicatcher-sync-sdk-java
• Extension Burp Suite : https://apicatcher.net/fr/burpsuite-extension
• Site : https://apicatcher.net