Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(stealth): use Chrome's native UA Client Hints unless an explicit UA is set

AriaShishegaran41dd159be309
diff --git a/internal/bridge/init_test.go b/internal/bridge/init_test.go
index b306d1ff..bb6f3c1b 100644
--- a/internal/bridge/init_test.go
+++ b/internal/bridge/init_test.go
@@ -56,17 +56,26 @@ func TestBuildChromeArgsHeadlessUsesSoftwareRendering(t *testing.T) {
}
func TestBuildChromeArgsIncludesGlobalUserAgent(t *testing.T) {
+ // ChromeVersion only (no explicit custom UA): Chrome must run WITHOUT
+ // --user-agent so its native, complete high-entropy UA Client Hints are served.
args := buildChromeArgs(&config.RuntimeConfig{ChromeVersion: "144.0.7559.133"}, 9222)
+ for _, arg := range args {
+ if strings.HasPrefix(arg, "--user-agent=") {
+ t.Fatalf("did not expect a pinned user-agent without a custom UA, got %v", args)
+ }
+ }
+ // Explicit custom UA: it must be pinned.
+ custom := buildChromeArgs(&config.RuntimeConfig{ChromeVersion: "144.0.7559.133", UserAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"}, 9222)
found := false
- for _, arg := range args {
+ for _, arg := range custom {
if strings.HasPrefix(arg, "--user-agent=Mozilla/5.0") {
found = true
break
}
}
if !found {
- t.Fatalf("expected global user-agent arg in %v", args)
+ t.Fatalf("expected an explicit custom UA to be pinned in %v", custom)
}
}
diff --git a/internal/stealth/bundle_test.go b/internal/stealth/bundle_test.go
index b3f6c7e1..a911a56e 100644
--- a/internal/stealth/bundle_test.go
+++ b/internal/stealth/bundle_test.go
@@ -138,7 +138,14 @@ func TestBuildLaunchContractOwnsStealthLaunchFlags(t *testing.T) {
t.Fatalf("expected stealth launch arg %q in %v", want, launch.Args)
}
}
- if !HasLaunchArgPrefix(launch.Args, "--user-agent=Mozilla/5.0") {
- t.Fatalf("expected stealth launch contract to own user-agent, got %v", launch.Args)
+ // Without an explicit custom UA, --user-agent must NOT be pinned (pinning it
+ // empties Chrome's native high-entropy UA Client Hints).
+ if HasLaunchArgPrefix(launch.Args, "--user-agent=") {
+ t.Fatalf("did not expect a pinned user-agent without a custom UA, got %v", launch.Args)
+ }
+ // With an explicit custom UA, the launch contract owns --user-agent.
+ custom := BuildLaunchContract(&config.RuntimeConfig{ChromeVersion: "144.0.0.0", UserAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"}, LevelLight)
+ if !HasLaunchArgPrefix(custom.Args, "--user-agent=Mozilla/5.0") {
+ t.Fatalf("expected an explicit custom UA to pin --user-agent, got %v", custom.Args)
}
}
diff --git a/internal/stealth/emulation.go b/internal/stealth/emulation.go
index 151852f6..e8bf9f29 100644
--- a/internal/stealth/emulation.go
+++ b/internal/stealth/emulation.go
@@ -3,6 +3,7 @@ package stealth
import (
"context"
"fmt"
+ "strings"
"github.com/chromedp/cdproto/emulation"
"github.com/pinchtab/pinchtab/internal/config"
@@ -75,9 +76,18 @@ func ApplyTargetEmulation(ctx context.Context, cfg *config.RuntimeConfig, userAg
}
}
- if uaOverride := BuildUserAgentOverride(userAgent, cfg.ChromeVersion); uaOverride != nil {
- if err := uaOverride.Do(ctx); err != nil {
- return fmt.Errorf("user agent override: %w", err)
+ // Override the UA Client Hints metadata ONLY when the caller supplied an
+ // explicit UA (userAgent is the launch --user-agent, set only for a configured
+ // custom UA). Otherwise defer to Chrome's NATIVE UA-CH: the synthesized
+ // metadata is inconsistent with a real Chrome — a stale GREASE brand, a
+ // hardcoded platformVersion, and (because cdproto's UserAgentMetadata has no
+ // full_version field) an empty uaFullVersion — whereas the native hints are
+ // correct and self-consistent.
+ if strings.TrimSpace(userAgent) != "" {
+ if uaOverride := BuildUserAgentOverride(userAgent, cfg.ChromeVersion); uaOverride != nil {
+ if err := uaOverride.Do(ctx); err != nil {
+ return fmt.Errorf("user agent override: %w", err)
+ }
}
}
diff --git a/internal/stealth/launch.go b/internal/stealth/launch.go
index 95c1e927..e5e4b4da 100644
--- a/internal/stealth/launch.go
+++ b/internal/stealth/launch.go
@@ -13,8 +13,10 @@ type LaunchContract struct {
func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract {
persona := BrowserPersona{}
+ customUA := ""
if cfg != nil {
persona = BuildPersona(cfg.UserAgent, cfg.ChromeVersion)
+ customUA = strings.TrimSpace(cfg.UserAgent)
}
args := []string{
@@ -23,7 +25,14 @@ func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract
"--disable-blink-features=AutomationControlled",
"--enable-network-information-downlink-max",
}
- if persona.UserAgent != "" {
+ // Only pin --user-agent when the operator configured an EXPLICIT custom UA.
+ // Passing --user-agent makes Chrome return EMPTY high-entropy UA Client Hints
+ // (architecture, platformVersion, uaFullVersion, fullVersionList) from
+ // navigator.userAgentData.getHighEntropyValues — a fingerprint inconsistency a
+ // real Chrome never exhibits. With no custom UA, Chrome's native UA + native
+ // UA-CH are already self-consistent, so leave them intact.
+ pinUA := customUA != "" && persona.UserAgent != ""
+ if pinUA {
args = append(args, "--user-agent="+persona.UserAgent)
}
if persona.Language != "" {
@@ -36,7 +45,7 @@ func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract
"automationControlledDisabled": true,
"enableAutomationFalse": true,
"downlinkMaxFlag": true,
- "globalUserAgent": persona.UserAgent != "",
+ "globalUserAgent": pinUA,
"globalLanguage": persona.Language != "",
},
}
diff --git a/internal/stealth/ua.go b/internal/stealth/ua.go
index 27fa08bc..fdced4fa 100644
--- a/internal/stealth/ua.go
+++ b/internal/stealth/ua.go
@@ -50,7 +50,19 @@ func ResolveUserAgent(userAgent, chromeVersion string) string {
}
func BuildPersona(userAgent, chromeVersion string) BrowserPersona {
- ua := ResolveUserAgent(userAgent, chromeVersion)
+ major := chromeVersion
+ if i := strings.Index(chromeVersion, "."); i > 0 {
+ major = chromeVersion[:i]
+ }
+ if major == "" {
+ major = "144"
+ }
+ // Freeze the UA build to <major>.0.0.0. Real Chrome (UA reduction, v100+) never
+ // exposes the full build in navigator.userAgent — a UA like "Chrome/146.0.7680.80"
+ // is a fingerprint tell. The full build still lives in the high-entropy UA-CH
+ // (uaFullVersion / fullVersionList). An explicit custom userAgent is respected
+ // verbatim by ResolveUserAgent.
+ ua := ResolveUserAgent(userAgent, major+".0.0.0")
language := "en-US"
languages := []string{"en-US", "en"}
acceptLanguage := "en-US,en"
@@ -62,14 +74,6 @@ func BuildPersona(userAgent, chromeVersion string) BrowserPersona {
}
}
- major := chromeVersion
- if i := strings.Index(chromeVersion, "."); i > 0 {
- major = chromeVersion[:i]
- }
- if major == "" {
- major = "144"
- }
-
navigatorPlatform := "Linux x86_64"
uaDataPlatform := "Linux"
platformVersion := "6.5.0"