unmask

docs

JA4 の取得方法、LB / CDN 設定、対応 distro、FAQ。

Prometheus メトリクス

admin daemon は Prometheus 形式の metrics endpoint を GET /unmask/metrics で公開します。scraper（30 秒間隔ほどで polling する agent）がこれを取得し、Grafana で可視化します — challenge の量、behavioral score の分布、DB latency など。 Go 標準ライブラリだけで Prometheus テキスト形式を直接出力するので、ランタイム依存は増えません。

公開しないでください。 この endpoint にはその site の bot 圧（例: 「1 日に challenge が 10 万回発動」）が含まれるため、アプリ層でアクセスを絞っています。既定の allowlist は loopback のみ（127.0.0.1 + ::1）で、同 host の scraper なら設定不要で動きます。 リモートの Prometheus から取りたいときは、その scraper の IP / CIDR だけを 設定 → Network の metrics_allow_from に足してください。それ以外のアドレスからの request は 403 になります。Prometheus を使っていなければ無視で構いません（endpoint はありますが、誰も触りません）。

公開しているメトリクス

メトリクス 型 中身
unmask_event_total
{phase, verdict}		 counter 直近 24 時間のイベント数を、challenge の phase と JA4 の verdict で分けたもの。「いま何が challenge されているか」の主要シグナル。
unmask_event_unique_ip gauge 直近 24 時間に、いずれかの phase で観測した送信元 IP のユニーク数。
unmask_verify_score
_bucket{le} / _sum / _count		 histogram /api/verify が出す behavioral score の分布（bucket は 0.1 〜 1.0）。daemon 起動以降をプロセス内で数えます。閾値 0.5 を境に人間と bot がどこに寄るかを見られます。
unmask_db_query_seconds
_sum / _count {op}		 counter daemon 内部の集計クエリの DB latency（sum と count）。DB の健全性をざっくり見る目安。

DB 由来のメトリクス（event_total / unique_ip）は 30 秒キャッシュするので、scrape 間隔を 短くしても DB 負荷は増えません。

scrape 設定

site 経由（推奨）

nginx が /unmask/ をすべて admin daemon に proxy するので、daemon の bind 方式（TCP / unix socket）に 関係なく動きます。Prometheus を host に向け、その IP を metrics_allow_from に足してください: 

# prometheus.yml
scrape_configs:
  - job_name: unmask
    scheme: https
    metrics_path: /unmask/metrics
    static_configs:
      - targets: ['your-host']
同 host（既定・allowlist 変更不要）

Prometheus を unmask と同じ host で動かし、daemon が TCP bind（既定 bind: 127.0.0.1）なら、loopback を 直接 scrape できます — 既定の allowlist がそのまま許可します: 

metrics_path: /unmask/metrics
static_configs:
  - targets: ['127.0.0.1:<admin-port>']   # daemon の bind port

死活監視

単純な死活監視（uptime monitor、load balancer の health check、コンテナ orchestrator）には、認証なしの health endpoint を使ってください。200 と本文 ok を返すだけで、stats は一切出しません: 

curl -sf https://your-host/unmask/healthz   # -> ok

healthz は何も明かさないからこそ、あえて allowlist なしで開けています。stats は /unmask/metrics とその allowlist の裏に置いています。