README
¶
go-browserhttp / browserhttp
A pure-Go (CGO=0) http.Client that presents a real Chrome TLS
fingerprint via uTLS. Many
sites 403 non-browser clients based largely on the TLS ClientHello; mimicking
Chrome's ciphers/extensions/curves — plus a browser User-Agent and a warmed
cookie jar — lets a plain Go client reach public endpoints with no host web
view. Identical on macOS, Linux and Windows.
c := browserhttp.NewClient(30 * time.Second)
resp, err := c.Get("https://www.reddit.com/r/golang/hot.json")
Extracted from go-news-reader/reader; shared by any fetcher that must look
like a browser.
Certificate verification
The client performs real X.509 chain and host-name verification on every
HTTPS handshake — it never uses InsecureSkipVerify in the default path. The
trust store is resolved once per process:
- The OS system pool (
crypto/x509.SystemCertPool) is used when it is populated — this covers Linux (/etc/ssl/...) and Windows (the syscall cert store). - Otherwise the client falls back to an embedded Mozilla CA bundle (the
"Mozilla Included CA Certificate List" from the Common CA Database, via
github.com/breml/rootcerts/embedded, MPL-2.0). This is essential under CGO=0 on macOS, whereSystemCertPoolis always empty because Go defers to a platform verifier a cgo-free binary cannot reach, and forFROM scratchcontainers that ship no OS trust store at all.
Two knobs are available via Options, threaded through NewClientWithOptions
and NewTransportWithOptions:
// Trust a private CA / test server, on top of the OS+embedded roots.
c := browserhttp.NewClientWithOptions(30*time.Second, browserhttp.Options{
ExtraRootPEM: myCAPEM,
})
// Explicit, clearly-named opt-out (off by default — use only when you must).
c := browserhttp.NewClientWithOptions(30*time.Second, browserhttp.Options{
InsecureSkipVerify: true,
})
License
BSD-3-Clause © the go-browserhttp/browserhttp authors.
Documentation
¶
Overview ¶
Package browserhttp builds a portable, pure-Go (CGO=0) http.Client that presents a real Chrome TLS fingerprint via uTLS. Many platforms (Reddit, Twitter, Instagram, TikTok) 403 non-browser clients based largely on the TLS ClientHello — Go's default handshake is trivially distinguishable from a browser's. Mimicking Chrome's ciphers/extensions/curves, plus a browser User-Agent and a warmed cookie jar, lets a plain Go client reach the public endpoints without any host web view. It works identically on macOS, Linux and Windows, and is shared by every provider that needs to look like a browser.
Certificate verification ¶
The client performs real X.509 chain and host-name verification on every HTTPS handshake; it never uses InsecureSkipVerify in the default path. The trust store is resolved once per process:
- The OS system pool (crypto/x509.SystemCertPool) is used when it is populated — this covers Linux (/etc/ssl/...) and Windows (the syscall cert store).
- Otherwise the client falls back to an embedded copy of the Mozilla Included CA Certificate List. This is essential under CGO=0 on macOS, where SystemCertPool is always empty (Go defers to the platform verifier, which a cgo-free binary cannot reach), and for FROM-scratch containers that ship no OS trust store at all.
Callers can append private-CA / test roots (Options.ExtraRootPEM) and, as an explicit and clearly-named opt-in, disable verification entirely (Options.InsecureSkipVerify) — but the default always verifies.
Index ¶
Constants ¶
const DefaultUserAgent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " +
"AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
DefaultUserAgent is a current desktop-Chrome User-Agent string. Providers set it (or their own) on outgoing requests; it is not applied automatically.
Variables ¶
This section is empty.
Functions ¶
func NewClient ¶
NewClient returns an http.Client whose TLS handshakes impersonate Chrome, which verifies server certificates against the OS/embedded trust store, and which keeps cookies across requests.
func NewClientWithOptions ¶ added in v0.2.0
NewClientWithOptions is NewClient with explicit TLS trust Options.
func NewTransport ¶
NewTransport returns an http.Transport that dials TLS with a Chrome fingerprint (forced to HTTP/1.1 so net/http drives the connection) and full certificate verification.
func NewTransportWithOptions ¶ added in v0.2.0
NewTransportWithOptions is NewTransport with explicit TLS trust Options.
Types ¶
type Options ¶ added in v0.2.0
type Options struct {
// ExtraRootPEM, when non-empty, is a PEM bundle of additional trusted root
// certificates appended to the trust store. Use it for private CAs or to
// trust a test server's self-signed certificate. It augments — never
// replaces — the OS/embedded roots.
ExtraRootPEM []byte
// InsecureSkipVerify disables all certificate chain and host-name
// verification. It is off by default and MUST stay off outside of
// deliberate, well-understood cases (e.g. probing a host whose self-signed
// certificate cannot be supplied as an extra root). The name mirrors
// crypto/tls so the risk is unmistakable at the call site.
InsecureSkipVerify bool
}
Options tunes the TLS trust behaviour of a client or transport. The zero value is safe: it verifies certificates against the OS/embedded trust store and skips nothing.
Source Files