impersonate-proxy

English | 日本語 | 简体中文

TLSフィンガープリント(JA3/JA4)、HTTP/2フィンガープリント、HTTPヘッダーの順序、User-Agent、送信元IPヘッダーを、単一のYAML設定ファイルから制御できるローカルMITMプロキシです。

プロキシを再起動せずにブラウザのツールバーから直接プロキシのON/OFF切り替えやフィンガープリントプロファイルの変更ができる Chrome拡張機能 も同梱しています。

WAFのボット検知システムに対する 許可されたセキュリティテスト を目的としています。curl・ブラウザ・Playwrightのトラフィックをこのプロキシ経由にすることで、フィンガープリントの組み合わせごとにどう判定されるかを観察できます。

仕組み

curl / browser / Playwright
        │  HTTP CONNECT (to proxy)
        ▼
┌─────────────────────────────────────────┐
│            impersonate-proxy            │
│                                         │
│  MITM TLS ◄──────────────► uTLS         │
│  (our CA cert)          (custom JA3/4)  │
│                                         │
│  Header rewriter (UA, order, add/del)   │
│  HTTP/2 framer  (SETTINGS, WINDOW_UPDATE│
│                  pseudo-header order)   │
└─────────────────────────────────────────┘
        │  Custom TLS ClientHello + HTTP/2
        ▼
   Target server / WAF

レイヤー	制御できる項目
TLS	uTLSのプリセット、または完全にカスタムな custom_hello 指定により、暗号スイート・拡張とその順序(JA3 / JA4)を制御
HTTP/1.1	ヘッダーの順序、User-Agent、任意ヘッダーの追加/削除、IPスプーフィング(X-Forwarded-For / True-Client-IP)
HTTP/2	SETTINGSの値と順序、WINDOW_UPDATE、疑似ヘッダーの順序(HTTP/2フィンガープリント)

前提条件

• macOS または Linux(amd64 / arm64)
• Go 1.22+

macOS

brew install go

Linux

ディストリビューション同梱のGoは古いことが多いため、公式バイナリを直接インストールしてください:

# ダウンロードして展開(1.22.5は https://go.dev/dl/ の最新版に置き換えてください)
curl -OL https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz

# PATHに追加(恒久化するには ~/.bashrc または ~/.zshrc にこの行を追記)
export PATH=$PATH:/usr/local/go/bin

確認:

go version
# go version go1.22.5 linux/amd64

ARM64(Raspberry Pi、AWS Gravitonなど): ダウンロードURL内の linux-amd64 を linux-arm64 に置き換えてください。

Docker(Goツールチェーン不要)

Goをインストールせず使い捨て環境で試したい場合は、Dockerセクションへ直接進んでください。

セットアップ

1. クローンとビルド

git clone https://github.com/ytkoka/impersonate-proxy.git
cd impersonate-proxy
make build

2. MITM CA証明書の生成

CAは初回起動時に自動生成されます。一度プロキシを起動して ca.crt と ca.key を作成してください:

make run
# 2026/04/22 12:00:00 generated CA certificate → ca.crt
# 2026/04/22 12:00:00 listening on 127.0.0.1:8080  preset=chrome

Ctrl-C で停止します。

3. CA証明書を信頼する

プロキシが生成するリーフ証明書をクライアントが拒否しないよう、MITM CAを信頼させる必要があります。

macOSシステムキーチェーン(全アプリに影響):

make trust-ca        # runs: sudo security add-trusted-cert ...

Linuxシステムのトラストストア(全アプリに影響。ca-certificatesパッケージが必要):

# Debian / Ubuntu
sudo cp ca.crt /usr/local/share/ca-certificates/impersonate-proxy.crt
sudo update-ca-certificates

# RHEL / Fedora / Amazon Linux
sudo cp ca.crt /etc/pki/ca-trust/source/anchors/impersonate-proxy.crt
sudo update-ca-trust

curlのみ(システム全体には影響しない):

curl --cacert ca.crt ...

Playwright / Node.js:

export NODE_EXTRA_CA_CERTS="$(pwd)/ca.crt"

Firefox: 設定 → プライバシーとセキュリティ → 証明書を表示 → 認証局 → ca.crt をインポート

Docker

コンテナ内でプロキシを実行できます。ローカルにGo/Makeをインストールする必要はありません。

1. プロキシを起動する

Linux環境限定の注意: コンテナは非特権ユーザー(nonroot、UID 65532)で動作し、CA証明書/鍵を保存する ./data ディレクトリへの書き込み権限が必要です。./data が存在しない状態で初回起動すると、Dockerが自動作成するディレクトリの所有者は root になり他ユーザーからは書き込めないため、CA証明書の生成に失敗します。事前に正しい所有者で作成しておいてください:

mkdir -p data && sudo chown 65532:65532 data

Docker Desktop for Mac/Windowsでは、バインドマウント層が所有権を自動的にマッピングするため不要です。

git clone https://github.com/ytkoka/impersonate-proxy.git
cd impersonate-proxy
docker compose up -d

イメージをローカルでビルドしてコンテナを起動します。初回起動時にMITM CAが生成され、以下のように出力されます:

impersonate-proxy  | generated CA certificate → /data/ca.crt (add to OS trust store to avoid cert errors)
impersonate-proxy  | listening on 0.0.0.0:8080  preset=chrome

クローンせずビルド済みイメージを直接使う場合:

docker run -d --name impersonate-proxy \
  -p 127.0.0.1:8080:8080 -p 127.0.0.1:8081:8081 \
  -v "$(pwd)/config.docker.yaml:/config.yaml:ro" \
  -v "$(pwd)/data:/data" \
  ghcr.io/ytkoka/impersonate-proxy:latest

docker-compose.yml は両ポートとも 127.0.0.1 にのみ公開します — ネイティブインストール時と同じループバック限定の露出範囲です(管理APIは無認証のため、独自のアクセス制御を追加しない限り 0.0.0.0 には変更しないでください)。

2. CA証明書を信頼する

CAはコンテナ内で生成されますが、ボリュームマウント経由でホストの ./data/ca.crt と ./data/ca.key に永続化されるため、コンテナの再起動・再作成をまたいで保持されます。上記のネイティブセットアップと同じ手順で、./ca.crt の代わりに ./data/ca.crt を指定してください:

# curl
curl --proxy http://127.0.0.1:8080 --cacert ./data/ca.crt https://tls.peet.ws/api/all

# macOSシステムキーチェーン
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./data/ca.crt

3. 設定する

config.yaml ではなく config.docker.yaml(Docker用)を編集し、再起動してください:

docker compose restart

config.docker.yaml は config.yaml とほぼ同一ですが、listen/mgmt_listen が 0.0.0.0 になっている点(Dockerのポート公開がプロセスに到達するために必須 — コンテナ自身の 127.0.0.1 はホストから到達できないため)と、ca_cert/ca_key が永続化ボリュームの /data 配下を指している点が異なります。指定可能な全項目は下記の設定を参照してください。

Makefileショートカット

ターゲット	説明
make docker-build	docker compose build でイメージをビルド
make docker-run	ビルドしてバックグラウンドで起動
make docker-stop	コンテナを停止・削除

停止・クリーンアップ

docker compose down          # コンテナを停止
rm -rf data                  # 永続化したCAも削除する場合(削除後は再度信頼設定が必要)

設定

プロキシを起動する前に config.yaml を編集してください。全項目にデフォルト値があるため、変更したい項目だけを指定すれば十分です。

listen: "127.0.0.1:8080"
mgmt_listen: "127.0.0.1:8081"  # Chrome拡張機能が使う管理API(空文字で無効化)
ca_cert: "ca.crt"
ca_key:  "ca.key"

tls:
  # TLSフィンガープリントのプリセット(JA3 / JA4を制御)
  # 選択肢: chrome | firefox | safari | edge | ios | random | golang
  preset: "chrome"

http:
  # User-Agentを上書き(空にするとクライアントのUAをそのまま通す)
  # "auto": tls.presetに対応するUAを使用(random/golang/customでは素通し)
  # "random": 内蔵リストからランダムに選択
  user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"

  # 送信元IPを偽装: X-Forwarded-For と True-Client-IP の両方をこの値に設定し、
  # クライアントが既に設定していた値を上書きする(空にすると無効化)
  # client_ip: "1.2.3.4"

  # このヘッダー順で送出する。リストにないヘッダーは末尾に追加される
  header_order:
    - "Host"
    - "User-Agent"
    - "Accept"
    - "Accept-Language"
    - "Accept-Encoding"
    - "Connection"

  # ヘッダーを追加または上書き
  add_headers:
    Accept-Language: "ja,en-US;q=0.9,en;q=0.8"

  # 転送前に削除するヘッダー
  remove_headers: []

http2:
  enabled: true

  # SETTINGSフレームのエントリ — idと順序の両方がHTTP/2フィンガープリントに影響する。
  # RFC 7540 §11.3 のID:
  #   1=HEADER_TABLE_SIZE  2=ENABLE_PUSH  3=MAX_CONCURRENT_STREAMS
  #   4=INITIAL_WINDOW_SIZE  5=MAX_FRAME_SIZE  6=MAX_HEADER_LIST_SIZE
  settings:
    - { id: 1, val: 65536 }    # ここではChromeのデフォルト値を例示
    - { id: 2, val: 0 }
    - { id: 4, val: 6291456 }
    - { id: 6, val: 262144 }

  # コネクションレベルのWINDOW_UPDATE増分
  window_update: 15663105

  # HEADERSフレーム内の疑似ヘッダーの順序
  pseudo_header_order: [method, authority, scheme, path]

管理API

プロキシ起動時、mgmt_listen(デフォルト 127.0.0.1:8081)にも軽量なHTTP APIが公開されます。Chrome拡張機能はこれを使ってプロキシを再起動せずに実行時の設定を読み書きします。curlから直接呼び出すこともできます:

エンドポイント	メソッド	説明
/api/config	GET	現在の設定をJSONで返す(現在の custom_hello とアップストリームの状態を含む)
/api/config	POST	TLSプリセット / custom_hello / 送信元IP / User-Agent / アップストリームの有効化・選択を部分的に更新する — 指定しなかったフィールドは変更されない
/api/upstream	GET	アップストリームの状態を返す: enabled、select、設定済みプロキシの名前(URLや認証情報は含まない)、IPヘッダー抑制が有効かどうか

POST /api/config は本当の意味での部分更新です。変更したいフィールドだけを送れば、TLSプリセットやアップストリームの選択を含め、それ以外はそのまま維持されます。

# 現在の設定を読む
curl http://127.0.0.1:8081/api/config