mandatoryprogrammer/thermopticスタックの全レイヤーにわたってリクエストをChromeブラウザとして完全に偽装する、次世代のHTTPステルスプロキシ。
"信じられない、光学迷彩だ！"
これは、JA4+ などのフィンガープリンティングを使用して特定のHTTPクライアントをブロックするサービスを迂回するために設計されたHTTPプロキシです。このプロキシを使用すると、curl のようなお好みのHTTPクライアントを使用しても、実際の（Chrome/Chromium）Webブラウザと魔法のように見分けがつかないフィンガープリントを得ることができます。thermoptic には、JavaScriptベースのフィンガープリンティングを緩和するための楽しい機能も用意されています。また、Webブラウザと低レベルHTTPクライアントを一緒に使ったハイブリッドスクレイピングを簡単に行うこともできます。
JA4+ フィンガープリンティングに詳しくなくても、スクレイピングをしたことがあれば、おそらくこれまでに一度はブロックされたことがあるでしょう。Cloudflare などの人気サービスは、こうした技術（および他のトリック）を使用して、「人間以外の」HTTPクライアントの使用を検出し、リクエストをブロックしています。これらのサービスは、このフィンガープリンティングを使用して、実際のブラウザでセッションを開始し、後で curl のような低レベルクライアントに切り替えたことを検出することもできます。thermoptic は、すべてのスクレイピングリクエストに対して統一された「本物の」ブラウザフィンガープリントを提示することで、これらの問題をすべて解決します。
以下は、プロキシを使用しない curl のJA4H（HTTP）フィンガープリントの例です。```
$ curl https://ja4db.com/id/ja4h/
ge11nn090000_b6a016211e8a_000000000000_e3b0c44298fc
これは、URLに直接アクセスしたときにChromeが生成するフィンガープリントとはかなり異なります：```
ge11cn19enus_f2808f0d04cf_9a10d4221160_7068f58def6e
しかし、プロキシを使用してリクエストを送信すると、私たちのJA4Hフィンガープリントは魔法のように同一になります:``` $ curl --proxy http://thermoptic:1234 https://ja4db.com/id/ja4h/ ge11cn19enus_f2808f0d04cf_9a10d4221160_7068f58def6e
（JA4 TLS フィンガープリントも同様、など）。
## セットアップ
Ubuntu 22.04 上のコンテナ化された Chrome インスタンスを介してトラフィックを偽装する `thermoptic` プロキシを起動するには：
通常の Docker セットアップ（GPU ランタイムのないホストで動作）：```
docker compose up --build
以上です。これでトラフィックをプロキシ経由で通すことができます：``` curl --proxy http://127.0.0.1:1234 --insecure https://ja4db.com/id/ja4h/
Important notes:
* デフォルトでは、プロキシは認証なしで動作します。プロキシを外部に公開する予定がある場合は、環境変数 `PROXY_USERNAME` と `PROXY_PASSWORD` で認証を設定してください。
* `---insecure` を使用したくない場合は、`./ssl/rootCA.crt` にある生成された CA ファイルを使用する必要があります。これは初めて `thermoptic` を実行したときに生成されます。
* `thermoptic` は、`--remote-debugging-port` フラグを付けて起動した任意の Chrome/Chromium インスタンスに接続できます。フィンガープリントをできるだけ目立たなくするには、より一般的に使用される環境（例: Windows 上の Chrome）を経由してセットアップおよびプロキシする必要があるため、これは不可欠です。
* GPU compose オーバーライドは、Docker の NVIDIA ランタイム/ツールキットがすでにインストールされている NVIDIA ホストを対象としています。GPU デバイスを予約し、`/dev/dri` をマウントし、同梱の Chrome コンテナが NVIDIA/Vulkan レンダリングパスに切り替えられるようにします。これを使用するには、`docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build` を実行します。
## 特徴
- 🕵️ [ブラウザ同等のプロキシ](#how-does-this-cloaking-work-exactly) - 実際の Chrome セッションを通じてリクエストを再生し、JA4 フィンガープリントをバイト単位で一致させます。
- 🤝 HTTP クライアント（例: `curl`、`requests` など）を `thermoptic` に統合するのにカスタムコードはほとんど、またはまったく必要ありません。[プロキシを設定](#setup)するだけで、フィンガープリントは自動的に処理されます。
- 🪝 [フックフレームワーク](#handling-browser-javascript-fingerprinting-with-thermoptic-hooks) - before-request / after-request / on-start の自動化に対応し、フルブラウザを操作してチャレンジを解決したり、アーティファクトを取得したりできます。
- 📘 Cloudflare Turnstile 解決フックの例は [`./hooks/onstart.js`](https://github.com/mandatoryprogrammer/thermoptic/blob/main/hooks/onstart.js) にあります。
- 🖥️ [Web ブラウザ制御 UI](#control-the-dockerized-chrome-browser-via-web-ui-xpra)（`http://127.0.0.1:14111`）で、Docker 化された Chrome ブラウザウィンドウを制御できます。サイトに手動でログインし、そのログイン済みセッションとしてシームレスにプロキシ経由でリクエストを送信するのに便利です（デバッグにも役立ちます）。
- 🔌 `docker-compose.yml` の `UPSTREAM_PROXY` 環境変数を使用して、アップストリームの HTTP または SOCKS プロキシ URI を設定します。
- 🛡️ 内蔵のヘルスチェックと再起動制御ループにより、ブラウザのフリーズを検出して、オペレータの常時監視なしに自動的に復旧します。
- ⚡ HTTP/1.1 および HTTP/2 に対応し、どちらのプロトコルでもトラフィックをプロキシできます。（_プロキシに対しては HTTP/1.1 で通信し、操作されている Chrome が最終サイトとは別のプロトコルでネゴシエートする場合があることに注意してください。_）
## このクローキングは正確にはどのように機能しますか？
* `thermoptic` をプロキシとして設定した `curl` などの HTTP クライアントを使用して HTTP リクエストが行われます。
* `thermoptic` はリクエストを分析し、それが*本来*どのようなブラウザリクエストであるかを最適に判断します（例: 手動の URL アクセス？ フォーム送信？ `fetch()` リクエスト？）。
* `thermoptic` は [Chrome Debugging Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/) を使用してブラウザを操作し、実際の Web ブラウザで通常発生するのとまったく同じようにリクエストを模擬するページをセットアップします。
* `thermoptic` はモックされたコンテキストを介してリクエストをトリガーし、HTTP レスポンスをキャプチャします。
* `thermoptic` は HTTP レスポンスをクライアントに返します。
ブラウザが実際にフルスタックを使用してリクエストを行っているため、結果として得られる JA4 フィンガープリントは同一になります。
注: 多くの WAF が Web ブラウザの JavaScript レベルのフィンガープリンティングを採用しているため、`thermoptic` はスクレイピングプロセスの重要なステップでブラウザを利用するためのフックも公開しています。詳細については[このセクション](#handling-browser-javascript-fingerprinting-with-thermoptic-hooks)を参照してください。
## なぜ*この*アプローチが他のソリューションより優れているのか？
率直に言うと、他のアプローチには、ブラウザフィンガープリンティング問題に対する実用的な長期的解決策となることを妨げる根本的な欠陥があります。
ブラウザの JA4+ フィンガープリンティングを「打ち負かす」試みの多くは、ブラウザスタックのさまざまなレイヤーを再実装することで実現しています。このアプローチには、次のようないくつかの深刻な欠点があります。
* 「実際の」ブラウザ実装の動作を完全に一致させるために細心の注意が必要です。その結果、*あらゆる*癖や相違点を利用して、これらのクライアントを「実際の」ブラウザ実装と区別することができます。
* スタックの 1 つのレイヤーだけで問題を解決しようとすること。Chrome は Web ブラウジング体験を提供するために複数のプロトコルを利用します。そのため、完全に一致する TLS レイヤーを作成したとしても、HTTP レイヤーがバイト単位で完璧でなければ、身元が明らかになる可能性があります。
* 「実際の」ブラウザは定期的に動作を変更するため、フィンガープリントも変化し、その結果、これらのツールは補正のためにより集中的な開発作業を常に必要とします。
対照的に、`thermoptic` は HTTP リクエストを実行するためにブラウザ自体を使用するため、次のようになります。
* TCP、TLS、HTTP などのスタックの各レイヤーは、リクエストが*通常*発生する方法で実際のブラウザを*使用*して行われるため、実際のブラウザと区別がつきません。
* さまざまなレイヤーでのブラウザ動作の変更による影響は最小限で、`thermoptic` が制御するブラウザを更新するだけで最新のフィンガープリントセットに一致させることができます。
もちろん、欠点のないソリューションはありません。`thermoptic` アプローチの欠点の詳細なリストについては、`DOWNSIDES.md` ドキュメントを参照してください。
## FAQ
### なぜ `thermoptic` という名前なのですか？
「Thermoptic」（「thermoptic camouflage（熱光学迷彩）」の略）は、[攻殻機動隊（1995）のアニメで少佐が使用した架空の迷彩](https://ghostintheshell.fandom.com/wiki/Thermoptic_camouflage)に由来しています。この映画では、この迷彩は可視光と熱放射の両方を含む複数の検出スペクトルにわたって装着者を隠すことができると示されています。同様に、このツールは複数のチャネル（HTTP、TLS など）にわたるフィンガープリンティングからユーザーをクロークしようと試みます。
### JA4+ はフィンガープリントの**スイート**です！ どのフィンガープリントを偽装しますか？
このツールは、接続している Chrome/Chromium ブラウザと完全に同じになるように、次の JA4 フィンガープリントを偽装します。
* JA4（TLS フィンガープリント）
* JA4H（HTTP フィンガープリント）
* JA4X（X509 TLS 証明書フィンガープリント）
* JA4T（TCP フィンガープリント）
### これと一緒に別のアップストリーム HTTP/SOCKS プロキシを使用したい場合はどうすればよいですか？
`thermoptic` は現在、制御対象の Chrome インスタンスを内部の `proxyrouter` サービス経由でルーティングするため、Chrome をアップストリームの HTTP または SOCKS プロキシ（認証情報を必要とするものも含む）に向けることができます。`docker-compose.yml` の `proxyrouter` サービスの下にある `UPSTREAM_PROXY` 値を編集して、アップストリームプロキシ URI を設定します。この値を空のままにすると、Chrome は認証なしのクラスタ内プロキシを通じてインターネットに直接通信します。
アップストリーム SOCKS プロキシを設定する例：```yaml
proxyrouter:
environment:
UPSTREAM_PROXY: "socks5://username:[email protected]:1080"
一部の上流プロキシは、低レベルのフィンガープリント（例: TCP メタデータ）を変更し、一般家庭のブラウザとの同等性を低下させる可能性があることに注意してください。
thermoptic は、クライアントが Cookie ヘッダーで指定した Cookie をブラウザに読み込みます。リクエストはブラウザコンテキストで実行されると、この Cookie を含むことになります。これは、サーバーが Cookie の並び順やその他の安易なトリックでフィンガープリントできないようにするためです。
注: これらの Cookie はリクエスト後も残ります。Cookie のクリーンアップロジックを実装したい場合は、thermoptic フックを記述してください。
はい、thermoptic はこのようなハイブリッドな使用法をサポートしています。詳細はこのセクションを参照してください。
X-Fetch-*、Origin、Referer などのヘッダーを正しく設定する必要があります。thermoptic にこれらのヘッダーを伝えないと、適切にステルスな方法でリクエストを実行できません。
コンテキストヘッダーを設定しない場合、thermoptic はデフォルト値を設定しますが、対象サイトが期待する内容と正確に一致しない場合があります。たとえば、Origin ヘッダーを設定しないと Origin は null になり、Referer ヘッダーを設定しないと Referer は一切送信されません。
リクエストを可能な限りステルスにするには、これらのコンテキストヘッダーを含めることが最善です！ thermoptic はあなたの心を読むことはできません。読めるのはあなたのリクエストだけです :)。
一般に、これは JavaScript/ブラウザレベルのチェックを通過するために一時的に完全な Web ブラウザを利用する thermoptic フックの場合にのみ当てはまります。これらのフックとフルブラウザモードを一時的に使用する場合は、ボットとしてフィンガープリントされないように注意する必要があります（例: Runtime.enable のような落とし穴を避ける）。
ここで働く倫理的考察と複雑なゲーム理論は、README で答えられる範囲を超えています。メール/Twitter/GitHub で私を批判するときは、これらの過度に単純化された論点のいずれかに反論してください。
スクレイピングの軍拡競争についてもっと語り合いたいなら、まず最低でもビールを一杯ごちそうしてください。正直なところ、私は README にこうした退屈な倫理エッセイを書くのが嫌いなので、あなたの生活を困難にしようとしている邪悪なオタクだと自由に想像してくれて構いません。
thermoptic フックによるブラウザの JavaScript フィンガープリンティングへの対処thermoptic を使用すると、以下のタイミングでブラウザアクションを実行するカスタムスクリプトを設定できます。
ON_START_HOOK_FILE_PATH）BEFORE_REQUEST_HOOK_FILE_PATH）AFTER_REQUEST_HOOK_FILE_PATH）これにより、Chrome Debugging Protocol を使用して、検証ステップに実際の Web ブラウザを必要とするサイトのために、クリック操作を行い、適切な Cookie を設定できます。その後、thermoptic プロキシを使用して、同じブラウザを通してセッションを隠したまま続行できます。
これを行うには、適切なフック JavaScript ファイルをカスタムコードで変更し、提供されている chrome-remote-interface インターフェースを介してブラウザを適切に操作します。```
// 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!);
}
実装例については、[Cloudflare turnstile CAPTCHAをバイパスする](https://github.com/mandatoryprogrammer/thermoptic/blob/main/tutorials/turnstile/cloudflare-turnstile-bypass.md)（およびその他のCloudflareアンチボットチェックを回避する）[`./hooks/onstart.js`](https://github.com/mandatoryprogrammer/thermoptic/blob/main/hooks/onstart.js) ファイルを参照してください。
## Web UI（Xpra）によるDocker化されたChromeブラウザの操作
`thermoptic` にはXpra Web UIが同梱されており、`http://127.0.0.1:14111` で利用できます。これにより、Docker化されたChromeブラウザを手動で簡単に操作できます。
<img src="https://assets.kitploit.com/production/public/readmes/49068/0fa1b187f46405dda2b0db5d461619daa6a7bdad2c385cb51994e870d9054d10.png" width="100%">
これは次のような場合に役立ちます：
* `curl` などの任意のHTTPクライアントを使って `thermoptic` 経由で認証付きリクエストを送信できるように、アカウントにログインすること。
* たとえばブラウザで `reddit.com` にログインすると、`thermoptic` 経由でRedditに送信するすべてのリクエストが自動的にあなたのRedditアカウントとして認証されます！
* カスタム `thermoptic` フックのデバッグや、Webサイトの問題の確認。
## 設定
次の環境変数は、`thermoptic` の実行時の設定方法を指定します。
`HTTP_PROXY_PORT`: `thermoptic` プロキシがリッスンするポート。Dockerで `thermoptic` を実行している場合は、`ports` マッピングフィールドもこれに合わせて変更する必要があります。
`CHROME_DEBUGGING_PORT`: Chromeデバッグプロトコルが公開されるポート。このポートは、`--remote-debugging-port` フラグを `9222` などの値に設定してChrome/Chromiumを起動するときに指定します。
`CHROME_DEBUGGING_HOST`: Chromeデバッグプロトコルが公開されるホスト。ブラウザがローカルで起動され、`thermoptic` がDockerで実行されていない場合は、通常 `127.0.0.1` です。Dockerで実行している場合は `host.docker.internal` を使用する必要があるかもしれません。詳細は[Dockerドキュメント](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host)を参照してください。
`PORT`: Chromeコンテナがスタックの他の部分に公開するCDPポート。`socat` ブリッジが期待どおり動作し続けるように、`CHROME_DEBUGGING_PORT` と揃えてください。
`CHROME_CONTROL_PORT`: thermoptic がブラウザを管理するために使用するChromeのコントロールサービスポート（たとえば、再起動リクエストの送信）。
`CHROME_CONTROL_COOLDOWN_MS`: Chromeの再起動試行間の最小時間（ミリ秒）。複数の障害が連続して発生したときに、急速な再起動ループを避けるために使用します。
`ENABLE_GUI_CONTROL`: `true` に設定するとxpraウェブパネルが起動し、`http://127.0.0.1:14111` にアクセスしてコンテナ化されたChromeを操作できます。ヘッドレス専用の実行では無効にしてください。
`CHROME_SCREEN_WIDTH` / `CHROME_SCREEN_HEIGHT`: Docker化されたヘッドフルChromeディスプレイのピクセル寸法。
`CHROME_ENABLE_GPU`: 同梱のChromeコンテナがホストGPUアクセラレーションを使用しようとするかどうかを制御します。`auto`（デフォルト）は、必要なランタイムとデバイスノードが存在する場合にNVIDIA/Vulkanパスを有効にし、それ以外の場合はソフトウェアレンダリングにフォールバックします。`false` に設定すると、以前のソフトウェアのみの動作に強制します。
`CHROME_PROFILE_RECOVERY`: `true`（デフォルト）の場合、同梱のChromeランチャーは、破損したプロファイルで観測されたクラッシュループ終了コード（`133`）と同じコードでChromeがすぐに終了したときに、1回の回復試行を行います。クリーンなプロファイルで再試行する前に、不良プロファイルの内容はコンテナ内の `/tmp/chrome-profile-recovery/` の下に移動されます。
`PROXY_USERNAME`: プロキシに対する認証に使用されるユーザー名。デフォルトは `changeme` です。未設定の場合は、プロキシは認証を必要とせずに実行されます。
`PROXY_PASSWORD`: プロキシに対する認証に使用されるパスワード。デフォルトは `changeme` です。未設定の場合は、プロキシは認証を必要とせずに実行されます。
`THERMOPTIC_CONTAINER_RUNTIME`: thermoptic が同梱コンテナ内で実行されていることを示します。これは `true` のままにしてください。完全なDockerセットアップでのみ意味を持つ組み込みヘルスチェックなどの動作を制御します。
`HEALTHCHECK_ENDPOINT_PORT`: thermoptic がヘルスチェックWebエンドポイントを公開するポート。ヘルスワーカーはこれをプロキシ経由で呼び出します。応答が停止した場合、Chromeは自動的に再起動され、フリーズしたセッションを解消します。
`HEALTHCHECK_ENDPOINT_PATH`: 上記のヘルスチェックエンドポイントが提供するHTTPパス。異なるURLが必要な場合は変更してください。
`ON_START_HOOK_FILE_PATH`: プロキシ起動時に実行するカスタムNodeコード。このフックが完了するまでプロキシはリッスンを開始しません。例は `./hooks/` を参照してください。サンプルは、プロキシを起動する前にブラウザを使用してCloudflareのJavaScriptブラウザチェックをクリックして通過する方法を示しています。
`BEFORE_REQUEST_HOOK_FILE_PATH`: リクエストがプロキシされる前に実行するカスタムNodeコード。サイトへのHTTPリクエストが行われる前にブラウザに何らかのチェックを通過させる必要がある場合に便利です。
`AFTER_REQUEST_HOOK_FILE_PATH`: リクエストがプロキシされた後に実行するカスタムNodeコード。多くの場合、`Cookie` ヘッダーを介してクライアントによって設定されたCookieをクリーンアップするなどの処理に役立ちます。
`DEBUG`: バグに遭遇したときに `true` に設定すると、issueを報告する前に thermoptic が詳細な診断情報を出力します。通常の運用中は `false` のままにしてください。
## セキュリティ
現時点では、`thermoptic` は明示的に信頼するHTTPクライアントでのみ使用することを想定していることに注意してください。信頼できないユーザーに公開することを意図したものでは*ありません*。
セキュリティの脆弱性については、`mandatory@` Gmailまでご報告ください。