tlsc

High-performance HTTP client with TLS fingerprint spoofing for Go

Installation • Quick Start • Features • Profiles • Performance • Benchmarks

tlsc makes HTTP requests that are indistinguishable from real browsers by spoofing TLS fingerprints (JA3/JA4), HTTP/2 fingerprints (Akamai), and HTTP/3 QUIC transport parameters. It's designed for web scraping, API access, and any scenario where you need to bypass bot detection.

Installation

go get github.com/Phrasing/tlsc@latest

Quick Start

package main

import (
    "context"
    "fmt"
    "io"
    "time"

    "github.com/Phrasing/tlsc/pkg/client"
)

func main() {
    // Create a client with Chrome fingerprint (default)
    c := client.New()

    resp, err := c.Get(context.Background(), "https://tls.peet.ws/api/all")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

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

Features

• TLS Fingerprint Spoofing: Mimics Chrome, Firefox, and Safari TLS handshakes
• HTTP/2 Fingerprinting: Matches browser HTTP/2 settings, priorities, and header order
• HTTP/3 Support: QUIC transport with browser-like parameters and auto-fallback to HTTP/2
• HTTP/1.1 Header Ordering: Preserves header order to match browser behavior
• High Performance: Optimized for throughput with connection pooling and minimal allocations
• Cookie Management: Automatic cookie jar with thread-safe storage
• Proxy Support: HTTP CONNECT and SOCKS5 proxy support
• DNS Caching: Optional DNS cache for faster repeated connections
• Benchmark Suite: Docker-based benchmarking with fingerprint validation

Browser Profiles

Chrome 143 (Default)

c := client.New() // Uses Chrome 143 by default
// or explicitly:
c := client.Chrome143Client()

Firefox 146

c := client.Firefox146Client()
// or:
c := client.New(client.WithProfile(profile.Firefox146()))

Safari 26.1

c := client.Safari261Client()
// or:
c := client.New(client.WithProfile(profile.Safari261()))

Configuration Options

c := client.New(
    // Browser profile
    client.WithProfile(profile.Chrome143()),

    // Timeouts
    client.WithTimeout(30 * time.Second),
    client.WithIdleTimeout(90 * time.Second),

    // Connection limits
    client.WithMaxConnsPerHost(100),

    // Proxy (HTTP CONNECT)
    client.WithHTTPProxy("host:port"),
    client.WithHTTPProxy("host:port:user:pass"),

    // Proxy (SOCKS5)
    client.WithSOCKS5Proxy("host:port"),
    client.WithSOCKS5Proxy("host:port:user:pass"),

    // Cookie handling
    client.WithCookieJar(customJar),  // Custom jar
    client.WithNoCookies(),           // Disable cookies

    // DNS caching (reduces latency for repeated requests)
    client.WithDNSCache(5 * time.Minute),

    // Protocol selection
    client.WithHTTP1(),   // Force HTTP/1.1 (higher throughput, less fingerprint control)
    client.WithHTTP3(),   // Enable HTTP/3 with auto-fallback to HTTP/2

    // Skip TLS verification (testing only)
    client.WithInsecureSkipVerify(),

    // Header ordering (overrides browser profile)
    client.WithHeaderOrder([]string{"host", "user-agent", "accept", "accept-language"}),
    client.WithPseudoHeaderOrder([]string{":method", ":authority", ":scheme", ":path"}),
)

API Reference

Client Methods

// Standard HTTP methods
resp, err := c.Get(ctx, "https://example.com")
resp, err := c.Post(ctx, "https://example.com", "application/json", body)

// Generic request
resp, err := c.Do(ctx, httpRequest)

// Using transport.Request directly (lower overhead)
resp, err := c.DoRequest(ctx, &transport.Request{
    Method:  "GET",
    Host:    "example.com",
    Path:    "/api/data",
    Headers: map[string]string{"Accept": "application/json"},
})

// Metrics
stats := c.Stats() // Returns request count, error count, bytes received

// Cleanup
c.Close()

Cookie Jar

import "github.com/Phrasing/tlsc/pkg/cookie"

jar := cookie.New()

// Cookies are automatically managed, but you can also:
jar.SetCookies(url, cookies)
cookies := jar.Cookies(url)
jar.Clear()
jar.ClearHost("example.com")

Direct Transport Usage

For maximum control, use the transport directly:

import "github.com/Phrasing/tlsc/pkg/transport"

t := transport.NewTransport(transport.TransportConfig{
    Profile:         profile.Chrome143(),
    MaxConnsPerHost: 100,
    IdleTimeout:     90 * time.Second,
    Timeout:         30 * time.Second,
})

// Use as http.RoundTripper
httpClient := &http.Client{Transport: t}
resp, err := httpClient.Get("https://example.com")

Header Ordering

Control HTTP/1.1 header order and HTTP/2 pseudo-header order using magic header keys:

import "github.com/Phrasing/tlsc/pkg/http"

// Create a request with custom header order (HTTP/1.1)
req, _ := http.NewRequest("GET", "https://example.com", nil)
req.Header = http.Header{
    "Host":             {"example.com"},
    "User-Agent":       {"Mozilla/5.0 ..."},
    "Accept":           {"text/html"},
    "Accept-Language":  {"en-US"},
    "Accept-Encoding":  {"gzip, deflate, br"},

    // Magic key: specifies the order headers are written (lowercase)
    http.HeaderOrderKey: {"host", "user-agent", "accept", "accept-language", "accept-encoding"},
}

// For HTTP/2 pseudo-header order
req.Header[http.PHeaderOrderKey] = []string{":method", ":authority", ":scheme", ":path"}

Headers listed in HeaderOrderKey are written first in the specified order. Any headers not in the list are written afterward in alphabetical order. The HeaderOrderKey and PHeaderOrderKey entries are automatically excluded from the actual request.

Package Structure

github.com/Phrasing/tlsc/
├── pkg/
│   ├── client/      # High-level HTTP client
│   ├── transport/   # HTTP transport with fingerprinting (HTTP/1.1, HTTP/2, HTTP/3)
│   ├── profile/     # Browser fingerprint profiles (TLS, HTTP/2, HTTP/3)
│   ├── http/        # Forked net/http with header ordering
│   ├── tls/         # TLS dialer and QUIC dialer with fingerprint spoofing
│   ├── cookie/      # Thread-safe cookie jar
│   ├── dns/         # DNS caching
│   ├── log/         # Request/response logging
│   └── pool/        # Memory pooling utilities
├── examples/        # Usage examples
│   ├── http1/       # HTTP/1.1 high-throughput mode
│   ├── http2/       # HTTP/2 fingerprinting
│   ├── http3/       # HTTP/3 QUIC transport
│   ├── cookie-jar/  # Cookie management
│   ├── browser-profiles/  # Browser fingerprint switching
│   ├── header-ordering/   # Custom header order
│   └── logging/     # Request/response logging
├── benchmark/       # Docker-based benchmark suite
│   ├── oracle/      # Fingerprint validation server
│   ├── payload/     # Configurable response server
│   └── driver/      # Benchmark driver and metrics
└── internal/
    ├── constants/   # Browser-specific constants
    └── fork/        # Forked dependencies (utls, x/net)

Fingerprint Details

TLS Fingerprint (JA3/JA4)

Each profile includes:

• Cipher suites in browser-specific order
• TLS extensions with correct ordering
• Supported curves and point formats
• ALPN protocols

HTTP/2 Fingerprint (Akamai)

Each profile includes:

• SETTINGS frame values (header table size, window size, etc.)
• WINDOW_UPDATE frame size
• Pseudo-header order (:method, :authority, :scheme, :path)
• Header order for common headers

HTTP/3 Fingerprint (QUIC)

Each profile includes browser-specific QUIC transport parameters:

• Flow control windows (InitialMaxData, InitialMaxStreamData)
• Stream limits (InitialMaxStreamsBidi, InitialMaxStreamsUni)
• Connection settings (MaxIdleTimeout, ActiveConnectionIDLimit)
• HTTP/3 SETTINGS (QPACK table capacity, blocked streams)

Values captured from real browsers via browserleaks.com/quic.

HTTP/1.1 Header Order

The forked pkg/http package preserves header ordering for HTTP/1.1 requests, matching browser behavior exactly.

Performance

TLSC vs tls-client Comparison (Chrome 143 Profile)

Benchmarks run with Docker-based payload server:

HTTP/2:

HTTP/2 performance is comparable - both libraries use similar forked http2 transports.

HTTP/1.1:

TLSC significantly outperforms in HTTP/1.1 mode with better latency (p99: 12ms vs 36ms) and fewer allocations (67 vs 115 allocs/req).

Benchmarks

The benchmark suite includes Docker-based infrastructure for accurate testing:

# Start benchmark infrastructure
docker compose -f benchmark/docker-compose.yml up -d

# Run fingerprint validation
go test -v -run TestFingerprint ./benchmark/...

# Run TLSC vs tls-client comparison
go test -v -run TestComparison ./benchmark/...

# Run full benchmark suite
go test -v -run TestFullBenchmarkSuite ./benchmark/...

# Stop infrastructure
docker compose -f benchmark/docker-compose.yml down

Benchmark Components

• Validation Oracle: Captures and validates JA3/JA4 fingerprints
• Payload Server: Serves configurable response sizes
• Toxiproxy: Simulates network conditions (latency, packet loss, bandwidth)

Dependencies

tlsc uses forked and external packages for full fingerprint control:

License

MIT License - See LICENSE file for details.