tlsclient

TLS Client

A powerful Go HTTP client library that provides advanced TLS fingerprinting capabilities, allowing you to emulate various browsers and devices for web scraping, testing, and automation tasks.

Features

• 🌐 Browser Emulation: Mimic TLS fingerprints of Chrome, Safari, OkHttp4, and HttpUrlConnection
• 🚀 HTTP Protocol Support: HTTP/1.1, HTTP/2, and HTTP/3
• 🗜️ Automatic Decompression: Built-in support for gzip, brotli, zstd, and deflate
• 🪝 Hooks: Pre-request and post-request hooks for request/response manipulation
• 📊 Bandwidth Tracking: Monitor network usage and performance
• 🎯 Certificate Pinning: Enhanced security with certificate validation
• 🌍 Proxy Support: HTTP, HTTPS, and SOCKS proxy support
• ⚡ High Performance: Optimized for speed and efficiency

Installation

go get github.com/nukilabs/tlsclient

Quick Start

package main

import (
    "fmt"
    "io"
    "log"
    "net/url"

    "github.com/nukilabs/http"
    "github.com/nukilabs/tlsclient"
    "github.com/nukilabs/tlsclient/profiles"
)

func main() {
    // Create a new client with Chrome profile
    client := tlsclient.New(profiles.Chrome138)
    client.SetProxy(&url.URL{
        Scheme: "http",
        Host:   "localhost:8888",
    })
    
    // Make a GET request
    req, err := client.NewRequest(http.MethodGet, "https://example.com", nil)
    if err != nil {
        log.Fatal(err)
    }

    // Add chrome-like headers
    req.Header = http.Header{
		"sec-ch-ua":                 {"\"Not)A;Brand\";v=\"8\", \"Chromium\";v=\"138\", \"Google Chrome\";v=\"138\""},
		"sec-ch-ua-mobile":          {"?0"},
		"sec-ch-ua-platform":        {"\"Windows\""},
		"upgrade-insecure-requests": {"1"},
		"user-agent":                {"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36"},
		"accept":                    {"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"},
		"sec-fetch-site":            {"none"},
		"sec-fetch-mode":            {"navigate"},
		"sec-fetch-user":            {"?1"},
		"sec-fetch-dest":            {"document"},
		"accept-encoding":           {"gzip, deflate, br, zstd"},
		"accept-language":           {"de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"},
		"priority":                  {"u=0, i"},
		http.HeaderOrderKey:         {"sec-ch-ua", "sec-ch-ua-mobile", "sec-ch-ua-platform", "upgrade-insecure-requests", "user-agent", "accept", "sec-fetch-site", "sec-fetch-mode", "sec-fetch-user", "sec-fetch-dest", "accept-encoding", "accept-language", "priority"},
	}

    // Perform the request
    res, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    
    // Read and print the response
    body, err := io.ReadAll(res.Body)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println(string(body))
}

Available Profiles

Chrome Browsers

// Chrome versions 120-138
client := tlsclient.New(profiles.Chrome138)  // Latest Chrome
client := tlsclient.New(profiles.Chrome120)  // Older Chrome version

Safari Browsers

// Safari 17
client := tlsclient.New(profiles.Safari17)

Android HttpUrlConnection

// Android API levels 21-35
client := tlsclient.New(profiles.HttpUrlConnectionAndroid(33))  // Android 13
client := tlsclient.New(profiles.HttpUrlConnectionAndroid(21))  // Android 5.0

Android OkHttp4

// Android API levels 21-35
client := tlsclient.New(profiles.Okhttp4Android(33))  // Android 13
client := tlsclient.New(profiles.Okhttp4Android(29))  // Android 10

Configuration Options

Basic Options

client := tlsclient.New(profiles.Chrome138,
    tlsclient.WithTimeout(30*time.Second),  // Set request timeout
    tlsclient.WithNoCookieJar(),            // Disable cookie jar
    tlsclient.WithNoAutoDecompress(),       // Disable automatic decompression
    tlsclient.WithNoFollowRedirects(),      // Disable automatic redirects
)

Advanced Transport Options

client := tlsclient.New(profiles.Chrome138,
    tlsclient.WithTransportOptions(tlsclient.TransportOptions{
        ServerNameOverride: "example.com",
        InsecureSkipVerify: true,
        DisableKeepAlives:  false,
        IdleConnTimeout:    90 * time.Second,
        DisableIPV4:        false,
        DisableIPV6:        false,
    }),
)

Certificate Pinning

client := tlsclient.New(profiles.Chrome138,
    tlsclient.WithAutoPinning(),
)

Redirect Handling

Disable Redirects

client.SetFollowRedirects(false)

Custom Redirect Policy

client.SetRedirectFunc(func(req *http.Request, via []*http.Request) error {
    // Maximum of 5 redirects
    if len(via) >= 5 {
        return errors.New("too many redirects")
    }
    
    // Don't follow redirects to different hosts
    if req.URL.Host != via[0].URL.Host {
        return errors.New("cross-host redirect not allowed")
    }
    
    return nil
})

Proxy Support

// HTTP Proxy
client.SetProxy(&url.URL{
    Scheme: "http",
    Host:   "proxy.example.com:8080",
})

// SOCKS5 Proxy
client.SetProxy(&url.URL{
    Scheme: "socks5",
    Host:   "proxy.example.com:1080",
})

// Authenticated Proxy
client.SetProxy(&url.URL{
    Scheme: "http",
    Host:   "proxy.example.com:8080",
    User:   url.UserPassword("username", "password"),
})

Hooks

Pre-Request Hooks

Pre-hooks run before each request and can modify the request before it is sent.

func AddAuthHeader(client *tlsclient.Client, req *http.Request) (*http.Request, error) {
    req.Header.Set("Authorization", "Bearer my-token")
    return req, nil
}

client.AddPreHooks(AddAuthHeader)

Post-Request Hooks

Post-hooks run after each request and can inspect or modify the response.

func GotBlockedHook(client *tlsclient.Client, req *http.Request, res *http.Response) (*http.Response, error) {
    if res.StatusCode == http.StatusTooManyRequests {
        // Switch to a different proxy if blocked
        client.SetProxy(&url.URL{
            Scheme: "http",
            Host:   "localhost:8889",
        })
    }
    return res, nil
}

client.AddPostHooks(GotBlockedHook)

Managing Hooks

// Set hooks (replaces any existing hooks)
client.SetPreHooks(hook1, hook2)
client.SetPostHooks(hook1, hook2)

// Add hooks (appends to existing hooks)
client.AddPreHooks(hook3)
client.AddPostHooks(hook3)

// Delete all hooks
client.DeletePreHooks()
client.DeletePostHooks()

Best Practices

Connection Reuse

// Reuse the same client for multiple requests
client := tlsclient.New(profiles.Chrome138)

// Make multiple requests with the same client
for _, url := range urls {
    res, err := client.Get(url)
    if err != nil {
        continue
    }
    // Process response...
    res.Body.Close()
}

Resource Management

res, err := client.Get("https://example.com")
if err != nil {
    return err
}
defer res.Body.Close() // Always close response body

// Read response body
body, err := io.ReadAll(res.Body)
if err != nil {
    return err
}

Contributing

We welcome contributions from the community! This TLS Client is constantly evolving, and we'd love your help in making it even better. Here are some ways you can contribute:

🌐 TLS Profiles

We're always looking to expand our browser and device emulation capabilities. If you have access to a browser, device, or HTTP client that isn't currently supported, we'd love to add it!

How to contribute a new TLS profile:

1. Capture the TLS fingerprint using tools like:

   • Powhttp HTTP Proxy App
   • Peets TLS fingerprinting API
   • Network analysis tools (Wireshark, etc.)

2. Create the profile by adding it to the appropriate file in /profiles/:

   // profiles/newbrowser.go
   var NewBrowser = ClientProfile{
       ClientHelloSpec: func() *tls.ClientHelloSpec {
           return &tls.ClientHelloSpec{
               CipherSuites: []uint16{
                   // Your cipher suites here
               },
               Extensions: []tls.TLSExtension{
                   // Your extensions here
               },
               // ... other TLS parameters
           }
       },
       Settings: []http2.Setting{
           // HTTP/2 settings
       },
       // ... other profile parameters
   }
   

3. Add tests in /tests/ to verify the profile works correctly

4. Update documentation to include the new profile in the README

Browsers/Clients we'd love to see:

• Firefox (all versions)
• Edge (Chromium-based)
• Opera
• Brave
• Mobile browsers (iOS Safari, Chrome Mobile, Samsung Internet)
• HTTP clients (curl, wget, Python requests, etc.)

We appreciate all contributions, no matter how small! 🙏

Acknowledgments

• Uses nukilabs/utls for TLS fingerprinting
• Uses nukilabs/http for custom HTTP1.1 and HTTP/2 support
• Uses nukilabs/quic-qo for HTTP/3 support
• Inspired by:
  • refraction-networking/utls
  • bogdanfinn/tls-client
  • useflyent/fhttp

© 2025 nukilabs