TLSClientProxy

TLSClientProxy

TLSClientProxy is a lightweight TLS proxy designed to help developers and researchers test and align their HTTPS client behavior with that of real browsers or mobile apps. It enables customizable TLS handshakes (JA3/JA4) to improve compatibility with strict endpoint configurations.

Navigation

• Choose the right plan for you
• What is TLS Fingerprint
• How to Use
  • Installation
    • Ready to use binaries
    • Compile from source
  • Usage
  • Validation
• Support
• Paid Consultations & Personal Help

Choose the right plan for you

Find a plan that best matches the scale you need for your application.

Binaries are free to use with an active NP Access Pass. Source code access with updates is available only to subscribers.

When a client connects to a server over HTTPS, it performs a TLS handshake. This handshake includes several details such as:

• Supported TLS versions (e.g. 1.2, 1.3)
• Cipher suites
• TLS extensions (like SNI, ALPN)
• Elliptic curves
• Compression methods

These details form a kind of “fingerprint” of the client — because different clients send different combinations, and these rarely match exactly.

• JA3: A method of fingerprinting clients using only the TLS Client Hello data. It hashes this information into a 32-character MD5 string.
• JA4: A newer version that extends JA3 and includes more behavioral data (e.g. TCP properties, order of headers).

Popular HTTP libraries like Guzzle, cURL, Requests, and even many headless browsers don’t mimic real devices closely.

By default we use x86_64 architecture on our Linux server and binary for that system placed in main repository directory as tlsclientproxy file. You can run it directly without any additional steps if you are using the same architecture.

Here’s a quick mapping of the most common OS outputs and what Go cross-compilation targets they correspond to:

If your architecture is not listed here, you can build the project from source as described below.

First of all you need to clone this repository to project directory on your server or local machine:

git clone https://github.com/mjcodebase/tlsclientproxy.git

Then you need to install Go version 1.22 or higher if you haven’t done it yet. You can find installation instructions on the official Go website.

To check your current Go version, run:

go version

To install Go on a Linux system, you can use the following commands:

sudo rm -rf /usr/local/go 
curl -OL https://go.dev/dl/go1.22.3.linux-amd64.tar.gz 
sudo tar -C /usr/local -xzf go1.22.3.linux-amd64.tar.gz 
export PATH=$PATH:/usr/local/go/bin 
echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.bashrc && source ~/.bashrc

Then you need to install Go dependencies:

cd tlsclientproxy 
go mod tidy

Finally, you can build the project:

go build -o tlsclientproxy

You can run the proxy with the following command to see the help message:

./tlsclientproxy -help

Usage: ./tlsclientproxy [flags]

You can use this tool to add a custom TLS fingerprint to your requests. By default all your requests sent to TLS fingerprint server should have X-Tls-Key and X-Tls-Url headers set.

Request headers:
  X-Tls-Key: <key> - Authentication key for TLS proxy (required)
  X-Tls-Url: <url> - Target URL for TLS connection (required) or use -endpoint flag to set it for all requests
  X-Tls-Proxy: <proxy> - Upstream proxy to use (optional) or use -proxy flag to set it for all requests
  X-Tls-Ja3: <key> - Custom JA3 Fingerprint (optional) or use -ja3 flag to set it for all requests

Flags:
  -bind string
        Address to listen on (host:port) (default "127.0.0.1:8383")
  -endpoint string
        Target URL for TLS connection (used to auto-detect JA3 if -ja3 is empty)
  -help
        Show all flags and usage information
  -ja3 string
        JA3 fingerprint to spoof
  -key string
        TLS Proxy authentication key
  -logs
        Enable logs with spoofing details
  -proxy string
        Upstream proxy to use
  -timeout int
        Request timeout in seconds (default 60)
  -ua string
        User-Agent string to spoof
  -version
        Show version and exit

To start the proxy, you need to specify the bind address and the key:

./tlsclientproxy -bind 127.0.0.1:8383 -key 7dcc41dd-fbf3-4026-97c7-8d47b47515ec

• if you will not specify the -bind address and -key, the proxy will listen on 127.0.0.1:8383 and will use the default key 7dcc41dd-fbf3-4026-97c7-8d47b47515ec
• if you will not specify the -endpoint, the proxy will use the X-Tls-Url header from the request to determine the target URL

Validation

You can use an online tool to validate your TLS fingerprint: https://check.ja3.zone

Without the proxy, you can run the following command to see your current TLS fingerprint:

curl -s https://check.ja3.zone | jq
{
  "hash": "900e66af9af55f6d4bec4bfd2f79423c",
  "fingerprint": "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49161-49171-49162-49172-156-157-47-53-10,0-23-65281-10-11-16-13-51-45-43-21,29-23-24,0",
  ...
  "user_agent": "curl/8.1.0-DEV"
}

Now start tlsclientproxy and run the same command again:

./tlsclientproxy

curl -s 127.0.0.1:8383 -H "X-Tls-Key: 7dcc41dd-fbf3-4026-97c7-8d47b47515ec" -H "X-Tls-Url: https://check.ja3.zone" | jq
{
  "hash": "b76d503360ae441d410a85a7f8d648ab",
  "fingerprint": "771,4865-4866-4867-49196-49195-52393-49200-49199-52392-49162-49161-49172-49171,0-23-65281-10-11-16-5-13-18-51-45-43-27-21,29-23-24-25,0",
  ...
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"
}

If you want to see the logs with the spoofing details, you can run the proxy with the -logs flag:

./tlsclientproxy -logs 1
2025/07/29 16:33:41 Up and running! Listening on 127.0.0.1:8383
2025/07/29 16:34:51 No JA3 preset found for host check.ja3.zone and no --ja3 provided, using default
2025/07/29 16:34:51 Proxying request to https://check.ja3.zone with JA3=771,4865-4866-4867-49196-49195-52393-49200-49199-52392-49162-49161-49172-49171,0-23-65281-10-11-16-5-13-18-51-45-43-27-21,29-23-24-25,0

This is a developer’s portal and should not be used for support. Please contact us via website chat if you need to submit a support request.

Please contact us via website chat if you need additional help with your own project, we will try to find best options for you.