impersonate-proxy

English | 日本語 | 简体中文

وكيل MITM محلي يتيح لك التحكم في بصمات TLS (JA3/JA4)، وبصمات HTTP/2، وترتيب ترويسات HTTP، وUser-Agent، وترويسات عنوان IP المصدر — كل ذلك من ملف إعداد YAML واحد.

يتضمن إضافة 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

لينكس

غالبًا ما تكون نسخة 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، إلخ): استبدل 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. تشغيل الوسيط

لينكس فقط: تعمل الحاوية بمستخدم غير مميز (nonroot، UID 65532) وتحتاج إلى صلاحية كتابة على الدليل ./data الذي يحتفظ بشهادة CA ومفتاحها. إذا لم يكن ./data موجودًا بعد، فإن Docker ينشئه تلقائيًا مملوكًا لـ root دون صلاحية كتابة للمستخدمين الآخرين، لذا ستفشل الحاوية في توليد CA عند التشغيل الأول. أنشئه بالمالك الصحيح مسبقًا:

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

غير مطلوب على Docker Desktop لنظامي Mac/Windows — إذ تُعيد طبقة bind-mount الخاصة به تعيين الملكية تلقائيًا.

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 فقط — نفس التعرّض للواجهة المحلية فقط كما في التثبيت الأصلي (واجهة برمجة إدارة لا تملك مصادقة، لذا لا تغيّر هذا إلى 0.0.0.0 دون إضافة آلية التحكم بالوصول الخاصة بك).

2. الوثوق بشهادة CA

يتم إنشاء CA داخل الحاوية ولكن يتم حفظها بشكل دائم في ./data/ca.crt و ./data/ca.key على المضيف عبر وحدة التخزين المرتبطة، لذا تبقى بعد إعادة تشغيل/إعادة بناء الحاوية. وثّق بها تمامًا كما في الإعداد الأصلي أعلاه، مع الإشارة إلى ./data/ca.crt بدلاً من ./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 مطابق لـ config.yaml باستثناء أن listen/mgmt_listen هما 0.0.0.0 (وهو أمر مطلوب لكي يتمكن نشر المنافذ في Docker من الوصول إلى العملية على الإطلاق — إذ لا يمكن الوصول إلى 127.0.0.1 الخاص بالحاوية من المضيف) وأن ca_cert/ca_key يشيران إلى /data، وحدة التخزين الدائمة. راجع Configuration أدناه للاطلاع على جميع الحقول المتاحة.

اختصارات Makefile

الهدف	الوصف
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"