impersonate-proxy

English | 日本語 | 简体中文

Un proxy MITM local qui vous permet de contrôler les empreintes TLS (JA3/JA4), les empreintes HTTP/2, l'ordre des en-têtes HTTP, le User-Agent et les en-têtes d'IP source — le tout depuis un seul fichier de configuration YAML.

Une extension Chrome est incluse pour activer/désactiver le proxy et changer de profil d'empreinte directement depuis la barre d'outils du navigateur, sans redémarrer le proxy.

Destiné aux tests de sécurité autorisés des systèmes de détection de bots des WAF. Faites passer curl, des navigateurs ou Playwright par le proxy pour observer comment différentes combinaisons d'empreintes sont classifiées.

Fonctionnement

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

Couche	Ce que vous pouvez contrôler
TLS	Suites de chiffrement, extensions, leur ordre (JA3 / JA4) via les préréglages uTLS ou une spécification custom_hello entièrement personnalisée
HTTP/1.1	Ordre des en-têtes, User-Agent, ajout/suppression de n'importe quel en-tête, usurpation d'IP (X-Forwarded-For / True-Client-IP)
HTTP/2	Valeurs et ordre des SETTINGS, WINDOW_UPDATE, ordre des pseudo-en-têtes (empreinte HTTP/2)

Prérequis

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

macOS

brew install go

Linux

Le Go fourni par les distributions est souvent obsolète. Installez directement le binaire officiel :

# 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

Vérifier :

go version
# go version go1.22.5 linux/amd64

ARM64 (Raspberry Pi, AWS Graviton, etc.) : remplacez linux-amd64 par linux-arm64 dans l'URL de téléchargement.

Docker (aucune chaîne d'outils Go nécessaire)

Vous préférez un environnement jetable plutôt que d'installer Go ? Passez directement à Docker.

Installation

1. Cloner et compiler

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

2. Générer le certificat CA MITM

La CA est générée automatiquement au premier lancement. Démarrez le proxy une fois pour créer ca.crt et 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

Arrêtez-le avec Ctrl-C.

3. Faire confiance au certificat CA

Les clients doivent faire confiance à votre CA MITM afin qu'ils ne rejettent pas les certificats feuilles générés par le proxy.

Trousseau système macOS (affecte toutes les applications) :

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

Confiance système Linux (affecte toutes les applications ; nécessite le paquet 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 uniquement (aucune modification à l'échelle du système) :

curl --cacert ca.crt ...

Playwright / Node.js :

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

Firefox : Préférences → Vie privée et sécurité → Afficher les certificats → Autorités → Importer ca.crt

Docker

Exécutez le proxy dans un conteneur — aucune installation locale de Go/Make requise.

1. Démarrer le proxy

Linux uniquement : le conteneur s'exécute en tant qu'utilisateur non privilégié (nonroot, UID 65532) et a besoin d'un accès en écriture au répertoire ./data qui contient le certificat/clé de la CA. Si ./data n'existe pas encore, Docker le crée automatiquement avec comme propriétaire root et sans accès en écriture pour les autres utilisateurs, de sorte que le conteneur échouera à générer la CA au premier lancement. Créez-le au préalable avec le bon propriétaire :

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

Non nécessaire sur Docker Desktop pour Mac/Windows — sa couche de montage de liaison (bind-mount) mappe automatiquement les propriétaires.

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

Cela construit l'image localement et démarre le conteneur. Au premier lancement, il génère le CA MITM et affiche :

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

Ou, pour exécuter directement l'image préconstruite sans cloner :

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 publie les deux ports sur 127.0.0.1 uniquement — la même exposition limitée à la boucle locale qu'une installation native (l'API de gestion n'a pas d'authentification, donc ne la changez pas en 0.0.0.0 sans ajouter votre propre contrôle d'accès).

2. Faire confiance au certificat CA

La CA est générée à l'intérieur du conteneur mais persistée dans ./data/ca.crt et ./data/ca.key sur l'hôte via le volume monté en bind, de sorte qu'elle survit aux redémarrages/reconstructions du conteneur. Faites-lui confiance exactement comme dans la configuration native ci-dessus, en pointant simplement vers ./data/ca.crt au lieu de ./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. Configurer

Modifiez config.docker.yaml (et non config.yaml — ce fichier est destiné à l'installation native) puis redémarrez :

docker compose restart

config.docker.yaml est identique à config.yaml, sauf que listen/mgmt_listen valent 0.0.0.0 (nécessaire pour que la publication de ports de Docker atteigne le processus — le 127.0.0.1 propre au conteneur est injoignable depuis l'hôte) et que ca_cert/ca_key pointent vers /data, le volume persistant. Voir Configuration ci-dessous pour tous les champs disponibles.

Raccourcis Makefile

Cible	Description
make docker-build	Construit l'image via docker compose build
make docker-run	Construit et démarre en arrière-plan
make docker-stop	Arrête et supprime le conteneur

Arrêt / nettoyage

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

Configuration