# MITMEngine

[![Build Status](https://travis-ci.org/cloudflare/mitmengine.svg?branch=master)](https://travis-ci.org/cloudflare/mitmengine)

## AVISO DE OBSOLESCENCIA: Este software ya no recibe mantenimiento.

El objetivo de este proyecto es permitir la detección precisa de la interceptación HTTPS y la robusta toma de huellas dactilares TLS.
Este proyecto se basa en [The Security Impact of HTTPS Interception](https://zakird.com/papers/https_interception.pdf), y comenzó como un puerto a Go de [sus scripts de procesamiento y huellas dactilares](https://github.com/zakird/tlsfingerprints).

Más contexto sobre MITMEngine está disponible en esta [entrada del blog de Cloudflare](https://blog.cloudflare.com/monsters-in-the-middleboxes/).
Enlaces rápidos:
- [Firmas y Huellas Dactilares: Definiciones Básicas](#signature-and-fingerprints)
- [Metodología de Detección de MITM](#mitm-detection-methodology)
- [API](#api)
- [Ejemplo de Uso](#example-usage)
- [Construcción y Pruebas](#building-and-testing)
- [Cómo Contribuir](#how-to-contribute)
- [Utilidad mergeDB](#mergedb-utility)

## Requisitos

- Go
- Wireshark 3.0.0 (`wireshark -v` para comprobar)

## Documentación
La documentación detallada vive con el código (primero copia el paquete a $(GOPATH)/src/github.com/cloudflare/mitmengine).

	godoc -http=:6060

http://localhost:6060/pkg/github.com/cloudflare/mitmengine

### Firmas y Huellas Dactilares
En este proyecto, las huellas dactilares se asignan a instancias concretas de un objeto, mientras que las firmas pueden representar múltiples objetos.
Usamos esta convención porque una huella dactilar es usualmente una propiedad inherente de un objeto, mientras que una firma puede ser elegida.
De la misma manera, una solicitud de cliente real vista por un servidor tendría una huella dactilar, mientras que el software que genera la solicitud puede elegir su propia firma (por ejemplo, eligiendo qué conjuntos de cifrado soporta).

### Solicitud de Cliente
Una huella dactilar de solicitud de cliente se deriva de una solicitud de cliente a un servidor, y contiene características tanto TLS como HTTP. Una firma de solicitud de cliente representa todas las huellas dactilares posibles que un software puede generar. El objetivo es hacer que cada firma sea lo suficientemente específica como para identificar de manera única un software.

### Agente de Usuario
Una firma de Agente de Usuario representa un conjunto de Agentes de Usuario generados por un navegador. Una firma de Agente de Usuario para un navegador permite un rango de versiones del navegador, y permite especificar el nombre del SO, la plataforma del SO, el rango de versiones del SO, y el tipo de dispositivo para crear firmas más detalladas.

### Navegador
Una firma de navegador contiene tanto una firma de Agente de Usuario como una firma de solicitud de cliente. Esto permite que una firma represente todas las huellas dactilares posibles generadas por Chrome 31-38 en Windows 10, por ejemplo.

### MITM
Una firma MITM contiene una firma de solicitud de cliente junto con detalles adicionales sobre el software MITM, incluyendo una calificación de seguridad que puede verse afectada por factores externos a la solicitud del cliente, como si el software valida o no los certificados.

## Metodología de Detección de MITM
Consideramos que una conexión HTTPS está interceptada cuando hay una discrepancia entre la firma de solicitud de cliente esperada correspondiente al navegador identificado por el Agente de Usuario, y la huella dactilar de solicitud de cliente real de la solicitud.

### Falsos positivos
Si una firma es inexacta o está desactualizada para un software de cliente determinado, es posible que la firma marque falsamente una conexión como interceptada.

### Falsos negativos
Si un proxy imita estrechamente la solicitud del cliente, entonces es posible que no esperemos detectar una discrepancia. Si las firmas del navegador son demasiado amplias, también fallaremos en detectar la interceptación.

### Huellas dactilares de producción
Las huellas dactilares de referencia del navegador y del software MITM utilizadas en [MALCOLM](https://malcolm.cloudflare.com) se pueden encontrar en `reference_fingerprints/mitmengine/`.
Este conjunto de huellas dactilares es una combinación de lo que se extrae de los pcaps TLS Client Hello en `reference_fingerprints/pcaps/`, así como los 500 pares principales de User Agents + TLS Client Hello observados en la red de Cloudflare y etiquetados con una alta calificación de confiabilidad (es decir, tráfico correspondiente a actividad humana y de bots amigables).

Idealmente, no tenemos que depender de huellas dactilares de referencia muestreadas de la red de Cloudflare; en su lugar, tendríamos un conjunto completo de pcaps para construir nuestro conjunto de TLS Client Hellos de referencia. ¿Interesado en ayudarnos a construir nuestro conjunto de datos? ¡Vea cómo [puede contribuir](#submit-a-pull-request)!

## API
Primero, un usuario debe crear una estructura `mitmengine.Config` para pasar a `mitmengine.NewProcessor`. Una estructura `mitmengine.Config` puede especificar nombres de archivos que contengan huellas dactilares de navegadores, huellas dactilares MITM y encabezados MITM.
Alternativamente, también puede especificar un archivo de configuración para leer los archivos mencionados anteriormente desde cualquier otra fuente; actualmente, MITMEngine admite la lectura de estos archivos desde bases de datos compatibles con el cliente de Amazon S3 (incluyendo Amazon S3 y Ceph).
Se pueden definir lectores de archivos adicionales para bases de datos (que llamamos "loaders") en el paquete `loaders`, y mientras los nuevos loaders implementen la interfaz Loader, deberían funcionar con el resto de MITMEngine de inmediato.

El punto de entrada previsto al paquete MITMEngine es a través de la función `Processor.Check`, que toma un Agente de Usuario y una huella dactilar de solicitud de cliente, y devuelve un informe de detección de mitm. Se agregarán funciones API adicionales en el futuro para permitir agregar nuevas firmas a un proceso en ejecución, por ejemplo.

## Ejemplo de Uso
A continuación se muestra un ejemplo de uso de la API. Una aplicación más completa está disponible en `cmd/demo/main.go`, y se puede compilar ejecutando `make bin/demo`.

	rawUa := "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36"
	requestFingerprintString := "303:dada,1301,1302,1303,c02b,c02f,c02c,c030,cca9,cca8,c013,c014,9c,9d,2f,35,a:aaaa,0,17,ff01,a,b,23,10,5,d,12,33,2d,2b,1b,dada,15:9a9a,1d,17,18:0::"
	uaFingerprintString := "1:72.0.3626:2:3:10.14.3:1:"
	requestFingerprint, _ := fp.NewRequestFingerprint(requestFingerprintString)
	uaFingerprint, _ := fp.NewUAFingerprint(uaFingerprintString)
	report := mitmProcessor.Check(uaFingerprint, rawUa, requestFingerprint)

La cadena requestFingerprintString de TLS tiene el siguiente formato:

	<tls_version>:<cipher_suites>:<extension_names>:<curves>:<ec_point_fmts>:<http_headers>:<quirks>

La uaFingerprint tiene el siguiente formato:

	# <browser_name>:<browser_version>:<os_platform>:<os_name>:<os_version>:<device_type>:<quirks>

Un ejemplo de cómo analizar User Agents en el formato para uaFingerprint está en el archivo `cmd/demo/main.go`.

## Construcción y Pruebas
Para usar MITMEngine, recuerda obtener sus dependencias. Probablemente quieras ejecutar la lógica de vendoring o gomod antes de ejecutar pruebas en MITMEngine.
Para probar, ejecuta `make test` y para ver la cobertura de código, ejecuta `make cover`.

## Cómo Contribuir
Dado que las huellas dactilares de navegadores y MITM se vuelven obsoletas rápidamente, estamos buscando activamente actualizar el repositorio de huellas dactilares con nuevas muestras.

Al contribuir con una muestra de huella dactilar (la "Muestra"), usted (en su propio nombre o en nombre de la organización que representa o por la que está patrocinado (si corresponde)) otorga a Cloudflare, Inc. y sus subsidiarias y afiliadas un derecho y licencia perpetua, irrevocable, no exclusiva, libre de regalías, a nivel mundial bajo todos los derechos de propiedad intelectual en la Muestra, para: (1) copiar, publicar, mostrar y distribuir la Muestra; y (2) preparar trabajos derivados que se basen en o formen parte de la Muestra.

Para contribuir con muestras de huellas dactilares, siga estos pasos:

### Generar una muestra de huella dactilar
(probado en macOS Mojave 10.14.3)

Crear par de clave y certificado RSA del servidor:

	openssl req -new -x509 -sha256 -out server.crt -nodes -keyout server.pem -subj /CN=localhost

Iniciar servidor en el puerto 4433:

	openssl s_server -www -cipher AES256-SHA -key server.pem -cert server.crt

Iniciar captura de TShark para descifrar encabezados HTTP (TShark >= 3.0.0):

	tshark -i loopback -o tls.keys_list:"127.0.0.1,4433,http,server.pem" -Tjson -e http.request.line -Y http > header.json

Iniciar captura de TShark de TLS Client Hello:

	tshark -i loopback -f "tcp port 4433" -w handshake.pcap

Visite `https://localhost:4433` desde el cliente TLS que desea identificar. Por ejemplo,

	echo -e "GET /test HTTP/1.1\r\nHost:example.com\r\n\r\n" | openssl s_client -connect localhost:4433

### Enviar una solicitud de extracción
- Genere una muestra de huella dactilar (`header.json`, `handshake.pcap`) como se describió anteriormente, y colóquela en el directorio `reference_fingerprints/pcaps/<desc>`, donde `<desc>` es un nombre único y descriptivo.
- Agregue una línea a `reference_fingerprints/fingerprint_metadata.jsonl` con los campos a continuación. Las opciones reconocidas para los campos `os`, `device`, `platform` y `browser` son las definidas en el paquete `uasurfer`. Las opciones reconocidas para `mitm_fingerprint.type` se enumeran a continuación. Consulte `reference_fingerprints/fingerprint_metadata.jsonl` para ver ejemplos; cualquier campo desconocido se puede dejar en blanco u omitir.

	{ "desc": "<unique and descriptive name for sample>", "comment": "<additional information about the sample>", "handshake_pcap": "<path to pcap containing a TLS Client Hello>", "header_json": "<(optional) path to file containing the client HTTP request", "ua_fingerprint": {"raw_ua": "<raw User Agent string>", "os": "<WindowsPhone|Windows|MacOSX|iOS|Android|...>", "os_version": "<major>.<minor>.<patch>", "device": "<Windows|Mac|Linux|...>", "platform": "<Computer|Tablet|Phone|...>", "browser": "<Chrome|IE|Safari|Firefox|...>", "browser_version": "<major>.<minor>.<patch>"}, "mitm_fingerprint": { "name": "<description of mitm>", "type": "<Antivirus|FakeBrowser|Malware|Parental|Proxy>" }}

- Envíe una solicitud de extracción con los cambios anteriores.

¡Otras PRs y solicitudes de características son bienvenidas!

## Utilidad mergeDB
mergeDB (en `cmd/mergedb`) es una utilidad para fusionar huellas dactilares similares de TLS ClientHello en múltiples versiones cercanas de navegadores o software MITM. Use mergeDB para consolidar grandes listas de huellas dactilares de User Agent / Client Hello:

	go run cmd/mergedb/main.go

Por defecto, mergeDB se ejecutará en las huellas dactilares en el directorio `reference_fingerprints/mitmengine`.
mitmengine

Más Populares
