docs

結論：TLS 終端の位置で決まる

[Client] ──TLS handshake──▶ [ ここで ClientHello を見た者だけが JA4 を計算できる ]

JA4 を計算するには 生の ClientHello バイト列が必要です。TLS を復号した後の平文 HTTP しか見ていないプロセスは、後から JA4 を組み立てられません。

構成パターン別の JA4 可否

JA4 を計算するには 生の ClientHello バイト列が要るので、可否は TLS をどこで終端するか(= クライアントの ClientHello を最初に見る点)と unmask の置き方(nginx native module / gateway コンテナ)だけで決まります。後段のアプリは無関係です。

● = unmask インストールノード　★ = TLS 終端 (ここで ClientHello を見る)

• native = nginx + unmask-plugin-nginx。C モジュールが ClientHello を直接解析して JA4 を算出 (最速・サブリクエスト無し・CentOS 6 等の古い distro でも動作)。サイトを nginx で配信していて JA4 を使うならこれ。
• gateway コンテナ = unmask.sh/unmask イメージ。公式 nginx イメージ + unmask module と unmask daemon を 1 つのコンテナにまとめたもの。任意の HTTP server (Apache、Node、別の nginx など) の前段で TLS を終端し、native と同じ仕組みで JA4 を算出するので、後ろのサーバーは何も変えなくてよい。→ コンテナで動かす / インストールガイド。
• Apache には unmask の module が無いので、Apache のサイトで JA4 を使うなら前段に gateway コンテナを置く (Apache 向けの推奨構成)。
• ③④ には、クライアントの JA4 をリクエストヘッダーで転送する前段が要る。GCP HTTPS LB は custom request header (X-Client-JA4)、Cloudflare は自前の cf-ja4 ヘッダー (有効化が必要で、プランによる)、AWS CloudFront / ALB は AWS 側の構成で JA4 をヘッダーに載せられる場合に限る。そうしたヘッダーが無ければ、③④ でも JA4 は取れない。
• ③④ では、どちらの置き方でも手順は同じで、管理画面の「信頼する LB / CDN」で前段 (CDN / LB) を選ぶだけ。unmask はその CDN / LB のアドレス範囲から届いた JA4 だけを採用し、それ以外から届いたものは使わない。ヘッダー名は preset 側が持っている (X-Client-JA4、Cloudflare は cf-ja4)。トグルも nginx 側の手作業の配線も不要。手順 → 下の LB / CDN 設定。

HTTP/3 (QUIC) — 先頭が q になる

JA4 の先頭 1 文字は ClientHello が届いたトランスポートを表します： t = TCP 上の TLS、q = QUIC。 nginx プラグインは HTTP/3 でも TCP と同じ仕組みで JA4 を算出します。 --with-http_v3_module 付きでビルドした nginx に listen … quic を設定すれば、QUIC の ClientHello も モジュールが既にフックしている TLS ライブラリの callback を通るため、追加設定は不要です。 nginx の HTTP/3 ビルドで使われる OpenSSL 3.5+ (native QUIC API) と quictls の 両系統で動作を確認済みです。

TCP  (HTTP/1.1, HTTP/2)  →  t13i3514h2_bfa337485184_3ad6d895dd8c
QUIC (HTTP/3)            →  q13i0306h3_55b375c5d22e_1cecd519fee8

• 同じクライアントでも HTTP/3 では別の文字列になります (先頭文字・ALPN・hello の中身がすべて変わるため)。HTTP/3 を配信しているサイトで JA4 のカスタムルールを書くときは、両方の形を対象にしてください。
• 同一訪問者の HTTP/2 ↔ HTTP/3 切替は、unmask の cookie rebinding が正常な遷移として扱います (fingerprint 不一致にはなりません)。
• 前段の CDN / LB が HTTP/3 を終端して JA4 を転送する構成でも、転送値は q 始まりで届き、「信頼する LB / CDN」の gate をそのまま通ります。

JA4 が取れないとどうなる？

JA4 が空でも unmask は動作します。bot 判定は以下のシグナルで続行されます。

• User-Agent 分類 — 600+ パターンのクローラー / bot UA リストで既知 bot を識別
• 公式 IP 範囲 — Googlebot / Bingbot 等の公式範囲を通過リストに登録 (順位事故防止)。範囲を公開する vendor は UA でなく IP で検証し、なりすまし UA を弾く (範囲のないクローラーは UA で通過)
• rate-limit — IP × パス単位の閾値超過で challenge に格上げ
• honeypot — 登録した罠パス (運用していない CMS パス等) を踏んだ訪問者を BAN
• behavioral CAPTCHA — mouseTrail / scroll / keyboard 等 5 軸の人間らしさスコア

まとめ — どの構成を選ぶか

• サイトを nginx で配信している → nginx + unmask-plugin-nginx (native mode)。nginx が TLS を終端していること
• Apache などそれ以外の HTTP server → 前段に gateway コンテナを置く。コンテナが TLS を終端し、JA4 を自分で算出する
• TLS を終端する前段 (CDN / LB) がある → そこからクライアントの JA4 をヘッダーで転送する → 下の LB / CDN 設定

インストール手順は インストールガイド を参照してください。

1. 全体像

[Client] ──TLS──▶ [LB] ──HTTP + X-Client-JA4──▶ [nginx + unmask]
                  ↑                ↑
       ここで JA4 抽出        header から読む

LB / CDN 側の役割:

• ① クライアントの TLS handshake から JA4 fingerprint を計算
• ② backend へ転送するリクエストのヘッダーに値を入れる。慣例は X-Client-JA4 (Cloudflare は自前の cf-ja4 を使い、unmask の Cloudflare preset はそれをそのまま読む)
• ③ クライアントが同じヘッダーを送ってきた場合は、LB 段で必ず上書き (偽装防止)

設定する箇所は 2 つ:

• §2 CDN / LB 側：クライアントの JA4 をリクエストヘッダーに載せる (LB ごとに設定)
• §3 unmask 側：「その LB を信頼する」と管理画面で選ぶ。既定は どの LB も信頼しない安全寄りの設定 なので、明示的に有効化する

3. unmask 側の設定

§2 で前段 (LB / CDN) が JA4 のヘッダーを送るようになったら、unmask 側は「どの送信元を信頼するか」を 1 箇所決めるだけ。native mode と gateway コンテナのどちらでも操作は同じ (管理画面の 設定 → ネットワーク タブ)。

1. 「信頼する LB / CDN」で、使っている LB / CDN (GCP HTTPS LB / Cloudflare / AWS CloudFront 等) にチェックを入れる
2. 一覧に無いもの (自社内部 LB / ALB 等) は custom LB で接続元 CIDR と JA4 ヘッダーを追加する

保存すると、unmask はその送信元から来た JA4 ヘッダーだけを採用し (ヘッダー名は preset 側が持っている。X-Client-JA4、Cloudflare は cf-ja4)、直アクセスの詐称ヘッダーは破棄される。あとは sudo nginx -s reload するだけ (gateway コンテナは自分で reload する)。nginx の server block への JA4 用の追記は不要。これで完了。

仕組み (運用者は意識不要): native は plugin が ClientHello から JA4 を算出し (前段が無くても動く)、信頼する LB のヘッダーが届いたときは生成済みの http.inc がそちらを採用する。gateway コンテナはコンテナ内で同じ仕組み。専用トグルは無い。

4. 動作確認 (admin ダッシュボード)

1. reload 後、ブラウザのプライベートウィンドウで対象のサイトを開く (unmask の通過 cookie をまだ持っていない状態にするため)
2. unmask の管理画面で bot ハントを開き、自分の IP の行を探す。JA4 列に、そのリクエストで unmask が使った fingerprint が出る (t で始まる。HTTP/3 なら q)。記録されるのは challenge を出した訪問で、既定では cookie を持たない初回訪問もこれに含まれる
3. または unmask のホストで sudo unmask stats -kind ja4 -since 1h を実行すると、直近 1 時間に記録された fingerprint が一覧で出る

JA4 列の読み方:

• ブラウザや端末ごとに fingerprint が違う → クライアントの JA4 が届いている ✓
• - (空) → JA4 が unmask に届いていない。LB がヘッダーを送っていないか、§3 で LB / CDN を選んでいない
• NOT_TRUSTED → 信頼するアドレス範囲の外から JA4 のヘッダーが届いた。選んでいる LB / CDN と、その CIDR を確認する
• どのリクエストも同じ fingerprint → LB から nginx への TLS 接続の fingerprint で、クライアントのものではない。ヘッダーが使われていない

verdict 列や、統計ページの「JA4 verdict 分布」カードに出る (none) は、失敗の印ではありません。fingerprint がどの verdict ルールにも一致しなかったという意味で、普通のブラウザはここに入ります。JA4 自体が無いリクエストも含まれるので、判断は JA4 列で行ってください。

native mode でリクエスト単位に見る場合: http.inc は unmask という名前の log format を定義していて、unmask が使った JA4 とその理由を記録する (diag=ok。untrusted_lb_header = 信頼する範囲の外から JA4 のヘッダーが届いた。trusted_no_header = 信頼する LB がヘッダーを送ってこなかった)。既存の access_log 行と同じブロックに、しばらくの間だけ access log を追加する:

access_log /var/log/nginx/unmask-ja4.log unmask;   # 追加したら nginx を reload

sudo tail -f /var/log/nginx/unmask-ja4.log         # 各行に ... ja4=... v=... a=... diag=...