Proxyman vs mitmproxy: decodificar mensajes WebSocket Protobuf

Has capturado una conexión WebSocket, pero sus mensajes parecen datos binarios aleatorios. Sabes que la app está recibiendo información útil, pero no puedes leer los valores en tu herramienta de depuración.

El mensaje puede usar Protocol Buffers, conocido habitualmente como Protobuf. Protobuf es rápido y compacto, pero no está diseñado para ser legible como JSON.

Tanto mitmproxy como Proxyman pueden ayudarte a decodificar mensajes WebSocket con Protobuf. mitmproxy ofrece una vista de contenido Protobuf y acepta un archivo de definición .proto. Proxyman ofrece una lista visual de mensajes, un Raw Mode rápido y la decodificación basada en descriptores dentro de la app para macOS.

¿Qué es WebSocket?

HTTP normal suele seguir un patrón sencillo:

1. La app envía una solicitud.
2. El servidor envía una respuesta.
3. El intercambio termina.

Un WebSocket mantiene abierta una única conexión. La app y el servidor pueden enviarse mensajes en cualquier momento.

Los WebSockets son útiles para:

• Mensajes de chat
• Precios en tiempo real
• Eventos de juegos
• Actualizaciones de entregas o viajes
• Notificaciones
• Edición colaborativa
• Paneles en tiempo real

Al depurar un WebSocket, normalmente quieres ver la conexión y leer cada mensaje enviado y recibido, en orden.

¿Qué es Protobuf?

Protobuf es un formato de datos binario creado por Google. Almacena datos estructurados en menos bytes que un formato de texto normal, como JSON.

Un mensaje JSON puede verse así:

{
  "userId": 123,
  "name": "Taylor",
  "online": true
}

Los mismos datos codificados con Protobuf son binarios. Si los abres como texto, es posible que veas cuadros, símbolos extraños o una larga lista de bytes.

Esto no significa que el mensaje esté roto. Tu herramienta de depuración necesita decodificarlo con las reglas de Protobuf.

¿Por qué Protobuf es difícil de leer?

Un mensaje Protobuf almacena números de campo y valores. Los nombres de campo legibles suelen estar en un esquema aparte.

Por ejemplo, el esquema puede decir:

message UserStatus {
  int64 user_id = 1;
  string name = 2;
  bool online = 3;
}

El mensaje binario puede contener los campos 1, 2 y 3, pero no necesita repetir las palabras user_id, name y online cada vez.

Ese diseño hace que el mensaje sea pequeño. También crea un problema al depurar: sin el esquema correcto, una herramienta puede mostrar los números de campo y los posibles tipos de valor, pero no puede saber con fiabilidad los nombres originales de los campos.

La solución actual con mitmproxy

mitmproxy admite tráfico WebSocket. Además, incluye una vista de contenido Protobuf que puede dar formato a datos binarios.

Para los campos con nombre, mitmproxy ofrece la opción protobuf_definitions. Debes asignarle la ruta de un archivo .proto:

mitmweb --set protobuf_definitions=/path/to/messages.proto

Una vez capturado el tráfico, localizas el flujo WebSocket, abres un mensaje y eliges la vista de contenido Protobuf si no se selecciona automáticamente.

Es una función integrada real. No necesitas escribir un addon personalizado en Python para la visualización normal de Protobuf.

mitmproxy encaja bien cuando:

• Ya usas mitmproxy para tu tráfico
• Te sientes cómodo con las opciones de terminal
• Guardas archivos .proto en tu proyecto de desarrollo
• Quieres automatizar o programar más partes del flujo de trabajo
• Necesitas un proxy gratuito y de código abierto

¿Qué puede resultar difícil en el flujo de trabajo de mitmproxy?

El principal desafío para un principiante es conectar todas las piezas.

1. El mensaje WebSocket es independiente de su esquema

Capturar los bytes es solo el primer paso. También necesitas la definición .proto correcta si quieres ver los nombres de campo reales.

Los proyectos grandes pueden tener muchos archivos .proto, importaciones, paquetes y tipos de mensaje. Además, un esquema puede cambiar mientras una versión antigua de la app sigue enviando el formato anterior.

2. La configuración usa opciones y vistas de contenido

Debes conocer el nombre de la opción, indicar la ruta correcta del archivo, localizar el mensaje WebSocket y seleccionar la vista de contenido adecuada.

Es eficiente una vez que lo aprendes. Un desarrollador que empieza en la depuración de red puede preferir un menú visible que parta del mensaje que ya está viendo.

3. Encontrar un mensaje puede llevar tiempo

Un WebSocket con mucha actividad puede enviar cientos o miles de mensajes. Los datos útiles se mezclan con latidos, actualizaciones de estado y otros tipos de evento.

Una línea de tiempo clara de mensajes enviados y recibidos te ayuda a relacionar una acción de la app con un mensaje binario concreto.

4. Es posible que falte el esquema

A veces se te permite depurar la app, pero no tienes cerca sus archivos fuente .proto. En ese caso, sigues necesitando una forma segura de inspeccionar los números de campo y los valores básicos.

La decodificación en bruto no puede recuperar los nombres originales, pero sí puede indicarte si el payload probablemente es Protobuf y ayudarte a localizar el valor que necesitas.

La solución visual con Proxyman

Proxyman para macOS 6.5.0 o posterior puede decodificar los payloads Protobuf de los mensajes WebSocket.

Hay dos modos útiles:

• Raw Mode funciona sin archivo descriptor. Muestra los números de campo y los valores inferidos.
• Message Type usa un archivo descriptor .desc importado. Puede mostrar los nombres y tipos de campo definidos en tu esquema.

Así puedes empezar con el mensaje capturado y, después, elegir cuánta información de esquema tienes.

Paso 1: Captura la conexión WebSocket

Descarga y configura Proxyman para macOS. Instala y confía en el certificado cuando necesites descifrar una conexión segura wss://.

Para un WebSocket abierto por Google Chrome, inicia Proxyman y luego abre el sitio web. Proxyman puede capturar automáticamente el tráfico WebSocket normal de producción desde Chrome.

Realiza la acción que envía el mensaje. Por ejemplo, envía un mensaje de chat o cambia un ajuste en tiempo real. Mantener la prueba pequeña facilita encontrar el frame correspondiente.

Selecciona el flujo WebSocket. En la pestaña WebSocket puedes ver los mensajes enviados por el cliente y los recibidos del servidor.

Paso 2: Prueba Raw Mode sin un esquema

Raw Mode es la forma más rápida de revisar un mensaje cuando no tienes un descriptor Protobuf.

1. Selecciona el mensaje WebSocket.
2. Haz clic derecho en el mensaje.
3. Elige Protobuf → Decode.
4. Selecciona Raw Mode.

Proxyman lee el payload binario y muestra los campos que puede inferir.

Raw Mode puede ayudarte a ver:

• Números de campo
• Números
• Valores de texto
• Valores de tipo booleano
• Valores binarios anidados

Raw Mode no puede saber que un campo se llamaba originalmente user_id o message_text. Para esos nombres, necesitas el esquema.

Paso 3: Prepara un descriptor para obtener los nombres de campo completos

Proxyman usa un Protobuf File Descriptor con extensión .desc. Un descriptor contiene la información del esquema compilado que necesita el decodificador.

La opción más sencilla es pedir al equipo de backend o de la app el archivo descriptor actual.

Si tienes los archivos fuente .proto, usa protoc para crear un descriptor. Este ejemplo incluye las definiciones importadas:

protoc \
  --descriptor_set_out=output.desc \
  --include_imports \
  -I=/path/to/proto/files \
  /path/to/proto/files/*.proto

Si protoc no está instalado en macOS, instala primero las herramientas de línea de comandos de Protobuf:

brew install protobuf

Guarda el descriptor en una carpeta de desarrollo segura. Un esquema puede revelar nombres de mensajes internos y estructuras de datos, así que no lo publiques a menos que tu equipo lo permita.

Paso 4: Importa el descriptor en Proxyman

Abre:

Tools → Protobuf Schema

Haz clic en el botón + y elige tu archivo .desc. Proxyman lee los nombres de paquete y los tipos de mensaje disponibles.

También puedes empezar desde el mensaje WebSocket, elegir Protobuf → Decode → Message Type y usar el botón de importación cuando falte el tipo esperado.

Paso 5: Elige el tipo de mensaje correcto

Selecciona el tipo de mensaje raíz que usa el payload. Incluye su nombre de paquete cuando el esquema lo defina.

Por ejemplo:

chat.events.NewMessage

Después de seleccionar el tipo correcto, Proxyman decodifica el payload con sus nombres de campo.

Ahora puedes relacionar los valores binarios con el comportamiento de tu app. Puedes ver IDs, marcas de tiempo, valores de enumeración, mensajes anidados y campos de texto que estaban ocultos en los bytes en bruto.

Proxyman vs mitmproxy para mensajes WebSocket Protobuf

La elección no depende de que una herramienta admita Protobuf y la otra no. Ambas lo admiten. La diferencia está en el flujo de trabajo.

mitmproxy es una opción sólida para los desarrolladores que ya trabajan en su terminal o en su interfaz web. Proxyman resulta útil cuando quieres hacer clic en un frame capturado, probar Raw Mode y luego añadir un descriptor sin salir de la línea de tiempo de mensajes.

Problemas comunes y cómo solucionarlos

Veo la conexión, pero no los mensajes legibles

Primero, confirma que SSL Proxying está habilitado para el host WebSocket. Vuelve a conectarte después de activarlo, porque una conexión segura existente puede seguir cifrada.

Después, confirma que el payload realmente usa Protobuf. Los datos binarios de WebSocket también pueden estar comprimidos, cifrados o usar otro formato, como MessagePack.

Raw Mode muestra números, pero no nombres de campo

Es lo esperado. Protobuf no incluye los nombres de campo originales en cada mensaje binario. Importa el archivo .desc actual y elige el Message Type correcto.

Los valores decodificados parecen incorrectos

Es posible que el tipo de mensaje raíz seleccionado sea incorrecto. Prueba con el tipo que se usa para ese evento concreto. Un mensaje del cliente al servidor y uno del servidor al cliente pueden usar tipos distintos.

El payload también puede contener un wrapper personalizado antes de los bytes Protobuf. Consulta con el equipo de la app si los primeros bytes describen la longitud del mensaje, el tipo de evento o la compresión.

Faltan algunos campos

Es posible que tu descriptor sea más antiguo que la app o el servidor. Elimina el esquema antiguo, genera un nuevo archivo .desc a partir de los archivos .proto actuales e impórtalo de nuevo.

Recuerda que Protobuf no envía los campos que tienen su valor por defecto. Un campo opcional que falta puede ser válido.

No puedo capturar el WebSocket desde una app de iOS

Algunas APIs de WebSocket en iOS no siguen la configuración normal del proxy HTTP. Si tu app usa URLSessionWebSocketTask, sigue la guía de SOCKS Proxy de Proxyman o usa el framework Atlantis, solo para depuración, en una app que desarrollas tú.

La lista de mensajes está demasiado llena

Borra la sesión y repite una acción. Anota la hora de la acción y luego inspecciona los mensajes enviados y recibidos cercanos. Las pruebas pequeñas son mucho más fáciles que grabar varios minutos de tráfico en tiempo real.

Conclusión

WebSocket mantiene los mensajes en movimiento en tiempo real, mientras que Protobuf los mantiene pequeños. Juntos son ideales para una app, pero los datos binarios capturados pueden ser difíciles de entender.

mitmproxy puede decodificar Protobuf con su vista de contenido y una definición .proto. Es potente para los desarrolladores a quienes les gustan las opciones de terminal y los flujos de trabajo automatizados.

Proxyman ofrece a los desarrolladores de macOS un camino visual desde el mensaje WebSocket en tiempo real hasta los valores decodificados. Empieza con Raw Mode si no tienes un esquema. Importa un descriptor .desc y selecciona el Message Type correcto cuando necesites los nombres de campo completos.

Próximos pasos

• Lee la documentación de WebSocket de Proxyman
• Lee la documentación de Protobuf de Proxyman
• Sigue el tutorial detallado Decodificar mensajes WebSocket Protobuf
• Aprende cómo capturar tráfico WebSocket desde simuladores y dispositivos iOS
• Consulta la opción Protobuf de mitmproxy
• Consulta las limitaciones de WebSocket de mitmproxy