Guía de sincronización en tiempo real de ApiCatcher

Envía en tiempo real el tráfico HTTP/HTTPS capturado en el teléfono a un ordenador o a otro sistema.

Especificación del protocolo: Real-time Sync Protocol

1. Qué hace

ApiCatcher captura tráfico mediante una VPN en iOS y Android y lo transmite por WebSocket a un receptor de la misma red local. La transmisión comienza en cuanto se inicia la captura, sin esperar a que termine la sesión para exportar un archivo.

Solo puede estar activo uno a la vez. Al activar uno, los otros dos se desactivan.

2. Para qué sirve

Ver el tráfico en un ordenador. Los documentos JSON de gran tamaño, las cabeceras largas y los cuerpos binarios son difíciles de inspeccionar en el teléfono. Con Desktop puedes analizarlos, compararlos y reproducir las solicitudes.

Enviar el tráfico a Burp Suite. Instala ApiCatcher for Burp Suite Extension. Las solicitudes capturadas en el teléfono aparecen en Site map o Proxy History y, desde allí, pueden enviarse a Repeater o Intruder. El tráfico se captura mediante la VPN del teléfono; no es necesario configurar un proxy del sistema en el ordenador.

Integrar un escáner de seguridad de API o una solución DLP. Durante las pruebas, activa la captura y la sincronización. El tráfico llega a tu plataforma, que puede buscar números de documento de identidad, números de teléfono, tokens y claves, identificar API que podrían filtrar datos y enviar un informe a los equipos de desarrollo o control de calidad.

Actualizar la documentación de API con tráfico real. El receptor compara el tráfico con los campos registrados anteriormente, detecta posibles campos nuevos en las solicitudes o respuestas, puede usar un modelo de IA para generar descripciones y comentarios, y avisa al responsable de la documentación.

Automatización o mocks. Guarda solicitudes completas como datos de prueba o úsalas para generar mocks.

3. Antes de empezar

1. Para descifrar HTTPS, instala el certificado raíz de ApiCatcher y confía en él por completo.
2. Conecta el teléfono y el receptor a la misma red Wi-Fi. Por motivos de seguridad de los datos, actualmente solo se admite ws:// en la red local; wss:// no es compatible. El tráfico no sale de la red local.
3. Abre el puerto del receptor en el cortafuegos del ordenador o del servidor (por ejemplo 8080).
4. Arranca primero el receptor y luego prueba la conexión en la app.

4. Abrir la sincronización en tiempo real

1. Abre ApiCatcher y ve a la pantalla de captura.
2. Pulsa + arriba a la derecha.
3. Selecciona Real-time Sync.
4. En la parte superior aparecen las pestañas Desktop, Burp Suite y Custom Receiver.

Cuando está activada, la pantalla principal muestra Real-time Sync Active y el estado Online u Offline del receptor. Pulsa ese aviso para volver a la pantalla de configuración.

5. Conectar con ApiCatcher Desktop

1. Descarga y abre ApiCatcher Desktop desde apicatcher.net.
2. En Desktop, inicia el receptor de sincronización en tiempo real. Aparecerá un código QR.
3. En el teléfono, abre Real-time Sync → Desktop.
4. Pulsa Scan QR Code y escanea el código que muestra Desktop.
5. Si el escaneo se completa correctamente, verás la dirección del receptor y el estado Online.
6. Activa Enable.
7. Vuelve a la pantalla principal, inicia la captura mediante VPN y utiliza la aplicación objetivo. Las solicitudes deberían aparecer progresivamente en Desktop.

Si aparece Offline, comprueba que Desktop sigue en ejecución y que el teléfono y el ordenador están en la misma subred. Después, pulsa Rescan.

6. Conectar con Burp Suite

Guía de la extensión: ApiCatcher for Burp Suite Extension

1. Consigue el .jar (o compílalo) y cárgalo en Burp: Extensions → Installed → Add, como extensión Java.
2. Abre la pestaña ApiCatcher de la barra superior y comprueba que el servidor WebSocket está en ejecución; si no lo está, pulsa Start Server.
3. En el teléfono, abre Real-time Sync → Burp Suite y escanea el código QR de la extensión.
4. Activa Enable y, a continuación, inicia la captura.
5. De forma predeterminada, el tráfico se envía a Target → Site map. Para ver la solicitud y la respuesta completas, cambia el destino a Proxy → HTTP history. Las entradas de History incluyen la cabecera X-ApiCatcher-RequestId.
6. Desde allí puedes enviar las solicitudes a Repeater o Intruder.

Si falla la sincronización, abre Extensions → Installed, selecciona la extensión y consulta las secciones Output y Errors de la parte inferior.

7. Conectar un receptor personalizado

1. Inicia el receptor en el ordenador o en la red interna (consulta el apartado 8). La dirección tendrá un formato similar a ws://192.168.1.75:8080.
2. En el teléfono, abre Real-time Sync → Custom Receiver.
3. En Remote URL, introduce ws://IP:puerto. El enlace Documentation situado a la derecha abre la especificación del protocolo.
4. Pulsa Test Connection. Si la prueba se completa correctamente, la dirección se guardará.
5. Activa Enable Real-time Streaming. El interruptor no puede activarse si la dirección está vacía o si falla la prueba de conexión.
6. Si modificas la dirección, el interruptor se desactivará. Prueba de nuevo la conexión antes de volver a activarlo.
7. Inicia la captura. El receptor debería comenzar a recibir tramas de texto JSON.

No uses http:// ni wss://. Tampoco 127.0.0.1: eso es el propio teléfono.

8. Implementar el protocolo en un receptor personalizado

Especificación: README.md
Repositorio: apicatcher-realtime-sync-protocol
SDK Java: apicatcher-sync-sdk-java

8.1 Conexión

• Utiliza ws:// en la red local. Por motivos de seguridad de los datos, wss:// no es compatible y el tráfico permanece en la red local
• Si se interrumpe la conexión, la aplicación intenta restablecerla automáticamente
• Los datos capturados durante la interrupción y los fragmentos incompletos se descartan; no se retransmiten
• Varias solicitudes pueden compartir una conexión; agrúpalas por requestId

8.2 Formato de mensaje

Cada mensaje se envía como una trama de texto de WebSocket que contiene un objeto JSON:

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

8.3 Eventos

Secuencia habitual:

req_start → req_body* → res_start → res_body* → req_end

req_body y res_body pueden no aparecer o repetirse varias veces. Si no hay cuerpo, no se envía el evento correspondiente.

req_start — inicio de la solicitud:

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

Al recibirlo, crea una entrada en la caché para ese requestId y guarda la URL, el método y las cabeceras de la solicitud.

req_body / res_body — fragmentos del cuerpo:

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

payload.data contiene datos binarios codificados en Base64. Los fragmentos se envían en orden. Como WebSocket funciona sobre TCP, el orden de llegada coincide con el de envío. Decodifica y concatena los fragmentos en ese mismo orden. Los cuerpos grandes se dividen en fragmentos de unos 16–32 KB; procésalos a medida que llegan, sin esperar a recibir el cuerpo completo.

res_start — cabeceras de respuesta:

{
  "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 — fin de la solicitud:

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

• error es null si la solicitud termina correctamente; de lo contrario, contiene un texto como "Timeout" o "Connection Aborted"
• timings expresa en milisegundos el tiempo de envío, espera de la respuesta y recepción
• Después de req_end, ensambla el registro completo y elimina la entrada de la caché
• Si se interrumpe la conexión WebSocket, descarta todos los registros que aún no hayan recibido req_end

8.4 Ensamblado

Al conectar
  └─ mapa: requestId → solicitud en curso

Al recibir una trama JSON
  ├─ req_start  → crear; guardar url / method / headers
  ├─ req_body   → decodificar Base64 y añadir al cuerpo de la solicitud
  ├─ res_start  → guardar status / cabeceras de respuesta
  ├─ res_body   → decodificar Base64 y añadir al cuerpo de respuesta
  └─ req_end    → guardar error / timings, entregar a la aplicación, borrar del mapa

Al interrumpirse la conexión
  └─ vaciar el mapa; no tratar un registro incompleto como una solicitud completa

Ejecuta análisis, guarda datos o actualiza la documentación solo después de recibir req_end. El cuerpo permanece incompleto mientras siguen llegando fragmentos.

8.5 SDK Java

apicatcher-sync-sdk-java inicia el servidor WebSocket y ensambla los fragmentos. Cuando se completa una transacción HTTP, el SDK invoca el callback con el JSON de una entrada (entry) HAR 1.2, no con un archivo HAR completo.

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

Implementa el listener:

import com.apicatcher.sync.TrafficListener;

public class StandardConsoleListener implements TrafficListener {
    @Override
    public void onTrafficReceived(String harJson) {
        System.out.println("Solicitud completa recibida:");
        System.out.println(harJson);
    }
}

Inicia el receptor:

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("Escuchando en el puerto " + port);
    }
}

En el teléfono, introduce ws://<IP de la red local de este ordenador>:8080 y abre el puerto correspondiente en el cortafuegos.

En onTrafficReceived puedes detectar datos sensibles, comparar el tráfico con la documentación, enviarlo a un servicio de análisis o publicarlo en una cola de mensajes.

8.6 Si implementas tu propio analizador

• Procesa únicamente tramas de texto y agrúpalas por requestId
• Concatena el cuerpo en orden de llegada; no lo reordenes por timestamp
• Los fragmentos de solicitudes simultáneas pueden intercalarse; mantenlos separados por requestId
• Si se interrumpe la conexión, descarta los registros incompletos; el protocolo no los retransmite
• La especificación actual es 1.0.0-Draft. Ignora los valores de event desconocidos en lugar de finalizar el proceso

9. Flujos habituales

Capturar tráfico para un análisis de seguridad

1. Inicia el receptor interno
2. Escanea el código QR o introduce la dirección ws://, prueba la conexión y activa la sincronización
3. Inicia la captura y ejecuta los casos de prueba en la aplicación
4. La plataforma analiza las transacciones HTTP completas —solicitud y respuesta— para detectar datos sensibles
5. Envía el informe por correo electrónico o mensajería instantánea e indica la URL, el campo y si aparece en las cabeceras, la cadena de consulta o el cuerpo

Actualizar la documentación con el tráfico

1. El receptor guarda las últimas muestras de solicitudes y respuestas de cada API
2. Compara los campos por ruta y método
3. Envía los campos nuevos o cuyo tipo haya cambiado a un modelo para generar sus descripciones
4. Envía la lista de cambios al responsable de la API

Pruebas de seguridad en Burp

1. Instala la extensión y pulsa Start Server
2. Escanea el código QR en la aplicación y activa Enable en la pestaña Burp Suite
3. Después de la captura, consulta las API en Site map y selecciona las solicitudes en History para continuar las pruebas

10. Preguntas frecuentes

Falla la prueba de conexión
Comprueba que el receptor está en ejecución, que la dirección IP pertenece a la red local del ordenador, que el puerto está abierto y que ambos dispositivos están en la misma subred. No uses 127.0.0.1 ni http://.

El interruptor no se queda encendido
La dirección no puede estar vacía. Un receptor personalizado debe superar primero la prueba de conexión con Test Connection.

La pantalla principal muestra Offline aunque el receptor está en ejecución
La suspensión del ordenador, un cambio de red Wi-Fi o el cierre del proceso pueden cambiar el estado a Offline. Consulta el estado en la pantalla de configuración. Para Desktop o Burp Suite, pulsa Rescan y escanea de nuevo el código QR.

Algunas peticiones no aparecen en el ordenador
Los datos capturados durante una interrupción no se retransmiten. Activa la sincronización antes de iniciar la captura. Las reglas de filtrado o las listas de exclusión de dominios también pueden hacer que parte del tráfico no pase por la interceptación MITM.

¿Puedo activar los tres receptores a la vez?
No. El orden de prioridad es Desktop → Burp Suite → receptor personalizado. Solo se establece una conexión.

¿Por qué no mandar un archivo HAR?
Incluir un cuerpo de gran tamaño en un único objeto JSON puede agotar la memoria del proceso VPN. El protocolo transmite el contenido en fragmentos y el SDK Java los ensambla en una entrada HAR en el receptor.

El indicador de estado de la pantalla principal no deja de girar
La aplicación está comprobando la conexión WebSocket. Si el proceso no termina, revisa la red y el proceso del receptor.

11. Enlaces

• Especificación del protocolo: https://github.com/apicatcher/apicatcher-realtime-sync-protocol/blob/main/README.md
• Repositorio del protocolo: https://github.com/apicatcher/apicatcher-realtime-sync-protocol
• SDK Java del receptor: https://github.com/apicatcher/apicatcher-sync-sdk-java
• Extensión de Burp Suite: https://apicatcher.net/es/burpsuite-extension
• Sitio: https://apicatcher.net