🔍 Captura e Inspección

• Intercepta tráfico HTTP y HTTPS (con soporte de CA MITM).
• Muestra todos los metadatos, cabeceras y cuerpos de solicitudes y respuestas.
• Soporta truncamiento para cuerpos muy grandes.

💾 Persistencia

• Las capturas y reglas de color se almacenan en captures.json (o archivo especificado).
• Recarga automáticamente el estado al iniciar y guarda periódicamente en disco.
• Las reglas de color predeterminadas se generan en la primera ejecución si no existen.

🖥️ Interfaz Web

• Interfaz web integrada y responsiva (servida por el propio proxy).
• Muestra las capturas en una lista desplazable con indicadores codificados por color.
• El panel de detalles muestra:
  • Cabeceras/cuerpos de solicitud y respuesta
  • Desglose de tiempos
  • Notas editables
  • Gráfico de rendimiento estilo Gantt para las fases de conexión

🎨 Reglas de Color

• Define resaltados de color condicionales para capturas usando una sintaxis de filtro flexible:
  • Ejemplo: status:4 status:5 → resalta errores HTTP
  • Ejemplo: url:/api/ → resalta solicitudes de API
  • Ejemplo: /\.css$/ → coincidencia regex en URL
• Cada regla incluye: nombre, color, expresión de coincidencia, prioridad y nota.
• Gana la coincidencia de mayor prioridad.
• Gestionado interactivamente a través de una interfaz modal con vistas previas en vivo.
• Persistido entre sesiones.

⏸️ Control de Captura

• El botón Pausar/Reanudar permite dejar de recolectar nuevas capturas sin detener el proxy.
• Útil cuando se centra en un conjunto de datos fijo o se aísla un comportamiento específico.

📈 Visualización de Rendimiento

• Cada captura incluye tiempos detallados de conexión:
  • Resolución DNS
  • Conexión TCP
  • Handshake TLS
  • Procesamiento del servidor
  • Lectura de respuesta
• Mostrado como un diagrama de Gantt en el panel de detalles.
• La escala redondea automáticamente al segundo más cercano para legibilidad.

🧭 Filtrado y Búsqueda

• Caja de filtro en tiempo real que soporta:
  • Filtros basados en campos (method:GET, status:404, header:Content-Type=application/json)
  • Expresiones regex (/login/)
  • Términos combinados con semántica AND/OR
• Coincidencia sin distinción de mayúsculas y parcial soportada.
• El filtro se aplica tanto a la lista de capturas como al resaltado de color.
• Historial de búsqueda almacenado localmente en el navegador.

🧹 Gestión

• Eliminar capturas individuales o borrar todas las capturas a través de la interfaz.
• Las reglas y notas se persisten junto con las capturas.

🧩 Utilidades de Exportación

• Copiar una captura como:
  • Comando curl (formateado para terminal)
  • Fragmento de código python requests (representación JSON limpia)
• Descargar cuerpos de respuesta directamente desde la interfaz.

Uso de Línea de Comandos

Inicio Rápido

Compilar (desde el código fuente)

Esto produce un único ejecutable que contiene el proxy compilado y los activos de UI integrados.

Ejecutar (predeterminado)

Por defecto, el binario se vincula a 127.0.0.1:8080 para proxy (y opcionalmente UI — ver banderas CLI). Abra la UI en un navegador para inspeccionar capturas.

Ejemplo: ejercitar el proxy con curl

El tráfico capturado aparecerá en la interfaz web.

Argumentos de Línea de Comandos

Use ./http-breakout-proxy -h para listar las banderas disponibles y descripciones de uso.

Resumen de la Interfaz Web

La UI está optimizada para flujos de trabajo de investigación.

• Barra de herramientas superior: entrada de filtro global (soporta regex y prefijos con clave), Pausar/Reanudar captura, Limpiar y Ayuda de filtro (se abre en una nueva pestaña).
• Panel izquierdo: lista cronológica de capturas (las más recientes primero). Cada elemento muestra el nombre de la captura; por defecto es MÉTODO URL [ESTADO] pero se puede asignar un nombre personalizado.
• Panel derecho: detalles de la captura seleccionada:
  • Resumen: metadatos, cabeceras y cuerpos (JSON formateado donde corresponda).
  • Pestañas Solicitud / Respuesta: cuerpos formateados en bruto.
  • Pestaña Bruto: JSON completo de la captura.
• Acciones por fila: copiar como curl, copiar como Python requests, descargar cuerpo de respuesta, renombrar, eliminar.

Lenguaje de Filtro (Referencia Rápida)

• Token simple: coincide en cualquier lugar (método, URL, estado, host, cabeceras, cuerpos).
• Prefijos: method:, status:, host:, url:, body:, req.body:, resp.body:, header:, req.header:, resp.header:.
• Sintaxis regex: /patrón/banderas (por ejemplo /bearer\\s+\\S+/i).
• Especificación de cabecera: header:nombre=valor donde nombre o valor pueden ser regex.
• Los términos se combinan con AND lógico por defecto (separados por espacio). Cambie a OR si lo desea modificando la lógica del cliente.

Ejemplos:

• method:POST status:2 host:api.example.com
• /token\\s*[:=]\\s*\\S+/i
• req.header:authorization=/bearer/i
• body:/\\"success\\"\\s*:\\s*true/i

Intercepción HTTPS (MITM)

Cuando el modo Man In The Middle está habilitado:

1. El proxy genera un par de claves CA RSA y un certificado raíz y los almacena en -ca (por defecto ./ca).
2. Para inspeccionar tráfico HTTPS debe agregar el certificado CA generado (ca.pem o similar) al almacén de confianza del cliente (o sistema) que realiza las solicitudes. En muchas plataformas esto requiere privilegios administrativos.
3. El proxy realiza la intercepción TLS emitiendo certificados hoja firmados por la CA local para cada nombre de host solicitado por el cliente.

Nota de seguridad: Instale la CA solo en entornos controlados. No confíe en esta CA en sistemas donde lea tráfico sensible no relacionado.

Persistencia

Si la persistencia está habilitada (a través de -f o ruta configurada):

• Las capturas se escriben periódicamente en disco (por ejemplo, captures.json).
• Al iniciar, la aplicación intenta cargar capturas previas desde el archivo de persistencia en el búfer en memoria (preservando el orden).
• Los cambios de nombre y eliminaciones se sincronizan con el almacen persistente en operaciones de guardado; considere invocar un volcado inmediato para operaciones críticas.

Formato de Almacenamiento

Los elementos capturados se serializan a JSON y contienen los siguientes campos (no exhaustivo):

• id — identificador de secuencia único
• time — marca de tiempo (ISO 8601)
• method, url
• request_headers, response_headers
• request_body, response_body — truncados a -max-body si es necesario
• response_status, duration_ms
• name — etiqueta opcional del usuario
• notes, deleted — metadatos de control para eventos SSE y estado de la UI

Ayudantes de Exportación y Reproducción

• Copiar como cURL: construye un comando curl seguro para shell que incluye cabeceras y cuerpo (omite cabeceras hop-by-hop).
• Copiar como Python: produce un pequeño fragmento requests con url, headers y opcionalmente data.
• Descargar: guarda el cuerpo de respuesta en un archivo; la extensión se infiere de Content-Type cuando es posible.

Consideraciones de diseño:

• Las cabeceras hop-by-hop (por ejemplo, Host, Content-Length, Connection) se omiten de los comandos de reproducción generados.
• Los cuerpos de respuesta binarios (imágenes, PDFs) se pueden descargar usando blobs binarios. Si las respuestas se almacenan codificadas en Base64, el cliente las decodificará antes de la descarga.

API: Endpoints REST (para automatización)

• GET /api/captures — listar capturas (array JSON).
• DELETE /api/captures — borrar todas las capturas.
• GET /api/captures/{id} — recuperar una sola captura.
• DELETE /api/captures/{id} — eliminar una captura específica.
• PATCH /api/captures/{id} — actualizar metadatos de captura; ejemplo de cuerpo: { "name": "Mi etiqueta" }.
• GET /api/pause — devuelve { "paused": true|false }.
• POST /api/pause — establecer estado de pausa; ejemplo de cuerpo: { "paused": true }.
• GET /events — flujo de Eventos Enviados por el Servidor (SSE) para notificaciones de captura en vivo y eventos de control.

Notas de Implementación (para desarrolladores)

• Incrustar UI: usar //go:embed ui/* y fs.Sub para servir archivos estáticos. Esto produce un único artefacto desplegable.
• Descompresión: el código de captura verifica Content-Encoding e intenta descomprimir cuerpos gzip y deflate antes de mostrarlos. Los bytes originales se conservan para transparencia del proxy.
• Concurrencia: el almacén de capturas utiliza bloqueo interno para proporcionar operaciones de agregado/lista/obtención/actualización seguras para hilos. Cuando es posible, se utilizan booleanos atómicos para banderas de alternancia (por ejemplo, pausa/reanudar).
• SSE: un broker ligero transmite adiciones, eliminaciones, cambios de nombre y eventos de control de capturas a los clientes de UI conectados.
• Bufferización: los cuerpos de captura se leen usando io.LimitReader para detectar truncamiento y proteger el uso de memoria.

Empaquetado y Distribución

Modelo de distribución recomendado:

1. Construir binarios estáticos y recortados para las plataformas objetivo (CGO_ENABLED=0, -trimpath, -ldflags "-s -w").
2. Producir archivos (.tar.gz para Unix, .zip para Windows) e incluir README.md y LICENSE.
3. Proporcionar sumas de verificación SHA-256 y adjuntar artefactos a los Lanzamientos de GitHub.
4. Opcionalmente usar goreleaser para automatizar compilaciones multiplataforma y artefactos de lanzamiento.

Ejemplos de comandos de compilación:

Ejecutar como Servicio

Unidad systemd (ejemplo Linux)

launchd (agente de usuario macOS)

Cree un plist en ~/Library/LaunchAgents y cárguelo con launchctl.

Solución de Problemas

• El cuerpo capturado aparece como galimatías binario
  El cuerpo está comprimido (por ejemplo, gzip). Asegúrese de estar ejecutando una compilación que incluya descompresión automática; la UI muestra JSON/texto descomprimido cuando está disponible.

• El tráfico HTTPS no se muestra / errores de conexión
  El cliente no confía en la CA generada. Instale ca/ca.pem en el almacén de confianza del cliente/sistema y márquelo como confiable para la intercepción TLS.

• La UI muestra una selección obsoleta después de borrar capturas
  Actualice a un cliente que borre selectedId en eventos SSE cleared o invoque el endpoint GET /api/captures para refrescar el estado.

• 405 en DELETE /api/captures
  Asegúrese de que el manejador del servidor acepte DELETE para /api/captures y que no esté golpeando una discrepancia de barra final.

Seguridad y Privacidad

Esta herramienta realiza intercepción TLS cuando MITM está habilitado. Úsela solo en entornos controlados donde tenga autorización explícita para inspeccionar tráfico. La CA generada es poderosa: trate su clave privada con la misma confidencialidad que cualquier otra clave privada de CA raíz. No instale la CA en almacenes de confianza compartidos o de producción.

Contribuciones

Las contribuciones son bienvenidas. Por favor, abra issues para errores o solicitudes de características. Para contribuciones de código:

1. Haga un fork del repositorio.
2. Cree una rama de característica.
3. Ejecute pruebas unitarias y linters donde corresponda.
4. Envíe un pull request describiendo el cambio, la justificación y cualquier preocupación de compatibilidad hacia atrás.

Licencia

Este proyecto se distribuye bajo la Licencia MIT. Consulte LICENSE para más detalles.

Atribución y Contacto

Autor: John Southerland (GitHub: jbsouthe)
Proyecto: http-breakout-proxy — destinado a depuración, desarrollo y aprendizaje sobre el comportamiento HTTP.