tlsforge

TLS Forge

tls-forge is an HTTP client and command-line tool for making requests with a real browser's network fingerprint. A measured profile controls the TLS ClientHello, JA3/JA4-relevant fields, HTTP/1.1 header casing and order, HTTP/2 settings, pseudo-header order, regular header order and browser headers as one coherent identity. Profiles created before HTTP/1.1 capture was introduced remain compatible and use the documented canonical-casing fallback.

Use it when an ordinary Go, Node.js or Python HTTP client is rejected because its network stack does not match the browser named by its User-Agent. tls-forge can be used as:

• a standalone CLI for one request or a batch;
• an intercepting proxy for an existing program;
• a Go library;
• a Node.js or Python SDK backed by the same Go transport;
• a local measurement tool for capturing and comparing browser fingerprints.

It does not execute page JavaScript and does not solve managed challenges or CAPTCHAs. It addresses the TLS and HTTP fingerprint checks that happen before, or alongside, normal HTTP handling.

What is a TLS fingerprint?

Before an HTTPS client can send GET, headers or a User-Agent, it sends a TLS ClientHello. That message exposes choices made by its networking stack, including:

• supported TLS versions and cipher suites;
• extensions and their order;
• supported groups, key shares and signature algorithms;
• GREASE values and ALPN protocols;
• session-resumption and application-settings behaviour.

Servers can retain the complete structure or reduce it to identifiers such as JA3 and JA4. The negotiated HTTP protocol adds more signals: exact HTTP/1.1 header casing and order, or HTTP/2 SETTINGS, window updates, pseudo-header order, normal header order and values.

Changing only User-Agent is therefore insufficient. Node.js and Python normally use OpenSSL, Go uses crypto/tls, while Chrome uses BoringSSL. Their handshakes differ before the server sees any HTTP header.

Cloudflare uses these signals in its bot-detection products. Cloudflare Bot Management exposes JA3 and JA4 fingerprints as request fields that can be used in WAF custom rules, Transform Rules and Workers; see Cloudflare's official JA3/JA4 fingerprint documentation.

The profiles in this project are measurements, not hand-written guesses. tls-forge compare measures a real browser and this client against the same local echo server and reports every difference it finds.

Install

A Chromium-based browser is required only for capture and compare. Fetching, batch processing, proxying and the language SDKs do not require a browser.

Release binary

Prebuilt binaries are published for macOS and Linux on arm64 and x86-64, and Windows on x86-64. Download the archive for your platform from GitHub Releases, extract it and place tls-forge (or tls-forge.exe) on PATH.

On Unix-like systems, a user-local installation can look like this:

mkdir -p ~/.local/bin
install -m 0755 tls-forge ~/.local/bin/tls-forge
tls-forge version

Homebrew

On macOS or Linux:

brew tap Sec-CH-Lemon/tap
brew trust --formula Sec-CH-Lemon/tap/tls-forge
brew install Sec-CH-Lemon/tap/tls-forge

Homebrew requires explicit trust for third-party taps. Review the tap before granting it.

Go install

With Go 1.26.7 or newer:

go install github.com/Sec-CH-Lemon/tls-forge/cmd/tls-forge@latest

The binary is written to $(go env GOPATH)/bin unless GOBIN is set.

Docker

Release images are published for linux/amd64 and linux/arm64:

docker pull ghcr.io/sec-ch-lemon/tls-forge
docker run --rm ghcr.io/sec-ch-lemon/tls-forge \
  fetch https://tls.browserleaks.com/json

Mount a directory when a command reads or writes files:

docker run --rm -v "$PWD:/work" ghcr.io/sec-ch-lemon/tls-forge \
  batch --input /work/urls.csv --output /work/results.jsonl

capture and compare are intentionally not supported by the small release image because it does not contain a browser.

Build from source

Requirements:

• Go 1.26.7 or newer;
• Git and Make for the standard build command;
• no C compiler or cgo.

git clone https://github.com/Sec-CH-Lemon/tls-forge.git
cd tls-forge
make build
./bin/tls-forge version

make build writes bin/tls-forge and stamps its version from git describe. Without Make:

go build -o tls-forge ./cmd/tls-forge
./tls-forge version

A plain go build reports version dev, because release versions are supplied through linker flags. A release-style static build is:

CGO_ENABLED=0 go build -trimpath \
  -ldflags "-s -w -X main.version=v0.1.0" \
  -o tls-forge ./cmd/tls-forge

Go can cross-compile the project without an external toolchain:

CGO_ENABLED=0 GOOS=linux GOARCH=arm64 \
  go build -o tls-forge-linux-arm64 ./cmd/tls-forge

CGO_ENABLED=0 GOOS=windows GOARCH=amd64 \
  go build -o tls-forge.exe ./cmd/tls-forge

To build the container image:

docker build -t tls-forge .
docker run --rm tls-forge version

Run all project checks before distributing a build:

make check

Verify the fingerprint

If a Chromium-based browser is installed, start with:

tls-forge compare

The command measures the browser and the selected profile locally, then compares TLS, JA4, HTTP/2 settings, header order and header values. A matching result is stronger than checking only a JA3 or JA4 hash.

Commands

tls-forge <command> [flags]

Run tls-forge <command> --help for generated command help. Durations use Go syntax such as 500ms, 30s or 2m.

When no profile is selected, the network commands (fetch, batch, proxy and daemon) use a profile installed as local, if one exists, and otherwise the latest bundled chrome profile. compare defaults to the bundled chrome family so it can detect drift instead of comparing a fresh local measurement with itself. Use tls-forge profiles to see the exact names available on the machine.

fetch

Make one request and write its decompressed body to standard output.

tls-forge fetch https://example.com/
tls-forge fetch -i -H "Accept-Language: en-US" https://example.com/
tls-forge fetch -X POST -H "Content-Type: application/json" \
  -d '{"hello":"world"}' https://example.com/api

Usage: tls-forge fetch [flags] <url>

Cookie files are treated as credentials and saved with mode 0600. JSON files can retain multiple named sessions; Netscape .txt files contain one jar and are compatible with tools such as curl and wget.

batch

Fetch a list concurrently and emit one JSON object per URL. Results go to stdout or --output; progress and summaries go to stderr, so the JSON Lines stream remains machine-readable.

tls-forge batch https://example.com/ https://example.org/
tls-forge batch --input example/urls.csv --concurrency 8
tls-forge batch --input urls.json --output results.jsonl --report reports/

Usage: tls-forge batch [flags] [urls...]

Input precedence is --urls, then --input, then positional URLs, then stdin. When an inline response body is not valid UTF-8, body is base64 and the row contains "body_encoding":"base64"; bytes always remains the original byte count. --body-dir writes the original bytes directly instead. Repeated URLs in one input get separate, stable body filenames. With --format auto, .json selects JSON, .csv selects CSV and every other name uses one URL per line.

Supported list shapes:

# lines: URL followed by an optional proxy
https://example.com/ http://user:pass@proxy.example:8080

[
  "https://example.com/",
  {"url": "https://example.org/", "proxy": "socks5://proxy.example:1080"}
]

url,proxy
https://example.com/,http://user:pass@proxy.example:8080
https://example.org/,

The command creates one client and cookie jar per distinct proxy. A batch exits non-zero when one or more URLs fail.

Runnable CLI and SDK examples, with complete sample inputs and outputs, are in example/.

capture

Open an installed Chromium-based browser, record its TLS and HTTP behaviour and optionally save a reusable profile. HTTP/1.1 and HTTP/2 are measured as two independent cold top-level navigations, each using a fresh temporary browser profile, so the transition between protocols cannot alter Sec-Fetch-*.

tls-forge capture
mkdir -p profiles && tls-forge capture --save profiles/
tls-forge capture --browser edge --headless --save edge.json
tls-forge capture --install

Usage: tls-forge capture [flags]

Installed profiles live below the operating system's user configuration directory. Set TLSFORGE_PROFILES to choose another directory. Running capture --install again replaces the local machine profile after a browser update.

compare

Measure an installed browser and the selected client profile against the same local server, then print a field-by-field diff.

The browser is measured over both HTTP/1.1 and HTTP/2. HTTP/1.1 names are compared with their exact wire casing; HTTP/2 remains lower-case as required by the protocol. Profiles that predate the optional HTTP/1.1 section continue to work with the historical fallback.

tls-forge compare
tls-forge compare --profile chrome_151 --headless
tls-forge compare --json > comparison.json

Usage: tls-forge compare [flags]

Exit codes are meaningful:

profiles

List profiles from the local profile directory, profiles embedded in this binary and compatible profiles from the underlying transport catalogue.

tls-forge profiles

Usage: tls-forge profiles. This command has no flags.

Profile names can be passed to --profile. A JSON profile path is also accepted directly:

tls-forge fetch --profile ./profiles/my-chrome.json https://example.com/

proxy

Run an intercepting HTTP/HTTPS proxy. It terminates incoming TLS and creates a new outbound connection with the selected browser fingerprint. A normal CONNECT tunnel cannot replace a fingerprint because it passes the caller's TLS bytes through unchanged.

tls-forge proxy
export HTTPS_PROXY=http://127.0.0.1:8080
curl --proxy http://127.0.0.1:8080 \
  --cacert "/path/printed/by/tls-forge" https://example.com/

The command prints the exact certificate path. Its default follows the OS user config directory: usually ~/.config/tls-forge/ca.pem on Linux, ~/Library/Application Support/tls-forge/ca.pem on macOS, and %AppData%\tls-forge\ca.pem on Windows.

Usage: tls-forge proxy [flags]

The proxy deliberately has no cookie jar; it forwards the caller's Cookie header. The generated CA can impersonate any site to a client that trusts it. Prefer trusting it only for the specific process, keep the private key secret, and remove that trust when the proxy is no longer needed. The proxy does not authenticate incoming clients: a non-loopback --addr must be protected by a firewall or authenticated tunnel. The certificate and key must either both exist and match or both be absent. Incoming connections expire after 30 seconds without any read or write progress, and the generated leaf-certificate cache is limited to 1024 hostnames.

serve

Run the local HTTPS measurement server independently. / contains the browser capture page; /api/all returns the current connection's TLS and HTTP fingerprint as JSON.

tls-forge serve
tls-forge serve --addr 0.0.0.0:8443
curl -k https://localhost:8443/api/all

Usage: tls-forge serve [flags]

The certificate is generated for each run, so test clients must trust it or explicitly disable verification for this local endpoint. The server does not authenticate incoming clients; the CLI warns when --addr exposes it beyond loopback. A connection that makes no read or write progress for 30 seconds is closed.

daemon

Run one long-lived client behind a JSON Lines protocol. This is the transport used by the Node.js and Python SDKs.

echo '{"id":1,"url":"https://example.com/"}' | tls-forge daemon

Usage: tls-forge daemon [flags]

One request object is read per line:

{"id":1,"method":"POST","url":"https://example.com/api","headers":{"content-type":"application/json"},"order":["content-type"],"body":"{\"a\":1}","setCookie":["session=abc"]}

The response repeats id and contains status, final url, body, multi-valued headers, cookies, and error when the request failed. Input lines are limited to 16 MiB. Requests are processed sequentially so one daemon remains one browser identity and one cookie jar.

version

Print the version stamped into the binary:

tls-forge version

Usage: tls-forge version. This command has no flags. A source build without version linker flags reports dev.

Language libraries

The root README intentionally contains only a working introduction for each SDK. Every language has its own detailed API document with all constructor and request options, response fields, lifecycle rules and failure behaviour.

Go

go get github.com/Sec-CH-Lemon/tls-forge

package main

import (
	"fmt"
	"log"

	tlsforge "github.com/Sec-CH-Lemon/tls-forge"
)

func main() {
	client, err := tlsforge.New(tlsforge.WithProfile("chrome"))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	res, err := client.Get("https://tls.browserleaks.com/json")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(res.Status, res.Text())
}

See the complete Go library documentation. The runnable consumer project is in example/go/.

Node.js

npm install tls-forge

import { Client } from 'tls-forge';

const client = new Client({ profile: 'chrome' });
try {
  const res = await client.get('https://tls.browserleaks.com/json');
  console.log(res.status, res.body);
} finally {
  client.close();
}

See the complete Node.js SDK documentation. The runnable consumer project is in example/node/.

Python

pip install tls-forge

import tlsforge

with tlsforge.Client(profile="chrome") as client:
    response = client.get("https://tls.browserleaks.com/json")
    print(response.status, response.json())

See the complete Python SDK documentation. The runnable consumer project is in example/python/.

Development

make test         # Go race tests
make cover        # 100% Go statement coverage gate
make node-test    # 100% Node line/function/branch coverage gate
make python-test  # 100% Python statement/branch coverage gate
make wrapper-smoke # Node and Python against the real Go daemon
make vet
make lint
make check        # all of the above

Release and maintenance documentation:

• CHANGELOG.md — user-visible changes;
• RELEASING.md — release process;
• docs/article.ru.md — Russian introduction to TLS fingerprinting and TLS Forge;
• docs/profiles.md — capture format and profile resolution;
• docs/protocol.md — JSON Lines daemon protocol;
• example/ — runnable Go, Node.js, Python and CLI examples.

Licence and attribution

The project is licensed under the Apache License 2.0. Redistributed source or binaries must retain the required licence and attribution notices described by that licence.

• NOTICE contains the project's copyright and attribution notice.
• THIRD-PARTY-NOTICES.txt contains licences and notices for dependencies linked into distributed binaries.

The captured ClientHello and browser profile fixtures are measurements of Chrome's protocol output; they do not contain Chrome source code. The project is not affiliated with or endorsed by Google or Cloudflare.

Use the software only on systems and traffic you are authorised to access.