impersonate-proxy

Inglese | 日本語 | 简体中文

Un proxy MITM locale che ti consente di controllare le impronte TLS (JA3/JA4), le impronte HTTP/2, l'ordine degli header HTTP, lo User-Agent e gli header dell'IP di origine — tutto da un unico file di configurazione YAML.

È inclusa un'estensione Chrome per attivare/disattivare il proxy e cambiare i profili di fingerprint direttamente dalla barra degli strumenti del browser senza riavviare il proxy.

Destinato ai test di sicurezza autorizzati dei sistemi di rilevamento bot dei WAF. Instrada curl, browser o Playwright attraverso il proxy per osservare come vengono classificate le diverse combinazioni di fingerprint.

Come funziona

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

Livello	Cosa puoi controllare
TLS	Suite di cifratura, estensioni, il loro ordine (JA3 / JA4) tramite preset uTLS o una specifica custom_hello completamente personalizzata
HTTP/1.1	Ordine degli header, User-Agent, aggiunta/rimozione di qualsiasi header, spoofing IP (X-Forwarded-For / True-Client-IP)
HTTP/2	Valori e ordine dei SETTINGS, WINDOW_UPDATE, ordine degli pseudo-header (fingerprint HTTP/2)

Prerequisiti

• macOS o Linux (amd64 / arm64)
• Go 1.22+

macOS

brew install go

Linux

Il Go fornito dalla distribuzione è spesso obsoleto. Installa direttamente il binario ufficiale:

# 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

Verifica:

go version
# go version go1.22.5 linux/amd64

ARM64 (Raspberry Pi, AWS Graviton, ecc.): sostituisci linux-amd64 con linux-arm64 nell'URL di download.

Docker (nessun toolchain Go necessario)

Preferisci un ambiente usa e getta invece di installare Go? Passa direttamente a Docker.

Configurazione

1. Clona e compila

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

2. Genera il certificato CA MITM

La CA viene generata automaticamente al primo avvio. Avvia il proxy una volta per creare ca.crt e 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

Fermalo con Ctrl-C.

3. Fidati del certificato CA

I client devono fidarsi della tua CA MITM per non rifiutare i certificati foglia generati dal proxy.

Portachiavi di sistema macOS (influisce su tutte le app):

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

Trust di sistema Linux (influisce su tutte le app; richiede il pacchetto 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

solo curl (nessuna modifica a livello di sistema):

curl --cacert ca.crt ...

Playwright / Node.js:

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

Firefox: Preferenze → Privacy e sicurezza → Visualizza certificati → Autorità → Importa ca.crt

Docker

Esegui il proxy in un container — non è richiesta un'installazione locale di Go/Make.

1. Avvia il proxy

Solo Linux: il container viene eseguito come utente non privilegiato (nonroot, UID 65532) e necessita dell'accesso in scrittura alla directory ./data che contiene il certificato e la chiave della CA. Se ./data non esiste ancora, Docker la crea automaticamente di proprietà di root senza accesso in scrittura per gli altri utenti, quindi il container non riuscirà a generare la CA al primo avvio. Creala in anticipo con il proprietario corretto:

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

Non necessario su Docker Desktop per Mac/Windows — il suo livello di bind-mount mappa automaticamente la proprietà.

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

Questo costruisce l'immagine localmente e avvia il container. Alla prima esecuzione genera la CA MITM e stampa:

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

Oppure, per eseguire direttamente l'immagine precompilata senza clonare:

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 espone entrambe le porte solo su 127.0.0.1 — la stessa esposizione limitata al loopback di un'installazione nativa (l'API di gestione non ha autenticazione, quindi non modificarlo in 0.0.0.0 senza aggiungere il tuo controllo degli accessi).

2. Considerare attendibile il certificato CA

La CA viene generata all'interno del container ma resa persistente in ./data/ca.crt e ./data/ca.key sull'host tramite il volume bind-mount, così sopravvive ai riavvii/ricostruzioni del container. Rendila attendibile esattamente come nella configurazione nativa sopra, puntando semplicemente a ./data/ca.crt invece di ./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. Configurazione

Modifica config.docker.yaml (non config.yaml — quel file è per l'installazione nativa) e riavvia:

docker compose restart

config.docker.yaml è identico a config.yaml tranne per il fatto che listen/mgmt_listen sono 0.0.0.0 (necessario affinché la pubblicazione delle porte di Docker raggiunga il processo — il 127.0.0.1 interno al container non è raggiungibile dall'host) e ca_cert/ca_key puntano a /data, il volume persistito. Consulta Configuration di seguito per tutti i campi disponibili.

Scorciatoie del Makefile

Target	Descrizione
make docker-build	Compila l'immagine tramite docker compose build
make docker-run	Compila e avvia in background
make docker-stop	Arresta e rimuove il container

Arresto / pulizia

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

Configurazione

Modifica config.yaml prima di avviare il proxy. Tutti i campi hanno valori predefiniti — devi specificare solo ciò che vuoi sovrascrivere.