impersonate-proxy

English | 日本語 | 简体中文

一个本地 MITM 代理,可通过单个 YAML 配置文件控制 TLS 指纹(JA3/JA4)、HTTP/2 指纹、HTTP 请求头顺序、User-Agent 以及源 IP 请求头。

项目内置了一个 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 等): 将下载链接中的 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.docker.yaml(而不是 config.yaml——那是原生安装使用的文件),然后重启:

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

# 切换为 Firefox 指纹并设置伪装 IP(其他字段不受影响)
curl -s -X POST http://127.0.0.1:8081/api/config \
  -H "Content-Type: application/json" \
  -d '{"tls_preset":"firefox","client_ip":"203.0.113.1"}'

# 在运行时切换为任意 JA3/JA4 指纹 — 字段与 config.yaml 中的
# custom_hello 块相同,以 JSON 形式发送(参见下方的“自定义 TLS 指纹”)
curl -s -X POST http://127.0.0.1:8081/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "tls_preset": "custom",
    "custom_hello": {
      "cipher_suites": [2570, 4865, 4866, 4867, 49195, 49199, 49196, 49200, 52393, 52392, 49171, 49172, 156, 157, 47, 53],
      "curves": ["X25519", "P256", "P384"],
      "versions": ["1.3", "1.2"],
      "extensions": [2570, 0, 23, 65281, 10, 11, 35, 16, 5, 18, 13, 51, 45, 43, 27, 21]
    },
    "client_ip": "",
    "user_agent": ""
  }'