mandatoryprogrammer/thermopticUn proxy HTTP furtif de nouvelle génération qui déguise parfaitement les requêtes en navigateur Chrome sur toutes les couches de la pile.
« Je n'y crois pas, le camouflage thermoptique ! »
Ceci est un proxy HTTP conçu pour contourner les services qui utilisent le fingerprinting tel que JA4+ pour bloquer certains clients HTTP. Avec ce proxy, vous pouvez utiliser vos clients HTTP préférés comme curl et avoir des empreintes numériques magiquement indiscernables de celles d'un vrai navigateur web (Chrome/Chromium). thermoptic propose également quelques fonctionnalités sympas pour atténuer le fingerprinting basé sur JavaScript. Il facilite aussi le scraping hybride en utilisant à la fois un navigateur web et des clients HTTP de bas niveau.
Même si vous n'êtes pas familier avec le fingerprinting JA4+, si vous avez déjà fait du scraping, vous avez probablement déjà été bloqué par ce mécanisme. Des services populaires comme Cloudflare utilisent de telles techniques (et d'autres astuces) pour détecter l'utilisation de clients HTTP « non humains » afin de bloquer les requêtes. Ces services peuvent également utiliser ce fingerprinting pour détecter si vous démarrez une session avec un vrai navigateur, puis passez à un client de bas niveau comme curl plus tard. thermoptic résout tous ces problèmes en présentant une empreinte unifiée de navigateur « réel » pour toutes les requêtes de scraping.
Voici un exemple d'empreinte JA4H (HTTP) de curl sans le proxy :```
$ curl https://ja4db.com/id/ja4h/
ge11nn090000_b6a016211e8a_000000000000_e3b0c44298fc
Ceci est tout à fait différent de l'empreinte que Chrome produit lorsque vous visitez l'URL directement:```
ge11cn19enus_f2808f0d04cf_9a10d4221160_7068f58def6e
Cependant, lorsque nous utilisons le proxy pour effectuer la requête, notre empreinte JA4H est magiquement identique :``` $ curl --proxy http://thermoptic:1234 https://ja4db.com/id/ja4h/ ge11cn19enus_f2808f0d04cf_9a10d4221160_7068f58def6e
(Il en va de même pour notre empreinte TLS JA4, etc.).
## Configuration
Pour démarrer un proxy `thermoptic` qui masque votre trafic via une instance Chrome conteneurisée sur Ubuntu 22.04 :
Configuration Docker standard (fonctionne sur les hôtes sans runtime GPU) :```
docker compose up --build
C'est tout, vous pouvez maintenant faire transiter le trafic via celui-ci:``` curl --proxy http://127.0.0.1:1234 --insecure https://ja4db.com/id/ja4h/
Notes importantes :
* Par défaut, le proxy fonctionne sans authentification. Si vous prévoyez d'exposer le proxy à l'extérieur, veuillez configurer l'authentification avec les variables d'environnement `PROXY_USERNAME` et `PROXY_PASSWORD`.
* Si vous ne souhaitez pas utiliser `---insecure`, vous devez utiliser le fichier CA généré situé dans `./ssl/rootCA.crt`. Ce fichier est généré la première fois que vous exécutez `thermoptic`.
* Vous pouvez connecter `thermoptic` à toute instance Chrome/Chromium lancée avec le drapeau `--remote-debugging-port`. C'est essentiel car vous voudrez configurer et utiliser le proxy via des environnements plus courants afin de garder votre empreinte aussi discrète que possible (par exemple Chrome sous Windows).
* La surcharge compose GPU est destinée aux hôtes NVIDIA ayant déjà le runtime/kit NVIDIA de Docker installé. Elle réserve le périphérique GPU, monte `/dev/dri` et permet au conteneur Chrome fourni de basculer vers le chemin de rendu NVIDIA/Vulkan. Pour l'utiliser, exécutez `docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build`.
## Fonctionnalités
- 🕵️ [Proxy à parité navigateur](#how-does-this-cloaking-work-exactly) qui rejoue les requêtes via une session Chrome réelle pour correspondre aux empreintes JA4 octet par octet.
- 🤝 Peu ou pas de code personnalisé nécessaire pour intégrer votre client HTTP (par ex. `curl`, `requests`, etc.) avec `thermoptic`, il suffit de [configurer le proxy](#setup) et vos empreintes sont gérées.
- 🪝 [Framework de hooks](#handling-browser-javascript-fingerprinting-with-thermoptic-hooks) pour l'automatisation avant-requête/après-requête/au démarrage, afin de piloter le navigateur complet pour résoudre des défis ou capturer des artefacts.
- 📘 Un exemple de hook pour résoudre le turnstile Cloudflare est disponible dans [`./hooks/onstart.js`](https://github.com/mandatoryprogrammer/thermoptic/blob/main/hooks/onstart.js).
- 🖥️ [Interface de contrôle du navigateur web](#control-the-dockerized-chrome-browser-via-web-ui-xpra) (à `http://127.0.0.1:14111`) pour contrôler la fenêtre du navigateur Chrome dockerisé. Utile pour vous connecter manuellement à des sites puis utiliser le proxy de manière transparente pour effectuer des requêtes dans votre session connectée (et pour le débogage).
- 🔌 Définissez un URI de proxy HTTP ou SOCKS en amont via la variable d'environnement `UPSTREAM_PROXY` dans `docker-compose.yml`.
- 🛡️ Contrôles de santé intégrés et boucle de contrôle de redémarrage pour détecter les navigateurs figés et récupérer automatiquement sans surveillance de l'opérateur.
- ⚡ Prend en charge HTTP/1.1 et HTTP/2, permettant de proxifier le trafic via l'un ou l'autre protocole. (_Notez que vous pouvez parler en HTTP/1.1 au proxy, et que le Chrome piloté peut négocier avec le site final via un protocole différent._)
## Comment fonctionne ce cloaking exactement ?
* Une requête HTTP est effectuée à l'aide d'un client HTTP tel que `curl` avec `thermoptic` configuré comme proxy.
* `thermoptic` analyse la requête pour déterminer au mieux quel type de requête navigateur elle est *censée* être (par ex. visite manuelle d'URL ? Envoi de formulaire ? Une requête `fetch()` ?).
* `thermoptic` utilise le [Chrome Debugging Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/) pour piloter le navigateur et configurer une page qui simule la requête exactement comme elle se produirait normalement dans un vrai navigateur web.
* `thermoptic` déclenche la requête via le contexte simulé et capture la réponse HTTP.
* `thermoptic` renvoie la réponse HTTP au client.
Étant donné que le navigateur effectue réellement la requête en utilisant sa pile complète, les empreintes JA4 résultantes sont identiques.
NOTE : En raison des nombreux WAF qui utilisent l'empreinte JavaScript des navigateurs web, `thermoptic` expose également des hooks pour utiliser le navigateur lors des étapes clés du processus de scraping. Voir [cette section](#handling-browser-javascript-fingerprinting-with-thermoptic-hooks) pour plus d'informations.
## Pourquoi *cette* approche plutôt que d'autres solutions ?
Pour être direct : les autres approches présentent des défauts fondamentaux qui les empêchent d'être une solution pratique à long terme au problème de l'empreinte navigateur.
De nombreuses autres tentatives pour « battre » l'empreinte JA4+ des navigateurs réimplémentent les différentes couches de la pile navigateur. Cette approche présente un certain nombre d'inconvénients sérieux, tels que :
* Exiger une grande attention pour correspondre parfaitement au comportement de l'implémentation du « vrai » navigateur. Par conséquent, *toute* particularité ou divergence peut être utilisée pour différencier ces clients de l'implémentation du « vrai » navigateur.
* Tenter de résoudre le problème uniquement à une seule couche de la pile. Chrome utilise plusieurs protocoles pour offrir une expérience de navigation web. Par conséquent, même si vous avez créé une couche TLS parfaitement identique, votre couche HTTP peut vous trahir si elle n'est pas parfaite au niveau de l'octet.
* Comme les « vrais » navigateurs changent régulièrement de comportement, leurs empreintes changent, et par conséquent ces outils nécessitent constamment un travail de développement plus intensif pour compenser.
En revanche, comme `thermoptic` utilise le navigateur lui-même pour effectuer les requêtes HTTP :
* Chaque couche de la pile, comme TCP, TLS, HTTP, est impossible à distinguer du vrai navigateur car la requête est effectuée *en utilisant* un vrai navigateur de la manière dont elle se produirait *normalement*.
* Les changements de comportement du navigateur à différentes couches sont peu perturbateurs ; le navigateur contrôlé par `thermoptic` a seulement besoin d'être mis à jour pour correspondre au dernier ensemble d'empreintes.
Bien sûr, aucune solution n'est sans inconvénients. Consultez la documentation `DOWNSIDES.md` pour une liste détaillée des inconvénients de l'approche `thermoptic`.
## FAQ
### Pourquoi le nom `thermoptic` ?
« Thermoptic » (diminutif de « thermoptic camouflage ») fait référence au camouflage fictif [utilisé par Major dans l'anime Ghost in the Shell (1995)](https://ghostintheshell.fandom.com/wiki/Thermoptic_camouflage). Dans le film, ce camouflage se révèle capable de cacher celui qui le porte sur plusieurs spectres de détection, notamment la lumière visible et le rayonnement thermique. De même, cet outil tente de dissimuler l'utilisateur à l'empreinte numérique sur plusieurs canaux (HTTP, TLS, etc.).
### JA4+ est une **suite** d'empreintes ! Lesquelles imite-t-il ?
Cet outil imitera les empreintes JA4 suivantes pour qu'elles ressemblent exactement au navigateur Chrome/Chromium auquel vous êtes connecté :
* JA4 (empreinte TLS)
* JA4H (empreinte HTTP)
* JA4X (empreinte du certificat TLS X509)
* JA4T (empreinte TCP)
### Et si je veux utiliser un autre proxy HTTP/SOCKS en amont ?
`thermoptic` route désormais l'instance Chrome contrôlée via un service interne `proxyrouter`, afin que vous puissiez pointer Chrome vers des proxies HTTP ou SOCKS en amont (y compris ceux nécessitant des identifiants). Définissez l'URI du proxy en amont en modifiant la valeur `UPSTREAM_PROXY` dans `docker-compose.yml` au niveau du service `proxyrouter`. Si vous la laissez vide, Chrome communique directement avec Internet via le proxy non authentifié du cluster.
Exemple de configuration d'un proxy SOCKS en amont :```yaml
proxyrouter:
environment:
UPSTREAM_PROXY: "socks5://username:[email protected]:1080"
Be aware that some upstream proxies can change low-level fingerprints (for example, TCP metadata) which may reduce parity with a residential browser.
thermoptic chargera le navigateur avec les cookies que votre client spécifie dans l'en-tête Cookie. La requête inclura ensuite ces cookies une fois exécutée dans le contexte du navigateur. Cela garantit que le serveur ne peut pas identifier l'ordre des cookies ni utiliser d'autres astuces bon marché de ce genre.
NOTE : ces cookies resteront également après la requête. Si vous souhaitez implémenter une logique de nettoyage des cookies, veuillez écrire un hook thermoptic.
Oui, thermoptic prend en charge une utilisation hybride de ce type, voir cette section pour plus d'informations.
Vous devez vous assurer de définir correctement des en-têtes comme X-Fetch-*, Origin et Referer. Si vous ne signalez pas ces en-têtes à thermoptic, il ne pourra pas exécuter la requête de manière suffisamment furtive.
Sans définition des en-têtes contextuels, thermoptic définira des valeurs par défaut qui peuvent ne pas refléter exactement ce que votre site cible attend. Par exemple, si vous ne définissez pas d'en-tête Origin, il définira une Origin à null ; si vous ne définissez pas d'en-tête Referer, il n'enverra tout simplement pas de Referer.
Il est de votre intérêt d'inclure ces en-têtes contextuels pour que votre requête soit aussi furtive que possible ! thermoptic ne peut pas lire dans vos pensées, il ne peut lire que votre requête :).
En règle générale, cela ne s'applique que dans le cas des hooks thermoptic qui utilisent temporairement le navigateur web complet pour passer les vérifications JavaScript/navigateur. Lorsque vous utilisez temporairement ces hooks et le mode navigateur complet, vous devez veiller à ne pas être identifié comme un bot (par exemple, évitez des pièges comme Runtime.enable).
Les considérations éthiques et la théorie des jeux complexe en jeu ici sont trop vastes pour être traitées dans un README. N'hésitez cependant pas à contester l'un de ces points trop simplifiés lorsque vous me flamez par e-mail/Twitter/Github :
Pour de plus amples discussions sur la course aux armements du scraping, je vous demande au moins de m'offrir une bière d'abord. Pour être honnête, je déteste écrire ces ennuyeux essais éthiques dans mes READMEs, alors n'hésitez pas à m'imaginer comme un nerd maléfique qui veut vous rendre la vie plus difficile.
thermopticthermoptic vous permet de configurer des scripts personnalisés afin d'effectuer des actions dans le navigateur lorsque :
ON_START_HOOK_FILE_PATH)BEFORE_REQUEST_HOOK_FILE_PATH)AFTER_REQUEST_HOOK_FILE_PATH)Cela vous permet d'utiliser le protocole de débogage Chrome pour cliquer et définir les cookies appropriés pour les sites qui exigent un véritable navigateur web pour une étape de vérification. Vous pouvez ensuite utiliser le proxy thermoptic pour poursuivre votre session masquée à travers le même navigateur.
Pour ce faire, modifiez le fichier JavaScript de hook approprié avec votre code personnalisé pour orchestrer le navigateur comme il se doit via l'interface chrome-remote-interface fournie :```
// 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!);
}
Pour un exemple d'implémentation, voir le fichier [`./hooks/onstart.js`](https://github.com/mandatoryprogrammer/thermoptic/blob/main/hooks/onstart.js) qui [contourne le CAPTCHA turnstile de Cloudflare](https://github.com/mandatoryprogrammer/thermoptic/blob/main/tutorials/turnstile/cloudflare-turnstile-bypass.md) (ainsi que d'autres vérifications anti-bot de Cloudflare).
## Contrôler le navigateur Chrome dockerisé via l'interface web (Xpra)
`thermoptic` est fourni avec l'interface web Xpra, disponible à l'adresse `http://127.0.0.1:14111`. Cela vous permet de contrôler facilement le navigateur Chrome dockerisé manuellement :
<img src="https://assets.kitploit.com/production/public/readmes/49068/0fa1b187f46405dda2b0db5d461619daa6a7bdad2c385cb51994e870d9054d10.png" width="100%">
Ceci est utile pour des choses telles que :
* Vous connecter à votre compte afin de pouvoir effectuer des requêtes authentifiées via `thermoptic` en utilisant votre client HTTP préféré comme `curl`.
* Par exemple, si vous vous connectez à `reddit.com` avec le navigateur, toutes les requêtes que vous envoyez à Reddit via `thermoptic` seront automatiquement authentifiées avec votre compte Reddit !
* Déboguer vos hooks `thermoptic` personnalisés et vérifier les problèmes liés aux sites web.
## Configuration
Ces variables d'environnement spécifient comment `thermoptic` doit être configuré lors de son exécution.
`HTTP_PROXY_PORT` : Le port sur lequel le proxy `thermoptic` doit écouter. Si vous exécutez `thermoptic` dans Docker, vous devrez également modifier le champ de mappage `ports` pour qu'il corresponde.
`CHROME_DEBUGGING_PORT` : Le port sur lequel le protocole de débogage Chrome est exposé. Ce port est spécifié lorsque vous lancez Chrome/Chromium avec l'option `--remote-debugging-port` définie sur une valeur telle que `9222`.
`CHROME_DEBUGGING_HOST` : L'hôte sur lequel le protocole de débogage Chrome est exposé. Il s'agit souvent de `127.0.0.1` si le navigateur est lancé localement et que `thermoptic` n'est pas exécuté dans Docker. S'il est exécuté dans Docker, vous devrez peut-être utiliser `host.docker.internal`, voir la [documentation Docker](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host) pour plus d'informations.
`PORT` : Le port CDP que le conteneur Chrome publie vers le reste de la pile. Gardez-le aligné avec `CHROME_DEBUGGING_PORT` pour que le pont `socat` continue de fonctionner comme prévu.
`CHROME_CONTROL_PORT` : Le port du service de contrôle de Chrome que thermoptic utilise pour gérer le navigateur (par exemple, pour envoyer des demandes de redémarrage).
`CHROME_CONTROL_COOLDOWN_MS` : Temps minimum en millisecondes entre les tentatives de redémarrage de Chrome. Utilisez-le pour éviter les boucles de redémarrage rapides lorsque plusieurs échecs se produisent en succession rapide.
`ENABLE_GUI_CONTROL` : Définissez sur `true` pour lancer le panneau web xpra afin de pouvoir piloter le Chrome dockerisé en visitant `http://127.0.0.1:14111`. Désactivez-le pour les exécutions sans interface graphique uniquement.
`CHROME_SCREEN_WIDTH` / `CHROME_SCREEN_HEIGHT` : Les dimensions en pixels de l'affichage Chrome headful dockerisé.
`CHROME_ENABLE_GPU` : Contrôle si le conteneur Chrome fourni doit tenter d'utiliser l'accélération GPU de l'hôte. `auto` (par défaut) active le chemin NVIDIA/Vulkan lorsque le runtime et les nœuds de périphérique requis sont présents, sinon il revient au rendu logiciel. Définissez-le sur `false` pour forcer l'ancien comportement logiciel uniquement.
`CHROME_PROFILE_RECOVERY` : Lorsqu'il est défini sur `true` (par défaut), le lanceur Chrome fourni effectuera une tentative de récupération si Chrome meurt immédiatement avec le même code de sortie de boucle de crash observé dans un profil empoisonné (`133`). Le contenu du mauvais profil est déplacé sous `/tmp/chrome-profile-recovery/` dans le conteneur avant de réessayer avec un profil propre.
`PROXY_USERNAME` : Le nom d'utilisateur utilisé pour vous authentifier auprès du proxy, la valeur par défaut est `changeme`. S'il n'est pas défini, le proxy fonctionne sans exiger d'authentification.
`PROXY_PASSWORD` : Le mot de passe utilisé pour vous authentifier auprès du proxy, la valeur par défaut est `changeme`. S'il n'est pas défini, le proxy fonctionne sans exiger d'authentification.
`THERMOPTIC_CONTAINER_RUNTIME` : Indique que thermoptic s'exécute dans le conteneur fourni. Laissez cette valeur sur `true` ; elle contrôle des comportements comme les vérifications de santé intégrées qui n'ont de sens que dans l'installation Docker complète.
`HEALTHCHECK_ENDPOINT_PORT` : Le port sur lequel thermoptic expose son point de terminaison web de vérification de santé. Le worker de santé l'appelle via le proxy ; s'il cesse de répondre, Chrome est automatiquement redémarré pour débloquer les sessions figées.
`HEALTHCHECK_ENDPOINT_PATH` : Le chemin HTTP servi par le point de terminaison de vérification de santé décrit ci-dessus. Modifiez-le si vous avez besoin d'une URL différente.
`ON_START_HOOK_FILE_PATH` : Code Node personnalisé à exécuter au démarrage du proxy. Le proxy ne commencera pas à écouter tant que ce hook n'est pas terminé, voir l'exemple dans `./hooks/`. L'exemple montre comment utiliser le navigateur pour cliquer à travers la vérification JavaScript de Cloudflare avant de démarrer le proxy.
`BEFORE_REQUEST_HOOK_FILE_PATH` : Code Node personnalisé à exécuter avant qu'une requête ne soit proxifiée. Ceci est utile si vous avez besoin que le navigateur réussisse une vérification avant qu'une requête HTTP de site ne soit effectuée.
`AFTER_REQUEST_HOOK_FILE_PATH` : Code Node personnalisé à exécuter après qu'une requête a été proxifiée. C'est souvent utile pour faire des choses comme nettoyer les cookies qui ont été définis par le client via l'en-tête `Cookie`.
`DEBUG` : Définissez sur `true` lorsque vous rencontrez un bug afin que thermoptic imprime des diagnostics verbeux avant que vous ne signaliez un problème ; laissez-le sur `false` en fonctionnement normal.
## Sécurité
Notez qu'à l'heure actuelle, `thermoptic` est uniquement destiné à être utilisé avec des clients HTTP en qui vous avez explicitement confiance. Il n'est *pas* destiné à être exposé à des utilisateurs non fiables.
Pour toute vulnérabilité de sécurité, veuillez envoyer un rapport à l'adresse `mandatory@` Gmail.