PacketPirate

Un proxy MITM sin interfaz gráfica, programable y basado en la línea de comandos, diseñado para la interceptación, análisis y modificación de tráfico de red en sistemas Windows. Funciona de manera similar a los proxies GUI estándar de la industria, pero está optimizado para entornos de automatización, operación sin interfaz gráfica e integración con flujos de trabajo de desarrollo.

Nota: Esta es una herramienta independiente, sin dependencias, implementada en Node.js.

Información general

• PacketPirate es una herramienta de interceptación de red a nivel de sistema. Al aprovechar la configuración del proxy HTTP de Windows, puede capturar el tráfico de cualquier aplicación que se ejecute en tu máquina—incluidos navegadores web (Chrome, Edge), herramientas CLI (curl, git) y aplicaciones de escritorio (Spotify, VS Code, Discord).

• Interceptación global del sistema: Captura tráfico HTTP/HTTPS de cualquier proceso que respete el proxy del sistema.

• Consciente de procesos: identifica exactamente qué aplicación está generando tráfico.

• Motor de reglas dinámico: Configurable mediante JSON para realizar acciones específicas sobre el tráfico coincidente (p. ej., extracción de tokens, registro de solicitudes).

• Registro completo de tráfico: Capaz de volcar cuerpos completos de solicitudes y respuestas (HTML, JSON, Binario) para su análisis.

• Arquitectura sin interfaz gráfica: Se ejecuta enteramente desde la CLI, adecuado para servicios en segundo plano y pipelines de pruebas automatizadas.

• Gestión de certificados personalizados: Incluye utilidades para generar y confiar en CAs raíz autofirmadas para el descifrado HTTPS.

Instalación

Requisitos previos

• Node.js (v14 o superior)
• Windows 10/11 (Requerido para las funciones de automatización del proxy del sistema)
• PowerShell (para los scripts de gestión de certificados)

Configuración

Clona el repositorio e inicializa el entorno:

# 1. Generate local SSL certificates
npm run setup

# 2. Trust the generated Root CA
npm run trust
# Note: Requires administrative approval to add the certificate to the Trusted Root Store.

Uso

Inicia el servidor proxy:

npm start

Esto lanza la interfaz CLI estándar.

Operación de la CLI

El menú interactivo proporciona los siguientes controles:

1. Escanear procesos: Enumera los procesos activos con conexiones de red establecidas. Permite filtrar el tráfico a un PID específico (p. ej., monitorear exclusivamente code.exe).
2. Alternar filtros: Habilita/deshabilita subsistemas de monitoreo específicos:
   • Escaneo de URLs de API: Registra los endpoints de API solicitados.
   • Volcado de cabeceras: Vuelca las cabeceras completas de las solicitudes a la consola.
   • Búsqueda de tokens: Detección heurística de tokens Bearer en las cabeceras Authorization.
   • Volcado completo de tráfico: Captura todo el tráfico (cabeceras + cuerpos completos) en archivos de registro jsonl estructurados.
3. Iniciar proxy: Vincula el servidor al primer puerto disponible (por defecto 8080) y configura el proxy del sistema de Windows.
4. Generar reglas: Ayudante para crear rápidamente nuevos patrones de interceptación.

Configuración

La lógica de interceptación se define en config/rules.json. Este archivo permite una configuración persistente del manejo de tráfico.

Esquema:

{
  "rules": [
    {
      "name": "Description of rule",
      "host": "hostname.match",
      "urlPattern": "regex_pattern",
      "action": "log | save_token",
      "outputFile": "path/to/output.txt",
      "tokenFilter": "regex_filter"
    }
  ]
}

Ejemplo:

{
    "rules": [
        {
            "name": "Test API",
            "host": "jsonplaceholder.typicode.com",
            "action": "save_token",
            "outputFile": "test_tokens.txt"
        }
    ]
}

Detalles técnicos

Arquitectura

La herramienta utiliza una arquitectura de doble servidor:

1. Servidor proxy: Gestiona la solicitud de tunelización CONNECT inicial y realiza el filtrado de hosts.
2. Servidor MITM: Descifra el tráfico HTTPS utilizando la CA generada dinámicamente, inspecciona la carga útil contra el motor de reglas y reenvía la solicitud hacia el destino.

Gestión de red

• Gestión de puertos: Detecta automáticamente errores EADDRINUSE e incrementa el número de puerto hasta encontrar uno libre.
• Proxy del sistema: Utiliza la manipulación directa del registro mediante PowerShell para aplicar la configuración del proxy en todo el sistema.
• Limpieza: Implementa manejadores SIGINT/SIGTERM para garantizar que la configuración del proxy se revierta al salir, evitando problemas de conectividad de red.

Ciclo de vida del certificado y seguridad

La herramienta se basa en un modelo de doble certificado para la interceptación HTTPS:

1. Generación de la CA raíz: npm run setup crea una CA raíz autofirmada (PacketPirateRoot).
   • Lógica: Utiliza New-SelfSignedCertificate de PowerShell para generar un par de claves válido por 5 años.
   • Exportación: La clave se exporta a src/certs/server.pfx (formato PKCS#12) con la contraseña "headless".
2. Establecimiento de confianza: npm run trust inyecta esta CA raíz en el almacén CurrentUser\Root de Windows.
   • Alcance de seguridad: Al apuntar a CurrentUser en lugar de LocalMachine, limitamos el radio de confianza a tu perfil de usuario específico, reduciendo el riesgo a nivel de sistema.
   • Aceptación del navegador: Chrome, Edge e IE heredan este almacén de confianza. Firefox requiere una opción separada (security.enterprise_roots.enabled) para respetar el almacén de confianza de Windows.
3. Eliminación: npm run untrust proporciona una limpieza completa.

🎓 Educativo: Cómo lo construimos

Este proyecto es un ejemplo práctico de Programación de Sistemas con Node.js. Va más allá de los servidores web típicos para interactuar con el sistema operativo y la pila de red a un nivel más bajo.

Arquitectura

participant App as Application (VS Code)
participant OS as Windows OS
participant Proxy as Proxy Server
participant MITM as MITM Server
participant Web as Internet

Note over App,Proxy: 1. Plain HTTP Tunneling
App->>Proxy: CONNECT google.com:443
Proxy-->>App: 200 Connection Established

Note over Proxy,MITM: 2. The "Hand-Off" Trick
Proxy->>MITM: Pipe socket data (raw encrypted bytes)

Note over App,MITM: 3. TLS Handshake and Decryption
MITM-->>App: ServerHello (signed by local root CA)
App->>MITM: Encrypted request (GET /)

Note over MITM: 4. Interception Logic
MITM->>MITM: Decrypt → Inspect headers → Log

Note over MITM,Web: 5. Upstream Forwarding
MITM->>Web: New HTTPS request (GET /)
Web-->>MITM: Response
MITM-->>App: Response

Conceptos clave

1. El patrón del "Doble Servidor"

El módulo http estándar de Node.js no puede manejar fácilmente el método CONNECT (utilizado para túneles HTTPS) y el tráfico HTTPS normal en la misma instancia de servidor.

• Servidor A (Net/HTTP): Escucha en el puerto 8080. Gestiona la solicitud CONNECT inicial. Actúa como un conducto TCP simple.
• Servidor B (HTTPS): Existe solo en memoria (o en un puerto aleatorio). Contiene la clave privada.
• El truco: Cuando el Servidor A recibe una conexión, "emite" el socket al Servidor B. El Servidor B cree que acaba de recibir una nueva conexión e inicia el handshake SSL. Esto nos permite descifrar el tráfico de manera transparente.

2. Atribución de procesos (El truco de netstat)

¿Cómo sabemos cuál aplicación está enviando tráfico? Los paquetes TCP en sí no llevan una etiqueta de "ID de proceso".

• Puertos efímeros: Cada conexión saliente utiliza un puerto aleatorio de numeración alta (p. ej., 54321).
• Correlación: Recurrimos a netstat -ano para encontrar qué PID es dueño del puerto 54321.
• Optimización: Hacer esto para cada paquete es lento, así que almacenamos en caché los resultados o solo comprobamos cuando es necesario.

3. Bifurcación de flujos

Usamos Streams de Node.js para manejar los datos de manera eficiente. En lugar de esperar a que se descargue la respuesta completa de 10MB antes de mostrarla, "bifurcamos" el flujo:

• Canal 1: Va al cliente (para que la aplicación siga funcionando).
• Canal 2: Va a nuestro logger (para poder guardarlo en disco). Esto se realiza mediante streams PassThrough, lo que permite el monitoreo en tiempo real con una latencia añadida mínima.

Licencia

GNU GPL v3.0