ja4proxy 0.5.0

       _       __ __                             
      (_)___ _/ // / ____  _________  _  ____  __
     / / __ `/ // /_/ __ \/ ___/ __ \| |/_/ / / /
    / / /_/ /__  __/ /_/ / /  / /_/ />  </ /_/ / 
 __/ /\__,_/  /_/ / .___/_/   \____/_/|_|\__, /  
/___/            /_/                    /____/   

Table of Contents

• The Fingerprinting Problem
• How ja4proxy Works
• Architecture & Protocol Pipeline
• Comparative Analysis
• Key Specifications
• Installation
• Quick Start
• Multi-Language Client Integration
  • Python (requests, httpx, aiohttp)
  • Node.js (axios, undici, fetch)
  • Go (net/http)
  • Rust (reqwest)
  • Scrapy Framework
• Dynamic Per-Request Directives
  • Via Proxy Credentials (Tag Routing)
  • Via Custom Request Headers
• Residential Proxy Chaining
• Supported Browser Presets
• Production Deployment
  • Docker & Docker Compose
  • Systemd Service Unit
  • System-Wide CA Trust Installation
• Security & Engineering Boundaries
• CLI Reference
• Automated Verification Suite
• License

The Fingerprinting Problem

Modern anti-bot mitigation platforms (Cloudflare Turnstile / Bot Management, Akamai Edge Workers, Imperva, Datadome, Kasada) no longer rely solely on IP reputation. Instead, automated scrapers and bots are blocked at Layer 7 by inspecting client-side protocol artifacts during the connection handshake:

Layer 7 Defense Hierarchy
├── 1. TLS ClientHello Fingerprinting (JA3 / JA4)
│      ├── Cipher suites order & availability
│      ├── Extension list & GREASE (RFC 8701) injection
│      ├── Elliptic curve groups & signature algorithms
│      └── ALPN (Application-Layer Protocol Negotiation)
├── 2. HTTP/2 Transport Fingerprinting (Akamai HTTP2 Hash)
│      ├── SETTINGS frame parameters (HEADER_TABLE_SIZE, MAX_CONCURRENT_STREAMS)
│      ├── WINDOW_UPDATE increments
│      ├── Pseudo-header serialization order (:method, :authority, :scheme, :path)
│      └── Priority trees and frame dependency graphs
└── 3. Layer 7 HTTP Header Consistency
       ├── Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform
       └── User-Agent string alignment with actual cryptographic capabilities

Standard networking stacks (OpenSSL in Python urllib3, Go crypto/tls, Node.js tls) expose hard-coded, static handshakes that immediately flag requests as non-browser traffic.

Fingerprint Breakdown: OpenSSL vs. ja4proxy (Chrome 133)

How ja4proxy Works

ja4proxy is an in-process, high-concurrency forward proxy. Rather than forwarding raw TCP sockets (which passes through your runtime's detectable OpenSSL handshake), ja4proxy terminates client requests locally and re-originates the upstream connection using an in-process uTLS and fhttp engine written in Go.

Any Existing Client Application
(cURL / requests / Scrapy / Playwright / Node / Go / Rust)
                           │
       HTTP CONNECT / Plain HTTP / SOCKS5 binary
                           │
                           ▼
┌────────────────────────────────────────────────────────────────────────┐
│ ja4proxy Runtime (127.0.0.1:8888)                                      │
│                                                                        │
│  [Ingress Sniffer] -> Auto-detects protocol by magic byte:             │
│                       - 0x05 (SOCKS5 RFC 1928)                         │
│                       - CONNECT host:443 (HTTPS Tunnel)                │
│                       - GET / POST / http://... (HTTP Gateway)         │
│                                                                        │
│  [Directive Parser] -> Extracts profile, session, upstream proxy:      │
│                        - Via credential tags: user-profile_chrome133   │
│                        - Via custom headers: X-JA4-Profile             │
│                                                                        │
│  [SSRF Guard] -> Validates target IP against private/loopback CIDRs    │
│                                                                        │
│  [TLS Interceptor] -> Generates dynamic in-memory SAN leaf certs       │
│                                                                        │
│  [Native Zero-GIL FFI] -> Dispatches request into Go uTLS engine       │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
              Outbound: Real Chrome 133 JA4 + HTTP/2 Multiplexing
                                    │
                                    ▼
                      Upstream Target (WAF / Protected Host)

Architecture & Protocol Pipeline

1. Single-Port Protocol Sniffing

ja4proxy binds to a single port and inspects the initial byte stream using non-destructive socket inspection:

• Byte 0x05: Dispatches to the binary SOCKS5 state machine (RFC 1928), negotiating NO AUTH or USERNAME/PASSWORD before taking target host and port.
• ASCII CONNECT: Intercepts HTTPS tunnels, performs an SSL handshake using dynamic per-hostname leaf certificates signed on-the-fly by the local CA, and decrypts request bytes.
• ASCII GET / POST / HEAD: Handles standard forward proxy requests or gateway URLs (http://127.0.0.1:8888/https://example.com).

2. Zero-GIL Native C-Shared FFI

Python manages client I/O asynchronously via asyncio. When dispatching outbound HTTP/TLS requests, ja4proxy calls into libutls through ctypes. The Python Global Interpreter Lock (GIL) is released during socket creation, cryptographic handshakes, and body streaming.

3. Memory Hygiene & Free Routine

Native C allocations returned by the Go runtime are wrapped in a structured memory protocol. Once response headers and body buffers are consumed in Python, freeMemory is explicitly invoked over the C pointer, preventing memory leaks across long-running proxy processes.

Comparative Analysis

Key Specifications

• Listen Protocols: HTTP Gateway, HTTP CONNECT, SOCKS5 (RFC 1928) on a single port.
• TLS Engine: uTLS with randomized GREASE (RFC 8701) and custom extension order permutations.
• HTTP Engine: fhttp with browser-matched HTTP/2 SETTINGS framing and pseudo-header ordering.
• Certificate Authority: 2048-bit RSA Root CA (ca.pem) with automatic in-memory leaf certificate generation and Subject Alternative Name (SAN) caching.
• Security Boundary: Pre-flight connection-time SSRF blocking for RFC 1918 private subnets, loopback, and cloud metadata (169.254.169.254).
• Decompression Sync: Automatic header reconciliation (Content-Encoding, Content-Length) to prevent client decoder desync.

Installation

Via Source

git clone https://github.com/cipherwire/ja4proxy.git
cd ja4proxy
pip install .

Via Docker

docker build -t ja4proxy .
docker run -d -p 8888:8888 --name ja4proxy ja4proxy

Quick Start

1. Launch the Server

ja4proxy start --host 127.0.0.1 --port 8888 --profile chrome_133

Output:

[*] ja4proxy v0.1.0 starting on http://127.0.0.1:8888
[*] Default Profile: chrome_133
[*] Protocols Supported: HTTP CONNECT, HTTP Gateway, SOCKS5 (Auto-detect)
[*] CA Certificate: C:\Users\AnonNp\.ja4proxy\ca.pem
[*] Ready for HTTP and SOCKS5 clients

2. Export the Root CA

Export the root certificate so your HTTP client can verify intercept certificates without disabling SSL verification:

ja4proxy ca --export ./ca.pem

3. Verify TLS Handshake Against tls.peet.ws

Using HTTP CONNECT:

curl -x http://127.0.0.1:8888 --cacert ./ca.pem https://tls.peet.ws/api/all

Using SOCKS5 (Identical Port):

curl -x socks5h://127.0.0.1:8888 --cacert ./ca.pem https://tls.peet.ws/api/all

Using Gateway Mode (No CA certificate required):

curl http://127.0.0.1:8888/https://tls.peet.ws/api/all

Verified output from tls.peet.ws:

{
  "http_version": "h2",
  "tls": {
    "ja4": "t13d1516h2_8daaf6152771_d8a2da3f94cd",
    "ja3": "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-21,29-23-24,0"
  }
}

Multi-Language Client Integration

Python (requests, httpx, aiohttp)

requests

import os
import requests

ca_cert = os.path.expanduser("~/.ja4proxy/ca.pem")
proxies = {
    "http": "http://127.0.0.1:8888",
    "https": "http://127.0.0.1:8888",
}

# Standard requests call immediately adopts Chrome 133 JA4 fingerprint
res = requests.get("https://tls.peet.ws/api/all", proxies=proxies, verify=ca_cert)
print("JA4:", res.json()["tls"]["ja4"])

httpx (Async with SOCKS5)

import asyncio
import os
import httpx

async def main():
    ca_cert = os.path.expanduser("~/.ja4proxy/ca.pem")
    async with httpx.AsyncClient(
        proxy="socks5://127.0.0.1:8888",
        verify=ca_cert,
    ) as client:
        res = await client.get("https://tls.peet.ws/api/all")
        print("JA4:", res.json()["tls"]["ja4"])

asyncio.run(main())

Node.js (axios, undici, fetch)

axios

const axios = require('axios');
const fs = require('fs');
const https = require('https');

const ca = fs.readFileSync('./ca.pem');
const httpsAgent = new https.Agent({ ca });

axios.get('https://tls.peet.ws/api/all', {
  proxy: { host: '127.0.0.1', port: 8888 },
  httpsAgent: httpsAgent
}).then(res => {
  console.log('JA4:', res.data.tls.ja4);
});

Native Node fetch (with undici)

import { fetch, ProxyAgent } from 'undici';
import fs from 'fs';

const client = new ProxyAgent({
  uri: 'http://127.0.0.1:8888',
  requestTls: { ca: fs.readFileSync('./ca.pem') }
});

const res = await fetch('https://tls.peet.ws/api/all', { dispatcher: client });
const json = await res.json();
console.log('JA4:', json.tls.ja4);

Go (net/http)

package main

import (
	"crypto/x509"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
)

func main() {
	caCert, _ := os.ReadFile("ca.pem")
	caCertPool := x509.NewCertPool()
	caCertPool.AppendCertsFromPEM(caCert)

	proxyURL, _ := url.Parse("http://127.0.0.1:8888")
	transport := &http.Transport{
		Proxy: http.ProxyURL(proxyURL),
		TLSClientConfig: &tls.Config{
			RootCAs: caCertPool,
		},
	}

	client := &http.Client{Transport: transport}
	resp, err := client.Get("https://tls.peet.ws/api/all")
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

Rust (reqwest)

use reqwest::{Certificate, Client, Proxy};
use std::fs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cert_bytes = fs::read("ca.pem")?;
    let cert = Certificate::from_pem(&cert_bytes)?;
    
    let proxy = Proxy::all("http://127.0.0.1:8888")?;
    let client = Client::builder()
        .proxy(proxy)
        .add_root_certificate(cert)
        .build()?;

    let res = client.get("https://tls.peet.ws/api/all").send().await?;
    println!("Response: {}", res.text().await?);
    Ok(())
}

Scrapy Framework

In your Scrapy project's settings.py:

# Enable standard HTTP proxy middleware
DOWNLOADER_MIDDLEWARES = {
    'scrapy.downloadermiddlewares.httpproxy.HttpProxyMiddleware': 750,
}

# Route all traffic through ja4proxy with Safari 18 profile
HTTP_PROXY = "http://user-profile_safari18:nopass@127.0.0.1:8888"
REQUESTS_CA_BUNDLE = "/path/to/ca.pem"

Dynamic Per-Request Directives

ja4proxy allows you to customize the browser profile, session pool, or upstream routing on a granular per-request basis without restarting the server.

Via Proxy Credentials (Tag Routing)

Pass directives directly inside the proxy username string formatted as tag_value:

Format:
http://[user]-profile_<profile>-session_<id>-proxy_<upstream_url>:[password]@127.0.0.1:8888

Examples:

1. Switch to Safari 18:

   curl -x "http://user-profile_safari18:pass@127.0.0.1:8888" --cacert ./ca.pem https://tls.peet.ws/api/all
   

2. Maintain a Sticky Session Pool:

   curl -x "http://user-profile_chrome133-session_worker12:pass@127.0.0.1:8888" --cacert ./ca.pem https://target.com
   

3. Chain Out to an Upstream SOCKS5 Proxy:

   curl -x "http://user-profile_chrome133-proxy_socks5://resuser:respass@residential.net:1080:pass@127.0.0.1:8888" --cacert ./ca.pem https://target.com
   

Via Custom Request Headers

When connecting via plain HTTP gateway or custom client hooks, pass directives as standard headers:

Residential Proxy Chaining

ja4proxy acts as a TLS and protocol transformer. You can position ja4proxy locally on your server or laptop, while routing the actual egress IP through your existing residential or datacenter proxy network:

Client -> ja4proxy (Applies Chrome 133 JA4 + HTTP/2) -> Upstream Residential IP -> Cloudflare

To configure global upstream forwarding at startup:

ja4proxy start --port 8888 --upstream-proxy "http://username:password@residential-provider.com:8000"

Or dynamically per request:

import requests

proxies = {
    # Dynamically inject residential upstream via tag syntax
    "https": "http://user-proxy_http://resuser:respass@gate.io:8000:pass@127.0.0.1:8888"
}

res = requests.get("https://api.ipify.org?format=json", proxies=proxies, verify="ca.pem")
print("Egress IP:", res.json()["ip"])

Supported Browser Presets

Run ja4proxy profiles to list all supported profiles:

Production Deployment

Docker & Docker Compose

docker-compose.yml

version: '3.8'

services:
  ja4proxy:
    image: ja4proxy:latest
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ja4proxy
    restart: unless-stopped
    ports:
      - "8888:8888"
    volumes:
      - ja4proxy_certs:/root/.ja4proxy
    environment:
      - JA4PROXY_PORT=8888
      - JA4PROXY_PROFILE=chrome_133
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:8888/https://httpbin.org/status/200"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  ja4proxy_certs:

Launch with:

docker compose up -d

Systemd Service Unit

Create /etc/systemd/system/ja4proxy.service:

[Unit]
Description=ja4proxy TLS & HTTP/2 Impersonation Proxy
After=network.target

[Service]
Type=simple
User=proxyuser
WorkingDirectory=/opt/ja4proxy
ExecStart=/usr/local/bin/ja4proxy start --host 0.0.0.0 --port 8888 --profile chrome_133
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now ja4proxy

System-Wide CA Trust Installation

To use ja4proxy transparently without passing --cacert or verify=... in your scripts:

Debian / Ubuntu

ja4proxy ca --export /tmp/ja4proxy-ca.crt
sudo cp /tmp/ja4proxy-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

macOS

ja4proxy ca --export /tmp/ja4proxy-ca.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/ja4proxy-ca.crt

Windows (PowerShell Administrator)

ja4proxy ca --export "$env:TEMP\ja4proxy-ca.crt"
certutil -addstore -f "Root" "$env:TEMP\ja4proxy-ca.crt"

Security & Engineering Boundaries

1. Pre-Flight SSRF Protection: ja4proxy resolves hostnames prior to outbound dispatch and drops requests resolving to private address spaces (RFC 1918 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback (127.0.0.0/8, ::1), and cloud metadata (169.254.169.254). Internal forwarding can be enabled with --allow-private-networks.

2. Decompression & Content-Length Sync: The native Go engine decodes gzip/brotli/deflate responses transparently. ja4proxy strips stale Content-Encoding and Transfer-Encoding headers and recalculates accurate Content-Length before serving downstream, preventing double-decompression exceptions.

3. Header Sanitization: Incoming client hop-by-hop headers (Proxy-Connection, Keep-Alive, Te) and automated OpenSSL/Python identifiers are stripped. Canonical browser headers (User-Agent, Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform) matching the selected profile are automatically synthesized when missing.

4. Zero-GIL Execution: Native C FFI functions execute outside Python's GIL. Concurrency scales across available CPU cores and network threads without interpreter bottlenecks.

CLI Reference

Usage: ja4proxy [OPTIONS] COMMAND [ARGS]...

  ja4proxy: High-performance universal forward proxy server with browser TLS (JA4)
  and HTTP/2 impersonation.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  ca        Inspects or exports the local Root CA certificate.
  profiles  Lists all supported browser profiles for TLS and HTTP/2.
  start     Starts the ja4proxy server.
  test      Performs a direct live handshake against tls.peet.ws.

ja4proxy start Flags

Automated Verification Suite

Run the full automated test suite covering CA generation, SOCKS5 state machines, chunked request decoding, SSRF guards, and live upstream verification against tls.peet.ws and httpbin.org:

python -m unittest discover -s tests -p "test_*.py" -v

All 19 unit and live tests execute with zero warnings and zero regressions:

test_ca_creation (test_certs.TestCertificateAuthority) ... ok
test_leaf_cert_generation (test_certs.TestCertificateAuthority) ... ok
test_leaf_cert_ip_address (test_certs.TestCertificateAuthority) ... ok
test_live_handshake_chrome (test_engine.TestNativeEngine) ... ok
test_live_post_httpbin (test_engine.TestNativeEngine) ... ok
test_bad_gateway_mapping_status_502 (test_live_proxy.TestLiveProxy) ... ok
test_chunked_request_upload (test_live_proxy.TestLiveProxy) ... ok
test_client_proxy_authentication (test_live_proxy.TestLiveProxy) ... ok
test_connect_tls_handshake_timeout (test_live_proxy.TestLiveProxy) ... ok
test_gateway_mode_gzip (test_live_proxy.TestLiveProxy) ... ok
test_safari_ios_headers (test_live_proxy.TestLiveProxy) ... ok
test_socks5_ingress_tls_peet (test_live_proxy.TestLiveProxy) ... ok
test_ssrf_protection_blocked (test_live_proxy.TestLiveProxy) ... ok
test_ssrf_restricted_addresses (test_live_proxy.TestLiveProxy) ... ok
test_extract_directives_from_headers (test_parser.TestParser) ... ok
test_extract_directives_priority_header_over_auth (test_parser.TestParser) ... ok
test_parse_credentials_empty (test_parser.TestParser) ... ok
test_parse_credentials_proxy_with_hyphens (test_parser.TestParser) ... ok
test_parse_credentials_tags (test_parser.TestParser) ... ok

----------------------------------------------------------------------
Ran 19 tests in 6.421s

OK

License

MIT License. Designed and engineered by cipherwire / hainahola.