TLS (JA3) Fingerprinting

Relevant source files

The following files were used as context for generating this wiki page:

• main.js
• utils.js
• fingerprint.js
• setup.js
• README.md
• CHANGELOG_v1.2.3.md
• renderer.js

In GeekezBrowser, "TLS Fingerprint Safety" is a core feature designed to make the browser's network traffic indistinguishable from that of a standard, unmodified Google Chrome browser. A TLS (Transport Layer Security) fingerprint, often represented as a JA3 hash, is generated from the parameters in a client's initial TLS ClientHello message. Advanced detection systems like Cloudflare use these fingerprints to identify and block non-standard clients or bots.

GeekezBrowser's strategy is to avoid modifying the TLS handshake at the browser level and to actively mimic Chrome's fingerprint at the proxy communication layer. This is achieved by using a real Chrome binary for web browsing and configuring the underlying Xray-core proxy engine to generate Chrome-like TLS handshakes for its own connections. This ensures the TLS fingerprint is consistent with the browser's User-Agent and other identifying characteristics.

Sources: README.md, CHANGELOG_v1.2.3.md, renderer.js:315

Architecture Overview

The system's approach to TLS fingerprinting involves two distinct components: the native Chrome browser instance and the Xray-core proxy engine. Each component handles TLS handshakes in a way that preserves authenticity.

1. Browser-to-Server TLS: All web traffic from the browser to the target website (e.g., Amazon, TikTok) uses the native TLS stack of the real Chrome binary. GeekezBrowser does not intercept or modify this handshake, ensuring a genuine JA3 fingerprint.
2. Proxy-to-Proxy TLS: When a proxy is used (e.g., VLESS, Trojan), the connection from the local Xray-core instance to the remote proxy server is also secured with TLS. For this connection, Xray-core is explicitly configured to generate a TLS ClientHello that mimics a standard Chrome browser.

The diagram below illustrates this dual-TLS architecture.

This diagram shows the two separate TLS handshakes that occur during a proxied connection, and how each is handled to maintain a consistent and undetectable fingerprint.

Sources: main.js:520-667, utils.js:203-221

Browser-Level Strategy: Native Execution

The primary method for ensuring an authentic TLS fingerprint is by using a real, unmodified Google Chrome binary. GeekezBrowser does not use a custom browser engine or attempt to emulate a TLS handshake in JavaScript. Instead, it downloads and launches a specific version of Chrome for Testing.

Sources: README.md, setup.js:192-212

Launch Process

When a user launches a profile, the main.js process executes the following steps:

1. Locates Chrome: The getChromiumPath function finds the path to the downloaded chrome.exe (Windows) or Google Chrome for Testing (macOS) binary.
2. Starts Puppeteer: puppeteer.launch is called with the executablePath pointing to the real Chrome binary.
3. Native Handshake: Because a genuine Chrome instance is running, any HTTPS request it makes will generate a TLS ClientHello packet that is byte-for-byte identical to what a regular user's browser would send. This results in a valid and consistent JA3 fingerprint.

The sequence diagram below details this launch process.

This process guarantees that the TLS fingerprint matches the capabilities and version of the running browser, a claim supported by the project's documentation.

Sources: main.js:63-79, 520-667, CHANGELOG_v1.2.3.md

Version Consistency

To prevent mismatches that can be flagged by detection systems, GeekezBrowser ensures strict version consistency between the advertised User-Agent and the underlying browser binary.

• Pinned Version: A specific Chrome version (129.0.6668.58) is hardcoded.
• Browser Download: The setup.js script uses @puppeteer/browsers to download this exact buildId.
• User-Agent Generation: The fingerprint.js module uses the same version string to construct the User-Agent header.

This alignment is critical, as a browser advertising version 129 but sending a JA3 fingerprint associated with version 120 would be an immediate red flag.

File	Constant	Value	Purpose
fingerprint.js	CHROME_VERSION_FULL	129.0.6668.58	Used for generating the User-Agent string.
setup.js	BUILD_ID	129.0.6668.58	The exact Chrome build to download.

Sources: fingerprint.js:2, setup.js:194

Proxy-Level Strategy: Xray-core Mimicry

When a profile uses a proxy that requires a TLS-encrypted connection (like VLESS with TLS/REALITY or Trojan), the connection between the local machine and the proxy server also has a TLS fingerprint. GeekezBrowser configures its integrated Xray-core engine to mimic a Chrome browser's TLS handshake for these connections.

Sources: utils.js:1-230

Configuration Flow

The parseProxyLink function in utils.js is responsible for translating a proxy link (e.g., vless://...) into a valid Xray-core outbound configuration. A key part of this process is setting the tlsSettings or realitySettings.

This flow ensures that whenever Xray-core establishes a TLS-based connection to a proxy server, it uses a fingerprint that matches Chrome.

Sources: utils.js:78-154

Key TLS Configuration Parameters

The following parameters in utils.js are crucial for TLS fingerprinting at the proxy layer.

Parameter	Context	Description	Example Protocols
fingerprint: "chrome"	tlsSettings, realitySettings	Instructs Xray-core to generate a TLS Client Hello that mimics a standard Chrome browser.	VLESS, Trojan
serverName	tlsSettings, realitySettings	Sets the Server Name Indication (SNI) in the TLS handshake, which must match the server's certificate.	VLESS, Trojan
alpn	tlsSettings	Sets the Application-Layer Protocol Negotiation (ALPN) values (e.g., h2, http/1.1).	VLESS
publicKey	realitySettings	The public key for the REALITY protocol, used to authenticate the server.	VLESS (REALITY)

Here is a code snippet from utils.js showing how the fingerprint is applied for a VLESS link with REALITY security:

// From utils.js
} else if (security === 'reality') {
    outbound.streamSettings.realitySettings = {
        show: false,
        fingerprint: params.get("fp") || "chrome",
        serverName: params.get("sni") || params.get("host") || "",
        publicKey: params.get("pbk") || "",
        shortId: params.get("sid") || "",
        spiderX: params.get("spx") || ""
    };
}

Sources: utils.js:144-153

Conclusion

GeekezBrowser employs a robust, two-pronged strategy for TLS fingerprint management that makes its traffic difficult to distinguish from a regular user. By leveraging a real, unmodified Chrome binary, it guarantees an authentic JA3 fingerprint for all browser-to-server communication. Simultaneously, it configures its underlying proxy engine, Xray-core, to actively mimic Chrome's TLS fingerprint for proxy-layer connections. This comprehensive approach of native execution and active mimicry is central to the browser's "TLS Fingerprint Safety" and its ability to bypass advanced bot detection systems.

Sources: README.md, CHANGELOG_v1.2.3.md