A local MITM proxy that lets you control TLS fingerprints (JA3/JA4), HTTP/2 fingerprints, HTTP header order, User-Agent, and source IP headers — all from a single YAML config file.
A Chrome extension is included for toggling the proxy and switching fingerprint profiles directly from the browser toolbar without restarting the proxy.
Intended for authorized security testing of WAF bot-detection systems. Route curl, browsers, or Playwright through the proxy to observe how different fingerprint combinations are classified.
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
| Layer | What you can control |
|---|---|
| TLS | Cipher suites, extensions, their order (JA3 / JA4) via uTLS presets or a fully custom custom_hello spec |
| HTTP/1.1 | Header order, User-Agent, add/remove any header, IP spoofing (X-Forwarded-For / True-Client-IP) |
| HTTP/2 | SETTINGS values & order, WINDOW_UPDATE, pseudo-header order (HTTP/2 fingerprint) |
- macOS or Linux (amd64 / arm64)
- Go 1.22+
brew install goThe distro-packaged Go is often outdated. Install the official binary directly:
# 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/binVerify:
go version
# go version go1.22.5 linux/amd64ARM64 (Raspberry Pi, AWS Graviton, etc.): replace
linux-amd64withlinux-arm64in the download URL.
Prefer a disposable environment instead of installing Go? Skip straight to Docker.
git clone https://github.com/ytkoka/impersonate-proxy.git
cd impersonate-proxy
make buildThe CA is generated automatically on first run. Start the proxy once to create ca.crt and 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=chromeStop it with Ctrl-C.
Clients need to trust your MITM CA so they don't reject the proxy-generated leaf certificates.
macOS system keychain (affects all apps):
make trust-ca # runs: sudo security add-trusted-cert ...Linux system trust (affects all apps; requires ca-certificates package):
# 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-trustcurl only (no system-wide change):
curl --cacert ca.crt ...Playwright / Node.js:
export NODE_EXTRA_CA_CERTS="$(pwd)/ca.crt"Firefox: Preferences → Privacy & Security → View Certificates → Authorities → Import ca.crt
Run the proxy in a container — no local Go/Make install required.
Linux only: the container runs as an unprivileged user (
nonroot, UID 65532) and needs write access to the./datadirectory that holds the CA cert/key. If./datadoesn't exist yet, Docker auto-creates it owned byrootwith no write access for other users, so the container will fail to generate the CA on first run. Create it with the right owner beforehand:mkdir -p data && sudo chown 65532:65532 dataNot needed on Docker Desktop for Mac/Windows — its bind-mount layer maps ownership automatically.
git clone https://github.com/ytkoka/impersonate-proxy.git
cd impersonate-proxy
docker compose up -dThis builds the image locally and starts the container. On first run it generates the MITM CA and prints:
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
Or, to run the prebuilt image directly without cloning:
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:latestdocker-compose.yml publishes both ports to 127.0.0.1 only — same loopback-only exposure as a native install (the management API has no authentication, so don't change this to 0.0.0.0 without adding your own access control).
The CA is generated inside the container but persisted to ./data/ca.crt and ./data/ca.key on the host via the bind-mounted volume, so it survives container restarts/rebuilds. Trust it exactly as in the native setup above, just pointing at ./data/ca.crt instead of ./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.crtEdit config.docker.yaml (not config.yaml — that file is for the native install) and restart:
docker compose restartconfig.docker.yaml is identical to config.yaml except listen/mgmt_listen are 0.0.0.0 (required for Docker's port publishing to reach the process at all — the container's own 127.0.0.1 is unreachable from the host) and ca_cert/ca_key point at /data, the persisted volume. See Configuration below for all available fields.
| Target | Description |
|---|---|
make docker-build |
Build the image via docker compose build |
make docker-run |
Build and start in the background |
make docker-stop |
Stop and remove the container |
docker compose down # stop the container
rm -rf data # also remove the persisted CA (re-trust required after)Edit config.yaml before starting the proxy. All fields have defaults — you only need to specify what you want to override.
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
# The HTTP/2 fingerprint follows tls.preset (see "Browser fingerprint reference"
# below), so switching the preset switches it too. The fields below are optional
# overrides: set one only to pin it for EVERY preset.
#
# 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's values 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]
# PRIORITY frames sent after the preface, and the priority carried in HEADERS
# (weight 1-256, as tls.peet.ws shows it)
# priorities: [{ stream_id: 3, depends_on: 0, weight: 201 }]
# headers_priority: { depends_on: 0, weight: 256, exclusive: true }
# Order of regular request headers over HTTP/2 (http.header_order is HTTP/1.1 only).
# Default: the order the preset's browser sends them in.
# header_order: [user-agent, accept, accept-language, accept-encoding]
# ID of the first request stream (odd). Default: the preset's browser (Firefox 15, others 1).
# first_stream_id: 1
# Impersonate only some target hosts (default: all). Hosts that are not
# impersonated are tunnelled through untouched. Patterns: "example.com" (exact)
# or "*.example.com" (subdomains only, not example.com itself).
filter:
mode: "off" # off | include (only the listed hosts) | exclude (all but the listed hosts)
hosts: []
# Hosts the MCP server's fetch_url tool may reach (see "MCP server"). Each entry
# allows that host and its subdomains; empty allows any public host. Read-only
# at runtime: it cannot be changed through the management API or MCP — edit it
# here, or pass `-fetch-allow-hosts a.com,b.com` when starting the proxy.
fetch_allow_hosts: []When the proxy starts it also exposes a lightweight HTTP API on mgmt_listen (default 127.0.0.1:8081). The Chrome extension uses this to read and update settings at runtime without restarting the proxy. You can also call it directly with curl:
| Endpoint | Method | Description |
|---|---|---|
/api/config |
GET |
Return active settings as JSON, including the current custom_hello and upstream state |
/api/config |
POST |
Partially update TLS preset / custom_hello / client IP / User-Agent / upstream enabled+select / host filter — omitted fields are left unchanged |
/api/upstream |
GET |
Return upstream state: enabled, select, configured proxy names (never URLs/credentials), and whether IP-header suppression is active |
POST /api/config is a genuine partial update: send only the field you want to change and everything else — including TLS preset and upstream selection — is left as-is.
# Read current settings
curl http://127.0.0.1:8081/api/config
# Switch to Firefox fingerprint and set a spoofed IP (other fields untouched)
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"}'
# Switch to an arbitrary JA3/JA4 fingerprint at runtime — same fields as the
# config.yaml custom_hello block, sent as JSON (see "Custom TLS fingerprint" below)
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": ""
}'
# Enable the upstream proxy and pick one by name — leaves TLS preset,
# client IP, and User-Agent exactly as they were
curl -s -X POST http://127.0.0.1:8081/api/config \
-H "Content-Type: application/json" \
-d '{"upstream_enabled": true, "upstream_select": "residential_us"}'
# Read current upstream state
curl -s http://127.0.0.1:8081/api/upstreamChanges take effect immediately for new connections. Set mgmt_listen: "" to disable the API entirely.
By default every host is impersonated. To impersonate only some targets, set filter:
filter:
mode: "include" # off (default) | include | exclude
hosts:
- "www.example.com" # exact host
- "*.example.com" # any subdomain, but not example.com itselfincludeimpersonates only the listed hosts,excludeimpersonates every host except the listed ones, andoffimpersonates everything.- A host that is not impersonated is passed through untouched. For HTTPS, the
CONNECTtunnel is relayed as raw bytes without terminating TLS, so the client sees the origin's real certificate (no CA trust is needed for these hosts) and its own TLS fingerprint, and no headers are rewritten. Plain-HTTP requests are forwarded without header rewriting. Both still go through the upstream proxy when it is enabled. - Matching ignores case and port.
example.commatches exactly that host;*.example.commatches subdomains at any depth but notexample.comitself, so list both to cover the apex too. IP literals match exactly. Ports, paths, CIDR ranges and any other use of*are rejected with an error at startup or from the management API. - A page usually loads other hosts as well (CDNs, challenge scripts). List those too, or the WAF will see a mix of impersonated and real fingerprints. Passed-through tunnels are logged as
PASSTHROUGH host:port, which helps find them. - Change it at runtime with
filter_modeandfilter_hoststhrough the management API.filter_hostsreplaces the whole list, and a rejected patch changes nothing. In-flight connections are unaffected.
curl -s -X POST http://127.0.0.1:8081/api/config \
-H "Content-Type: application/json" \
-d '{"filter_mode":"include","filter_hosts":["www.example.com","*.example.com"]}'The HTTP/2 fingerprint is chosen by the TLS preset. It is the akamai_fingerprint string tls.peet.ws reports: SETTINGS | WINDOW_UPDATE | PRIORITY frames | pseudo-header order (m=:method, a=:authority, s=:scheme, p=:path).
| Browser | TLS preset | HTTP/2 fingerprint | Source |
|---|---|---|---|
| Chrome 156 | chrome |
1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p |
measured |
| Edge (Chromium) | edge |
same as Chrome | same network stack |
| Firefox 133–148 | firefox |
1:65536;2:0;4:131072;5:16384|12517377|0|m,p,a,s |
published |
| Safari 17 (macOS) | safari |
2:0;4:4194304;3:100|10485760|0|m,s,p,a |
published |
| Safari 17 (iOS) | ios |
2:0;4:2097152;3:100|10485760|0|m,s,p,a |
published |
| — | custom, random, golang |
Chrome's | no single browser behind them |
"Measured" means observed from the real browser through tls.peet.ws; "published" means taken from tls-client and curl-impersonate, which record real browser traffic. The per-profile sources are in h2fp/profiles.go. The Safari/iOS profiles are Safari 17 to match the User-Agents the proxy sends for user_agent: "auto"; Safari 18.4 and later send 2:0;3:100;4:2097152;9:1|10420225|0|m,s,a,p. get_config (and GET /api/config) reports the fingerprint in effect as http2_fingerprint.
Request headers. Over HTTP/2 the proxy also sends the headers a request carries in the order the preset's browser does — for example iOS Safari: accept, sec-fetch-site, accept-encoding, sec-fetch-mode, user-agent, accept-language, sec-fetch-dest; Chrome starts with the sec-ch-ua* headers; Firefox starts with user-agent. It only reorders: it never adds headers, so a client that doesn't send Accept still won't (the MCP fetch_url tool does send the browser's page-load headers). Headers that aren't in the browser's list follow, alphabetically. Firefox's first request goes out on stream 15, as the real browser does. The orders come from captures of the real browsers (curl-impersonate tests/signatures, listed in hdrprofile/hdrprofile.go); Edge's is Chrome's. Override with http2.header_order; http.header_order still sets the order for HTTP/1.1 only.
Fields set under http2: in config.yaml override the preset's value for every preset. If your config.yaml was copied from an older version and still lists settings, window_update and pseudo_header_order, those pin Chrome's values: delete them to follow the preset.
With user_agent: "auto" the proxy sets the User-Agent that matches the current tls.preset, so the TLS fingerprint and the UA never contradict each other. Switching the preset (via config or the Chrome extension) switches the UA too.
tls.preset |
User-Agent sent |
|---|---|
chrome |
Chrome 131 (macOS) |
firefox |
Firefox 132 (macOS) |
safari |
Safari 17.2 (macOS) |
edge |
Edge 131 (Windows) |
ios |
iPhone / iOS 17.1 Safari |
random, golang, custom |
not modified — the client's own UA is passed through |
"random" is a separate mode that picks a random UA from a built-in list on every request, regardless of the TLS preset.
Note: The
edgepreset sends the same TLS ClientHello aschrome, andiosthe same assafari(the older uTLS Edge 85 / iOS 14 hellos contradicted the Edg/131 and iOS 17 User-Agents). Their JA3/JA4 values therefore match Chrome and Safari respectively.
The built-in presets (chrome, firefox, safari, …) cover the most common cases. When you need to match a specific browser version or a fingerprint that differs from those presets, set preset: "custom" and provide a custom_hello block.
How JA3 / JA4 map to config fields
| Fingerprint component | Config field | Notes |
|---|---|---|
| TLS version range | versions |
Min/max are derived automatically |
| Cipher suite list + order | cipher_suites |
Use 0x0a0a as a GREASE placeholder; uTLS randomises it per connection |
| Extension type IDs + order | extensions |
Order directly controls the JA3 extensions component; values matching the GREASE pattern (0xXAXA) are randomised per connection |
| Supported groups (curves) | curves |
Also controls which key shares are sent |
JA3 and JA4 are one-way hashes — you cannot reverse a hash back to a spec. Find the underlying parameters for the target browser with tls.peet.ws or Wireshark, then paste them into
custom_hello.
Chrome 131 example
tls:
preset: "custom"
custom_hello:
cipher_suites: # hex IDs; 0x0a0a = GREASE placeholder (randomised per connection)
- 0x0a0a
- 0x1301 # TLS_AES_128_GCM_SHA256
- 0x1302 # TLS_AES_256_GCM_SHA384
- 0x1303 # TLS_CHACHA20_POLY1305_SHA256
- 0xc02b # ECDHE-ECDSA-AES128-GCM-SHA256
- 0xc02f # ECDHE-RSA-AES128-GCM-SHA256
- 0xc02c # ECDHE-ECDSA-AES256-GCM-SHA384
- 0xc030 # ECDHE-RSA-AES256-GCM-SHA384
- 0xcca9 # ECDHE-ECDSA-CHACHA20-POLY1305
- 0xcca8 # ECDHE-RSA-CHACHA20-POLY1305
- 0xc013 # ECDHE-RSA-AES128-SHA
- 0xc014 # ECDHE-RSA-AES256-SHA
- 0x009c # RSA-AES128-GCM-SHA256
- 0x009d # RSA-AES256-GCM-SHA384
- 0x002f # RSA-AES128-SHA
- 0x0035 # RSA-AES256-SHA
curves: # X25519 | X25519Kyber768 | P256 | P384 | P521
- "X25519Kyber768"
- "X25519"
- "P256"
versions: # TLS versions to advertise
- "1.3"
- "1.2"
extensions: # extension type IDs in order (controls JA3 extensions component)
- 0x0a0a # GREASE
- 0 # server_name (SNI)
- 23 # extended_master_secret
- 65281 # renegotiation_info
- 10 # supported_groups
- 11 # ec_point_formats
- 35 # session_ticket
- 16 # ALPN
- 5 # status_request
- 18 # signed_certificate_timestamp
- 13 # signature_algorithms
- 51 # key_share
- 45 # psk_key_exchange_modes
- 43 # supported_versions
- 27 # compress_certificate
- 17513 # application_settings (ALPS)
- 0x0a0a # GREASE
- 21 # paddingSupported extension type IDs
| ID | Name | Notes |
|---|---|---|
0xXAXA (any GREASE pattern) |
GREASE | Randomised per connection |
0 |
server_name (SNI) | |
5 |
status_request | OCSP stapling |
10 |
supported_groups | Uses the curves list |
11 |
ec_point_formats | Fixed: uncompressed (0) |
13 |
signature_algorithms | Chrome-like defaults |
16 |
ALPN | Advertises h2, http/1.1 |
18 |
signed_certificate_timestamp | |
21 |
padding | BoringSSL-style padding |
23 |
extended_master_secret | |
27 |
compress_certificate | |
28 |
record_size_limit | Fixed: 0x4001 |
35 |
session_ticket | |
43 |
supported_versions | Uses the versions list |
45 |
psk_key_exchange_modes | PSK with DHE |
50 |
signature_algorithms_cert | Chrome-like defaults |
51 |
key_share | Key shares for X25519 and P256 (from curves) |
17513 |
application_settings (ALPS) | Advertises h2 |
17613 |
application_settings (ALPS, new codepoint) | Advertises h2; sent by Chrome 133+ instead of 17513 |
65037 |
encrypted_client_hello (ECH) | GREASE ECH payload (BoringSSL-style) |
65281 |
renegotiation_info | |
| other | GenericExtension | Sent with empty payload |
Runtime updates:
preset: "custom"is not limited toconfig.yaml— it can also be switched to at runtime via the management API (POST /api/configwith acustom_helloobject, see Management API) or from the Chrome extension's TLS Preset dropdown, without restarting the proxy.
By default the proxy dials the target directly, so X-Forwarded-For / True-Client-IP spoofing (above) only changes what a request claims — the TCP connection's real source IP is still yours. Setting upstream.enabled: true routes the target connection through a SOCKS5 or HTTP CONNECT proxy first, so the real egress IP changes too. This lets you test WAF rules that ignore spoofable headers and look at the connecting IP itself, and to separate "fingerprint is fine but the IP is bad" from "IP is clean but the fingerprint is wrong."
Only tunnel-capable schemes are supported — socks5, socks5h, and http (CONNECT). Both hand back a raw TCP tunnel that the proxy then wraps with uTLS itself, so the ClientHello and HTTP/2 framing this whole tool exists to control pass through completely unmodified. An https:// (TLS-terminating) upstream is not supported: it would decrypt and re-establish TLS itself, replacing your uTLS fingerprint with its own.
upstream:
enabled: false # off by default; toggle at runtime without restarting
select: "residential_us" # proxy name | "rotate" | "random" | "" (first proxy)
dial_timeout_ms: 15000
suppress_ip_headers_when_active: true # skip XFF/True-Client-IP while upstream is active — avoids a clean IP claiming a spoofed one
proxies:
- name: residential_us
url: "socks5://user:pass@gw.provider.com:1080" # hostnames are resolved by the proxy (SOCKS5h behavior), never locally
- name: datacenter
url: "http://user:pass@dc.provider.com:8080"
- name: tor
url: "socks5://127.0.0.1:9050" # free to try: brew install tor && brew services start torSwitch proxies at runtime the same way as the TLS preset — via the Chrome extension's "Upstream proxy" toggle/dropdown, or:
curl -s -X POST http://127.0.0.1:8081/api/config \
-H "Content-Type: application/json" \
-d '{"upstream_enabled": true, "upstream_select": "residential_us"}'GET /api/upstream and the Chrome extension's dropdown only ever show proxy names — URLs and credentials never leave the proxy process.
Verifying it actually worked: check the real egress IP (e.g. curl --proxy http://127.0.0.1:8080 https://ifconfig.me) before and after enabling upstream, and separately confirm the fingerprint is unaffected with tls.peet.ws — JA3/JA4 and the HTTP/2 fingerprint should be identical with upstream.enabled on or off, since only the network path changed.
Gotcha: a browser (unlike
curl) keeps warm, pooled connections per origin. If you switchselect(or toggleenabled) and then just reload a tab that already had a connection open, the browser may reuse that existing connection instead of opening a new one — so the change won't show up until it actually dials fresh. Test in a new Incognito window, or flushchrome://net-internals/#sockets, if a switch doesn't seem to take effect.
Don't trust a proxy just because it accepts a connection. A SOCKS5/CONNECT handshake succeeding tells you nothing about whether the proxy is honest — a malicious one can terminate your TLS itself and hand back its own certificate instead of tunneling raw bytes, letting it read (or alter) everything you thought was end-to-end encrypted. Before relying on any proxy you didn't set up yourself, check for exactly this: hit
https://tls.peet.wsthrough it and confirm (a) there's no certificate error and (b) the JA4 matches what you get withupstream.enabled: false. A cert error or a changed JA4 means the "proxy" is intercepting your traffic, not tunneling it — don't route anything through it.
Docker: an upstream URL pointing at the host machine (e.g. a local Tor instance at
socks5://127.0.0.1:9050) won't resolve inside the container —127.0.0.1there is the container's own loopback, not the host's. Usesocks5://host.docker.internal:9050(Docker Desktop on Mac/Windows) or the container's default-gateway IP (Linux) instead.
make run
# Kills any previous instance on port 8080, rebuilds, and starts.To switch fingerprint profiles, edit config.yaml and re-run make run.
# With CA trusted system-wide (after make trust-ca):
curl --proxy http://127.0.0.1:8080 https://tls.peet.ws/api/all
# Without system trust — pass CA explicitly:
curl --proxy http://127.0.0.1:8080 --cacert ca.crt https://tls.peet.ws/api/allThe chrome-extension/ directory contains a Manifest V3 extension that controls the proxy from the browser toolbar.
Installation:
Option A — Chrome Web Store (recommended):
Option B — Load unpacked (for development, or to try unreleased changes):
- Open
chrome://extensionsin Chrome - Enable Developer mode (toggle in the top-right corner)
- Click Load unpacked and select the
chrome-extension/folder
Controls:
| Control | What it does |
|---|---|
| Proxy toggle | Enables / disables Chrome's proxy setting (routes traffic through :8080) |
| TLS Preset | Switches the uTLS fingerprint preset (chrome / firefox / safari / edge / ios / random / golang / custom) |
| Cipher Suites / Curves / TLS Versions / Extensions | Shown when Custom (JA3/JA4) is selected — the same fields as custom_hello in config.yaml, letting you dial in an arbitrary JA3/JA4 fingerprint without editing YAML or restarting the proxy |
| Client IP | Sets X-Forwarded-For and True-Client-IP on every request |
| User-Agent | Overrides the HTTP User-Agent header. Auto follows the selected TLS preset (see User-Agent auto mode); Random picks a random UA per request. Auto and Random are mutually exclusive |
| Upstream proxy | Enables routing through an upstream SOCKS5/HTTP-CONNECT proxy and selects which one (or rotate/random) — see Upstream proxy |
| Apply button | POSTs the new settings to the management API; takes effect immediately |
| API field | Address of the management API (default http://127.0.0.1:8081) |
User-Agent scope: The extension changes the HTTP
User-Agentheader only. JavaScript'snavigator.userAgentis controlled by Chrome itself and is not affected. To spoof both simultaneously, launch Chrome with--user-agent="..."alongside the proxy settings.
const { chromium } = require('playwright');
const browser = await chromium.launch();
const context = await browser.newContext({
proxy: { server: 'http://127.0.0.1:8080' },
});
// If CA is not in the system keychain, set before launching:
// NODE_EXTRA_CA_CERTS=./ca.crt node script.js
const page = await context.newPage();
await page.goto('https://tls.peet.ws/api/all');For a more complete example — cycling through presets via the management API and recording a WAF's allow/block verdict for each — see examples/waf-fingerprint-test.js.
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch()
context = browser.new_context(proxy={"server": "http://127.0.0.1:8080"})
page = context.new_page()
page.goto("https://tls.peet.ws/api/all")Set NODE_EXTRA_CA_CERTS (Node) or REQUESTS_CA_BUNDLE (Python) if the CA is not trusted system-wide.
tls.peet.ws returns the full fingerprint breakdown for any request it receives. Pipe the output through jq or Python for a readable view:
curl -s --proxy http://127.0.0.1:8080 --cacert ca.crt \
https://tls.peet.ws/api/all | python3 -m json.toolKey fields to check:
| Field | Description |
|---|---|
tls.ja3_hash |
JA3 fingerprint hash |
tls.ja4 |
JA4 fingerprint string |
http2.akamai_fingerprint |
HTTP/2 fingerprint string (SETTINGS + WINDOW_UPDATE + pseudo-header order) — field name is defined by the tls.peet.ws API |
http1.headers |
Header names in the order received by the server |
user_agent |
User-Agent as seen by the server |
ip |
Source IP as seen by the server — verify X-Forwarded-For / True-Client-IP spoofing here |
impersonate-mcp/ is a stdio MCP server, built on the official Go SDK, that lets an AI agent configure the proxy and check the result. It is a plain client of the Management API and reuses the config package types. It is a separate Go module: make build does not build it and the Docker image does not include it.
make build-mcp # → impersonate-mcp/impersonate-mcp
make test-mcpRegister it with your MCP client (the proxy must be running). For Claude Code:
claude mcp add impersonate -- /path/to/impersonate-proxy/impersonate-mcp/impersonate-mcp --ca-cert /path/to/impersonate-proxy/ca.crtOr in any client's JSON config:
{
"mcpServers": {
"impersonate": {
"command": "/path/to/impersonate-proxy/impersonate-mcp/impersonate-mcp",
"args": ["--ca-cert", "/path/to/impersonate-proxy/ca.crt"],
"env": { "IMPERSONATE_MGMT_URL": "http://127.0.0.1:8081" }
}
}
}
commandmust be the binary, not a directory. The executable isimpersonate-mcp/impersonate-mcpinside the clone;make build-mcpprints its absolute path when it finishes./path/to/impersonate-proxyin the examples above is your clone.
| Tool | Description |
|---|---|
get_config |
Return the active runtime settings (TLS preset, custom_hello, User-Agent, client IP, upstream state, host filter, http2_fingerprint, fetch_allow_hosts) |
set_tls_preset |
Switch the TLS preset (chrome, firefox, safari, …). The HTTP/2 fingerprint switches with it |
set_custom_hello |
Set an arbitrary ClientHello (cipher suites, curves, versions, extensions) and switch the preset to custom |
set_user_agent |
Set the User-Agent ("" = leave as is, "auto" = derive from the preset) |
set_client_ip |
Set the spoofed client IP ("" = off) |
set_upstream |
Enable/disable the upstream proxy and/or select one by name (or rotate / random) |
verify_fingerprint |
Fetch tls.peet.ws/api/all through the proxy and summarise ja3_hash, ja4, akamai_fingerprint, user_agent and ip |
fetch_url |
Fetch any http(s) URL through the proxy — with the current TLS preset, User-Agent, client IP, upstream and host filter — and return status, http_version, final_url, redirects, headers, body (text only; Set-Cookie values are omitted), body_truncated, elapsed_ms. Options: method, headers, body, follow_redirects (max 10), max_body_bytes (default 51200, max 1048576). GET and HEAD carry the preset browser's page-load headers (Accept, Accept-Encoding, Sec-Fetch-*, …) unless you pass your own; compressed bodies (gzip, deflate, br, zstd) are decoded. Failures are reported in the error field |
| Flag | Environment variable | Default | Description |
|---|---|---|---|
--mgmt-url |
IMPERSONATE_MGMT_URL |
http://127.0.0.1:8081 |
Management API base URL |
--proxy-url |
IMPERSONATE_PROXY_URL |
derived from the proxy's listen |
Proxy used by verify_fingerprint and fetch_url |
--ca-cert |
IMPERSONATE_CA_CERT |
system trust store | Path to the proxy's ca.crt, so verify_fingerprint and fetch_url trust the MITM certificate |
--verify-url |
IMPERSONATE_VERIFY_URL |
https://tls.peet.ws/api/all |
Fingerprint echo endpoint |
--read-only |
IMPERSONATE_READ_ONLY |
false |
Hide every tool that changes settings (set_*); fetch_url stays but is limited to GET / HEAD / OPTIONS without a body |
- The management API has no authentication, and this server lets an agent change the proxy's settings. Keep
mgmt_listenon loopback (a warning is logged otherwise), and use--read-onlywhen the agent should only observe. verify_fingerprintsends one request to an external service (tls.peet.wsby default). If the host filter excludes that host the result is not impersonated, and the tool says so inwarnings.set_upstreamcan only toggle and select proxies that are already inconfig.yaml; adding proxies at runtime is not supported by the management API.- The HTTP/2 fingerprint (
akamai_fingerprint) follows the TLS preset, andget_configshows it ashttp2_fingerprint. Values pinned underhttp2:inconfig.yamloverride the preset for every preset. fetch_urlalways goes through the proxy, so every current setting applies; it never connects to targets directly. It refuses loopback, private and link-local destinations (127.0.0.0/8,10/8,172.16/12,192.168/16,169.254/16,::1, plusfc00::/7,fe80::/10,100.64/10and0.0.0.0/8), checking both the host and every address it resolves to, and re-checks each redirect hop.fetch_allow_hosts(proxyconfig.yamlor-fetch-allow-hosts) can further limit it to listed hosts and their subdomains;get_configshows the list, and no tool can change it. If the proxy's configuration cannot be read,fetch_urlrefuses rather than fetching unrestricted. Limit: the name is resolved once by the MCP server and again by the proxy, so a DNS-rebinding server that answers differently the second time is not stopped by this check alone.- Logs go to stderr; stdout is reserved for the MCP protocol.
impersonate-proxy/
├── main.go # Entry point
├── config/config.go # YAML config struct and defaults
├── fp/dialer.go # uTLS dialer — TLS fingerprint presets
├── h2fp/conn.go # HTTP/2 framer — SETTINGS / WINDOW_UPDATE / pseudo-header control
├── mitm/ca.go # MITM CA: generate, cache, and serve leaf certs
├── upstream/ # Upstream SOCKS5/HTTP-CONNECT proxy: manager, dialers, selection
├── proxy/proxy.go # Proxy server: CONNECT handling, protocol branch, runtime config
├── rewrite/headers.go # HTTP header rewriting (UA, order, add/remove, IP spoof)
├── filter/filter.go # Host filter: which targets get impersonated
├── mgmt/server.go # Management HTTP API (/api/config, /api/upstream)
├── impersonate-mcp/ # Optional MCP server (separate Go module): drives the management API
├── chrome-extension/
│ ├── manifest.json # Manifest V3
│ ├── popup.html # Toolbar popup UI
│ ├── popup.css
│ ├── popup.js # Proxy toggle + upstream toggle + management API client
│ ├── icon.svg
│ └── icon16.png, icon48.png, icon128.png # Toolbar / Web Store icons
├── config.yaml # Default configuration
├── config.docker.yaml # Configuration used by docker-compose.yml
├── examples/
│ └── waf-fingerprint-test.js # Playwright harness: cycle presets, record WAF verdicts
├── Dockerfile
├── docker-compose.yml
└── Makefile
| Target | Description |
|---|---|
make build |
Compile the binary |
make build-mcp |
Build the optional MCP server to impersonate-mcp/impersonate-mcp (see MCP server) |
make test-mcp |
Run the MCP server's tests |
make package-mcpb |
Build per-platform .mcpb bundles for the MCP server into impersonate-mcp/dist/ (needs jq, zip) |
make run |
Build, kill any existing instance, and start |
make trust-ca |
Add ca.crt to the macOS system keychain (requires sudo) |
make clean |
Remove the binary, ca.crt, and ca.key |
make docker-build |
Build the Docker image (see Docker) |
make docker-run |
Build and start the container in the background |
make docker-stop |
Stop and remove the container |
Remove the binary and generated CA files:
make cleanIf you added the CA to the macOS system keychain, remove it through Keychain Access (search for "impersonate-proxy CA") or:
sudo security delete-certificate -c "impersonate-proxy CA" /Library/Keychains/System.keychain- MITM only: The proxy decrypts and re-encrypts traffic. Clients must trust the generated CA.
- No HTTP/2 from client: The client→proxy leg uses HTTP/1.1 (via CONNECT). Only the proxy→server leg uses HTTP/2 with custom fingerprints.
- Request trailers:
Transfer-Encoding: chunkedrequest bodies are forwarded, but their trailers are dropped. Expect: 100-continue: The proxy answers this itself and strips the header, so the client sends its body before the server has accepted the request.- WebSocket:
wss://is supported over HTTP/1.1 only. When the server speaks h2, the proxy opens a second connection for the upgrade with a ClientHello that offers onlyhttp/1.1ALPN and no ALPS extension (as browsers do for WebSocket sockets); that hello's JA3/JA4 therefore differs from the page's h2 connection, and has not been compared against a real browser capture. The upgraded stream is relayed byte for byte. Not supported:ws://throughCONNECT(the tunnel assumes TLS), and WebSocket over HTTP/2 (RFC 8441). - Host filter and plain HTTP: requests to hosts that are not impersonated are re-serialized by the proxy, so their header order is not preserved (HTTPS passthrough is relayed byte for byte). See Host filter.
- Large request bodies over HTTP/2: The body is sent as a single DATA frame without flow control, so a server can reject bodies above its frame size limit (typically 16 KB) with
FRAME_SIZE_ERROR. HTTP/1.1 is not affected. - No QUIC / HTTP/3: Out of scope.
- User-Agent (HTTP header only): The proxy rewrites the
User-AgentHTTP header, but JavaScript'snavigator.userAgentis set by the browser independently and is unaffected. Use Chrome's--user-agentlaunch flag to override both simultaneously. - Upstream proxy is TCP-tunnel-only: only
socks5/socks5h/http(CONNECT) upstreams are supported — an upstream that terminates TLS itself is rejected at startup, since it would strip the uTLS ClientHello. See Upstream proxy.
This tool is intended for authorized security testing only — for example, testing WAF and bot-detection configurations on systems you own or have explicit written permission to test.
Using this tool against systems without authorization may violate applicable laws (such as the Computer Fraud and Abuse Act, Japan's Unauthorized Computer Access Law, or equivalent legislation in your jurisdiction) and the terms of service of the target.
The authors accept no liability for misuse.
- uTLS — TLS fingerprint customization
- tls.peet.ws — Fingerprint inspection API used in examples
- JA4+ — Fingerprinting standard reference
