impersonate-proxy

English | 日本語 | 简体中文

TLS 지문(JA3/JA4), HTTP/2 지문, HTTP 헤더 순서, User-Agent, 소스 IP 헤더를 단일 YAML 설정 파일에서 모두 제어할 수 있는 로컬 MITM 프록시입니다.

프록시를 재시작하지 않고도 브라우저 툴바에서 직접 프록시를 토글하고 지문 프로필을 전환할 수 있는 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	암호화 스위트, 확장, 그 순서(JA3 / JA4)를 uTLS 프리셋 또는 완전히 사용자 정의된 custom_hello 사양을 통해 제어
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는 흔히 구버전인 경우가 많습니다. 공식 바이너리를 직접 설치하세요:

# Download and extract (replace 1.22.5 with the latest from 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

# Add to PATH (add this line to ~/.bashrc or ~/.zshrc to make it permanent)
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

Mac/Windows용 Docker Desktop에서는 필요하지 않습니다 — 바인드 마운트 계층이 소유권을 자동으로 매핑합니다.

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 system keychain
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은 listen/mgmt_listen이 0.0.0.0(Docker의 포트 게시가 프로세스에 도달하려면 반드시 필요합니다 — 컨테이너 자체의 127.0.0.1은 호스트에서 접근할 수 없습니다)이고 ca_cert/ca_key가 영속 볼륨인 /data를 가리킨다는 점을 제외하면 config.yaml과 동일합니다. 사용 가능한 모든 필드는 아래의 Configuration을 참조하세요.

Makefile 단축 명령

Target	Description
make docker-build	docker compose build를 통해 이미지 빌드
make docker-run	백그라운드에서 빌드 및 시작
make docker-stop	컨테이너 중지 및 제거

중지 / 정리

docker compose down          # stop the container
rm -rf data                  # also remove the persisted CA (re-trust required after)

구성

프록시를 시작하기 전에 config.yaml을 편집하세요. 모든 필드에는 기본값이 있으므로 재정의하려는 항목만 지정하면 됩니다.

listen: "127.0.0.1:8080"
mgmt_listen: "127.0.0.1:8081"  # management API used by the Chrome extension (empty to disable)
ca_cert: "ca.crt"
ca_key:  "ca.key"

tls:
  # TLS fingerprint preset (controls JA3 / JA4)
  # Options: chrome | firefox | safari | edge | ios | random | golang
  preset: "chrome"

http:
  # Override User-Agent (leave empty to pass through the client's UA)
  # "auto": use the UA matching tls.preset (passed through for random/golang/custom)
  # "random": pick a random UA from a built-in list
  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"

  # Spoof source IP: sets both X-Forwarded-For and True-Client-IP to this value,
  # replacing any values the client may have already set (leave empty to disable)
  # client_ip: "1.2.3.4"

  # Emit headers in this order; headers not listed are appended after
  header_order:
    - "Host"
    - "User-Agent"
    - "Accept"
    - "Accept-Language"
    - "Accept-Encoding"
    - "Connection"

  # Add or overwrite headers
  add_headers:
    Accept-Language: "ja,en-US;q=0.9,en;q=0.8"

  # Remove headers before forwarding
  remove_headers: []

http2:
  enabled: true

  # SETTINGS frame entries — id and order both affect the HTTP/2 fingerprint.
  # RFC 7540 §11.3 IDs:
  #   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 defaults shown here
    - { id: 2, val: 0 }
    - { id: 4, val: 6291456 }
    - { id: 6, val: 262144 }

  # Connection-level WINDOW_UPDATE increment
  window_update: 15663105

  # Order of pseudo-headers in the HEADERS frame
  pseudo_header_order: [method, authority, scheme, path]

관리 API

프록시가 시작되면 mgmt_listen(기본값 127.0.0.1:8081)에서 경량 HTTP API도 노출합니다. Chrome 확장 프로그램은 이를 사용해 프록시를 재시작하지 않고 런타임에 설정을 읽고 업데이트합니다. curl로 직접 호출할 수도 있습니다: