mandatoryprogrammer/thermopticUn proxy sigiloso HTTP de nueva generación que enmascara perfectamente las peticiones como el navegador Chrome en todas las capas de la pila.
"¡No me lo creo, camuflaje termoóptico!"
Es un proxy HTTP diseñado para evadir servicios que utilizan huellas digitales como JA4+ para bloquear ciertos clientes HTTP. Con este proxy, puedes usar tus clientes HTTP preferidos como curl y aun así tener huellas digitales mágicamente indistinguibles de un navegador web real (Chrome/Chromium). thermoptic también incluye algunas funciones divertidas para mitigar la toma de huellas digitales basada en JavaScript. Además, facilita el scraping híbrido combinando un navegador web y clientes HTTP de bajo nivel.
Incluso si no estás familiarizado con la toma de huellas digitales JA4+, si has hecho scraping, probablemente te hayan bloqueado por ello antes. Servicios populares como Cloudflare usan estas técnicas (y otros trucos) para detectar el uso de clientes HTTP "no humanos" y bloquear solicitudes. Estos servicios también pueden usar esta toma de huellas digitales para detectar si inicias una sesión con un navegador real y luego cambias a un cliente de bajo nivel como curl más adelante. thermoptic resuelve todos estos problemas presentando una huella digital de navegador "real" unificada para todas las solicitudes de scraping.
A continuación se muestra un ejemplo de la huella digital JA4H (HTTP) de curl sin el proxy:```
$ curl https://ja4db.com/id/ja4h/
ge11nn090000_b6a016211e8a_000000000000_e3b0c44298fc
Esto es bastante diferente de la huella que Chrome produce cuando visitas la URL directamente:```
ge11cn19enus_f2808f0d04cf_9a10d4221160_7068f58def6e
Sin embargo, cuando usamos el proxy para hacer la petición, nuestra huella JA4H es mágicamente idéntica:``` $ curl --proxy http://thermoptic:1234 https://ja4db.com/id/ja4h/ ge11cn19enus_f2808f0d04cf_9a10d4221160_7068f58def6e
(Lo mismo aplica para nuestra huella digital TLS JA4, etc.).
## Configuración
Para iniciar un proxy `thermoptic` que oculta tu tráfico a través de una instancia de Chrome contenerizada en Ubuntu 22.04:
Configuración normal de Docker (funciona en hosts sin runtime de GPU):```
docker compose up --build
Eso es todo, ahora puedes enrutar el tráfico a través de él:``` curl --proxy http://127.0.0.1:1234 --insecure https://ja4db.com/id/ja4h/
Notas importantes:
* Por defecto, el proxy se ejecuta sin autenticación. Si planeas exponer el proxy externamente, asegúrate de configurar la autenticación con las variables de entorno `PROXY_USERNAME` y `PROXY_PASSWORD`.
* Si no quieres usar `---insecure`, necesitas usar el archivo CA generado ubicado en `./ssl/rootCA.crt`. Este se genera la primera vez que ejecutas `thermoptic`.
* Puedes conectar `thermoptic` a cualquier instancia de Chrome/Chromium lanzada con el flag `--remote-debugging-port`. Esto es esencial, ya que querrás configurar y hacer proxy a través de entornos más comunes para mantener tu huella lo más discreta posible (p. ej., Chrome en Windows).
* La anulación de compose para GPU está pensada para hosts NVIDIA que ya tengan instalado el runtime/toolkit NVIDIA de Docker. Reserva el dispositivo GPU, monta `/dev/dri` y permite que el contenedor de Chrome incluido cambie a la ruta de renderizado NVIDIA/Vulkan. Para usar esto, ejecuta `docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build`.
## Features
- 🕵️ [Proxy con paridad de navegador](#how-does-this-cloaking-work-exactly) que reproduce las peticiones a través de una sesión real de Chrome para igualar las huellas JA4 byte por byte.
- 🤝 Se requiere poco o ningún código personalizado para integrar tu cliente HTTP (p. ej., `curl`, `requests`, etc.) con `thermoptic`; solo [configura el proxy](#setup) y tus huellas quedarán gestionadas.
- 🪝 [Framework de hooks](#handling-browser-javascript-fingerprinting-with-thermoptic-hooks) para automatización antes de la petición, después de la petición o al inicio, de modo que puedas controlar el navegador completo para resolver desafíos o capturar artefactos.
- 📘 Un ejemplo de hook para resolver Cloudflare Turnstile se puede ver en [`./hooks/onstart.js`](https://github.com/mandatoryprogrammer/thermoptic/blob/main/hooks/onstart.js).
- 🖥️ [Interfaz de control del navegador web](#control-the-dockerized-chrome-browser-via-web-ui-xpra) (en `http://127.0.0.1:14111`) para controlar la ventana del navegador Chrome en Docker. Útil para iniciar sesión manualmente en sitios y luego usar el proxy sin problemas para hacer peticiones como tu sesión iniciada (y para depuración).
- 🔌 Establece una URI de proxy HTTP o SOCKS ascendente mediante la variable de entorno `UPSTREAM_PROXY` en `docker-compose.yml`.
- 🛡️ Comprobaciones de salud integradas y bucle de control de reinicio para detectar navegadores congelados y recuperarse automáticamente sin necesidad de supervisión manual.
- ⚡ Compatible con HTTP/1.1 y HTTP/2, lo que permite realizar proxy del tráfico sobre cualquiera de los dos protocolos. (_Ten en cuenta que puedes hablar HTTP/1.1 con el proxy, y el Chrome manipulado puede negociar con el sitio final mediante un protocolo diferente._)
## ¿Cómo funciona exactamente este camuflaje?
* Se realiza una petición HTTP usando un cliente HTTP como `curl` con `thermoptic` configurado como proxy.
* `thermoptic` analiza la petición para determinar lo mejor posible qué tipo de petición de navegador se *supone* que es (p. ej., ¿visita manual de URL? ¿Envío de formulario? ¿Una petición `fetch()`?).
* `thermoptic` utiliza el [Protocolo de Depuración de Chrome (CDP)](https://chromedevtools.github.io/devtools-protocol/) para manipular el navegador y preparar una página que simula la petición exactamente como ocurriría normalmente en un navegador web real.
* `thermoptic` dispara la petición a través del contexto simulado y captura la respuesta HTTP.
* `thermoptic` envía la respuesta HTTP de vuelta al cliente.
Debido a que el navegador es quien realiza realmente la petición usando su pila completa, las huellas JA4 resultantes son idénticas.
NOTA: Debido a que muchos WAF emplean fingerprinting a nivel de JavaScript de los navegadores web, `thermoptic` también expone hooks para utilizar el navegador en pasos clave del proceso de scraping. Consulta [esta sección](#handling-browser-javascript-fingerprinting-with-thermoptic-hooks) para más información al respecto.
## ¿Por qué *este* enfoque frente a otras soluciones?
Siendo francos: otros enfoques tienen fallos fundamentales que les impiden ser una solución práctica a largo plazo para el problema del fingerprinting de navegador.
Muchos otros intentos de "vencer" el fingerprinting JA4+ del navegador lo hacen reimplementando las distintas capas de la pila del navegador. Este enfoque tiene varios inconvenientes graves, como:
* Requiere gran cuidado para igualar perfectamente el comportamiento de la implementación del navegador "real". Como resultado, *cualquier* rareza o discrepancia puede usarse para diferenciar estos clientes de la implementación del navegador "real".
* Intentar resolver el problema solo en una capa de la pila. Chrome utiliza múltiples protocolos para ofrecer una experiencia de navegación web. Como resultado, incluso si has creado una capa TLS perfectamente coincidente, tu capa HTTP puede delatarte si no es perfecta a nivel de bytes.
* Dado que los navegadores "reales" cambian regularmente su comportamiento, sus huellas cambian y, como resultado, estas herramientas requieren constantemente un trabajo de desarrollo más intensivo para compensarlo.
En cambio, como `thermoptic` usa el propio navegador para realizar peticiones HTTP:
* Cada capa de la pila, como TCP, TLS y HTTP, es indistinguible del navegador real porque la petición se realiza *usando* un navegador real de la forma en que ocurriría *normalmente*.
* Los cambios en el comportamiento del navegador en varias capas son mínimamente disruptivos; el navegador que controla `thermoptic` solo necesita actualizarse para igualar el último conjunto de huellas.
Por supuesto, ninguna solución está exenta de inconvenientes. Consulta la documentación `DOWNSIDES.md` para obtener una lista detallada de las desventajas del enfoque de `thermoptic`.
## Preguntas frecuentes
### ¿Por qué el nombre `thermoptic`?
"Thermoptic" (abreviatura de "camuflaje termoóptico") es una referencia al camuflaje ficticio [usado por la Mayor en el anime Ghost in the Shell (1995)](https://ghostintheshell.fandom.com/wiki/Thermoptic_camouflage). En la película, se muestra que este camuflaje puede ocultar a quien lo lleva en múltiples espectros de detección, incluidos la luz visible y la radiación térmica. Del mismo modo, esta herramienta intenta ocultar al usuario del fingerprinting a través de múltiples canales (HTTP, TLS, etc.).
### ¡JA4+ es una **suite** de huellas! ¿Cuáles falsifica?
Esta herramienta falsificará las siguientes huellas JA4 para que sean exactamente como las del navegador Chrome/Chromium al que estás conectado:
* JA4 (huella TLS)
* JA4H (huella HTTP)
* JA4X (huella de certificado TLS X509)
* JA4T (huella TCP)
### ¿Y si quiero usar otro proxy HTTP/SOCKS ascendente con esto?
`thermoptic` ahora enruta la instancia de Chrome controlada a través de un servicio interno `proxyrouter`, por lo que puedes apuntar Chrome a proxies HTTP o SOCKS ascendentes (incluidos aquellos que requieren credenciales). Establece la URI del proxy ascendente editando el valor `UPSTREAM_PROXY` en `docker-compose.yml`, dentro del servicio `proxyrouter`. Si lo dejas vacío, Chrome habla directamente con Internet a través del proxy no autenticado del clúster.
Ejemplo para configurar un proxy SOCKS ascendente:```yaml
proxyrouter:
environment:
UPSTREAM_PROXY: "socks5://username:[email protected]:1080"
Ten en cuenta que algunos proxies ascendentes pueden cambiar las huellas dactilares de bajo nivel (por ejemplo, los metadatos TCP), lo que puede reducir la paridad con un navegador residencial.
thermoptic cargará el navegador con las cookies que tu cliente especifique en la cabecera Cookie. La petición incluirá estas una vez que se ejecute en el contexto del navegador. Esto se hace para asegurar que el servidor no pueda tomar la huella del orden de las cookies ni otros trucos baratos por el estilo.
NOTA: estas cookies también permanecerán después de la petición. Si deseas implementar lógica de limpieza para las cookies, escribe un hook de thermoptic.
Sí, thermoptic admite el uso híbrido como este, consulta esta sección para más información.
Debes asegurarte de que estás configurando cabeceras como X-Fetch-*, Origin y Referer correctamente. Si no le indicas a thermoptic estas cabeceras, no podrá ejecutar la petición de la manera sigilosa adecuada.
Sin configurar cabeceras contextuales, thermoptic establecerá valores predeterminados que pueden no reflejar exactamente lo que tu sitio objetivo espera. Por ejemplo, si no estableces una cabecera Origin, establecerá un Origin de null; si no estableces una cabecera Referer, simplemente no enviará ningún Referer.
Te conviene incluir estas cabeceras contextuales para que tu petición sea lo más sigilosa posible. thermoptic no puede leer tu mente, solo puede leer tu petición :).
Generalmente esto solo se aplica en el caso de los hooks de thermoptic que utilizan temporalmente el navegador web completo para superar comprobaciones de JavaScript/nivel de navegador. Cuando uses temporalmente estos hooks y el modo de navegador completo, deberás tener cuidado de no ser identificado como bot (p. ej., evita trampas como Runtime.enable).
Las consideraciones éticas y la compleja teoría de juegos en juego aquí son mayores de lo que puede responderse en un README. Siéntete libre de argumentar en contra de cualquiera de estos puntos simplificados cuando me flamees por correo electrónico/Twitter/Github:
Para más charla sobre la carrera armamentística del scraping, te pido que al menos me invites a una cerveza primero. Para ser honesto, odio escribir estos aburridos ensayos éticos en mis READMEs, así que siéntete libre de imaginarme como un nerd malvado que quiere hacerte la vida más difícil.
thermopticthermoptic te permite configurar scripts personalizados para realizar acciones en el navegador cuando:
ON_START_HOOK_FILE_PATH)BEFORE_REQUEST_HOOK_FILE_PATH)AFTER_REQUEST_HOOK_FILE_PATH)Esto te permite usar el Chrome Debugging Protocol para hacer clic y establecer las cookies adecuadas para sitios que requieren un navegador web real para un paso de verificación. Luego puedes usar el proxy de thermoptic para continuar tu sesión camuflada a través del mismo navegador.
Para hacer esto, modifica el archivo JavaScript de hook correspondiente con tu código personalizado para orquestar el navegador adecuadamente a través de la interfaz chrome-remote-interface proporcionada:```
// cdp is an instance of a connected browser, use it to run your browser actions
export async function hook(cdp) {
console.log([STATUS] Browser start hook called successfully!);
}
Para un ejemplo de implementación, consulta el archivo [`./hooks/onstart.js`](https://github.com/mandatoryprogrammer/thermoptic/blob/main/hooks/onstart.js) que [evita el CAPTCHA turnstile de Cloudflare](https://github.com/mandatoryprogrammer/thermoptic/blob/main/tutorials/turnstile/cloudflare-turnstile-bypass.md) (y otras comprobaciones anti-bot de Cloudflare).
## Controla el navegador Chrome dockerizado mediante la interfaz web (Xpra)
`thermoptic` viene con una interfaz web de Xpra disponible en `http://127.0.0.1:14111`. Esto te permite controlar manualmente el navegador Chrome dockerizado con facilidad:
<img src="https://assets.kitploit.com/production/public/readmes/49068/0fa1b187f46405dda2b0db5d461619daa6a7bdad2c385cb51994e870d9054d10.png" width="100%">
Esto es útil para cosas como:
* Iniciar sesión en tu cuenta para poder realizar solicitudes autenticadas a través de `thermoptic` usando tu cliente HTTP preferido como `curl`.
* Por ejemplo, si inicias sesión en `reddit.com` con el navegador, ¡todas las solicitudes que hagas a Reddit a través de `thermoptic` se autenticarán automáticamente con tu cuenta de Reddit!
* Depurar tus hooks personalizados de `thermoptic` y comprobar problemas con sitios web.
## Configuración
Estas variables de entorno especifican cómo debe configurarse `thermoptic` cuando se ejecuta.
`HTTP_PROXY_PORT`: El puerto en el que debe escuchar el proxy de `thermoptic`. Si estás ejecutando `thermoptic` en Docker, también tendrás que cambiar el campo de mapeo `ports` para que coincida.
`CHROME_DEBUGGING_PORT`: El puerto en el que queda expuesto el Chrome Debugging Protocol. Este puerto se especifica cuando lanzas Chrome/Chromium con el flag `--remote-debugging-port` establecido a un valor como `9222`.
`CHROME_DEBUGGING_HOST`: El host en el que queda expuesto el Chrome Debugging Protocol. Normalmente es `127.0.0.1` si el navegador se lanza localmente y `thermoptic` no se está ejecutando en Docker. Si se ejecuta en Docker, puede que tengas que usar `host.docker.internal`; consulta la [documentación de Docker](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host) para más información.
`PORT`: El puerto CDP que el contenedor de Chrome publica hacia el resto de la pila. Mantenlo alineado con `CHROME_DEBUGGING_PORT` para que el puente `socat` siga funcionando como se espera.
`CHROME_CONTROL_PORT`: El puerto del servicio de control de Chrome que thermoptic usa para gestionar el navegador (por ejemplo, para enviar solicitudes de reinicio).
`CHROME_CONTROL_COOLDOWN_MS`: Tiempo mínimo en milisegundos entre intentos de reinicio de Chrome. Úsalo para evitar bucles de reinicio rápidos cuando se producen varios fallos en rápida sucesión.
`ENABLE_GUI_CONTROL`: Establécelo a `true` para lanzar el panel web de xpra y poder manejar el Chrome contenedorizado visitando `http://127.0.0.1:14111`. Desactívalo para ejecuciones solo headless.
`CHROME_SCREEN_WIDTH` / `CHROME_SCREEN_HEIGHT`: Las dimensiones en píxeles de la pantalla del Chrome dockerizado headful.
`CHROME_ENABLE_GPU`: Controla si el contenedor de Chrome incluido debe intentar usar la aceleración GPU del host. `auto` (predeterminado) habilita la ruta NVIDIA/Vulkan cuando el runtime y los nodos de dispositivo requeridos están presentes; de lo contrario, recurre al renderizado por software. Establécelo a `false` para forzar el comportamiento anterior solo por software.
`CHROME_PROFILE_RECOVERY`: Cuando es `true` (predeterminado), el lanzador de Chrome incluido hará un intento de recuperación si Chrome muere inmediatamente con el mismo código de salida de bucle de caída observado en un perfil envenenado (`133`). Los contenidos del perfil dañado se mueven a `/tmp/chrome-profile-recovery/` dentro del contenedor antes de reintentar con un perfil limpio.
`PROXY_USERNAME`: El nombre de usuario que se usa para autenticarte en el proxy; el valor predeterminado es `changeme`. Si no se establece, el proxy se ejecuta sin requerir autenticación.
`PROXY_PASSWORD`: La contraseña que se usa para autenticarte en el proxy; el valor predeterminado es `changeme`. Si no se establece, el proxy se ejecuta sin requerir autenticación.
`THERMOPTIC_CONTAINER_RUNTIME`: Indica que thermoptic se está ejecutando dentro del contenedor incluido. Déjalo establecido en `true`; controla comportamientos como las comprobaciones de salud integradas que solo tienen sentido en la configuración completa de Docker.
`HEALTHCHECK_ENDPOINT_PORT`: El puerto donde thermoptic expone su endpoint web de comprobación de salud. El trabajador de salud llama a este endpoint a través del proxy; si deja de responder, Chrome se reinicia automáticamente para desbloquear sesiones congeladas.
`HEALTHCHECK_ENDPOINT_PATH`: La ruta HTTP servida por el endpoint de comprobación de salud descrito anteriormente. Cámbiala si necesitas una URL diferente.
`ON_START_HOOK_FILE_PATH`: Código Node personalizado para ejecutar al inicio del proxy. El proxy no comenzará a escuchar hasta que este hook haya terminado; consulta el ejemplo en `./hooks/`. La muestra demuestra cómo usar el navegador para pasar la comprobación de navegador JavaScript de Cloudflare antes de iniciar el proxy.
`BEFORE_REQUEST_HOOK_FILE_PATH`: Código Node personalizado para ejecutar antes de que una solicitud pase por el proxy. Esto es útil si necesitas que el navegador pase alguna comprobación antes de que se realice una solicitud HTTP al sitio.
`AFTER_REQUEST_HOOK_FILE_PATH`: Código Node personalizado para ejecutar después de que una solicitud haya pasado por el proxy. A menudo es útil para hacer cosas como limpiar cookies que el cliente haya establecido mediante la cabecera `Cookie`.
`DEBUG`: Establécelo a `true` cuando encuentres un bug para que thermoptic imprima diagnósticos detallados antes de que reportes un problema; déjalo en `false` durante la operación normal.
## Seguridad
Ten en cuenta que, por ahora, `thermoptic` solo está pensado para usarse con clientes HTTP en los que confíes explícitamente. *No* está pensado para exponerse a usuarios no confiables.
Si encuentras vulnerabilidades de seguridad, por favor envía un informe a `mandatory@` Gmail.