Skip to content

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

fix(stealth): keep page/worker UA parity and avoid headless leak

Luigi Agosti5acd9b8eceeb
diff --git a/internal/bridge/init_test.go b/internal/bridge/init_test.go
index bb6f3c1b..848d98a8 100644
--- a/internal/bridge/init_test.go
+++ b/internal/bridge/init_test.go
@@ -56,16 +56,39 @@ 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.
+ // HEADED + no 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)
+ t.Fatalf("did not expect a pinned user-agent in headed mode without a custom UA, got %v", args)
}
}
- // Explicit custom UA: it must be pinned.
+ // HEADLESS + no custom UA: Chrome's NATIVE userAgent contains
+ // "HeadlessChrome/..." in --headless=new. We MUST pin --user-agent so the
+ // headless tell never reaches the page or workers. The native UA-CH is
+ // already degraded in headless, so the PR #580 UA-CH realism rationale
+ // does not apply here.
+ headless := buildChromeArgs(&config.RuntimeConfig{ChromeVersion: "144.0.7559.133", Headless: true}, 9222)
+ var headlessUA string
+ for _, arg := range headless {
+ if strings.HasPrefix(arg, "--user-agent=") {
+ headlessUA = strings.TrimPrefix(arg, "--user-agent=")
+ break
+ }
+ }
+ if headlessUA == "" {
+ t.Fatalf("expected --user-agent to be pinned in headless mode (HeadlessChrome would otherwise leak in navigator.userAgent), got %v", headless)
+ }
+ if strings.Contains(headlessUA, "HeadlessChrome") {
+ t.Fatalf("pinned headless UA must not contain HeadlessChrome, got %q", headlessUA)
+ }
+ if !strings.Contains(headlessUA, "Chrome/144.0.0.0") {
+ t.Fatalf("pinned headless UA should carry the configured frozen Chrome major, got %q", headlessUA)
+ }
+
+ // Explicit custom UA: it must be pinned (independent of headless).
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 custom {
diff --git a/internal/bridge/worker_stealth.go b/internal/bridge/worker_stealth.go
index 9d85613e..74e686f4 100644
--- a/internal/bridge/worker_stealth.go
+++ b/internal/bridge/worker_stealth.go
@@ -45,16 +45,39 @@ func (b *Bridge) applyWorkerStealth(parent context.Context, targetID target.ID,
ua = b.StealthBundle.LaunchUserAgent()
}
+ persona := workerStealthPersona(ua, b.Config.ChromeVersion)
+
if err := chromedp.Run(runCtx,
chromedp.ActionFunc(func(ctx context.Context) error {
return stealth.ApplyTargetEmulation(ctx, b.Config, ua)
}),
- chromedp.Evaluate(workerStealthParityScript(stealth.BuildPersona(ua, b.Config.ChromeVersion)), nil),
+ chromedp.Evaluate(workerStealthParityScript(persona), nil),
); err != nil {
slog.Debug("worker stealth parity failed", "targetId", targetID, "targetType", targetType, "err", err)
}
}
+// workerStealthPersona returns the persona the worker-stealth parity script
+// should impose on a worker's navigator.
+//
+// When no explicit custom UA is configured (launch.go no longer pins
+// --user-agent in that case), the PAGE uses Chrome's native userAgent.
+// Synthesizing a config-derived UA here would force a static major onto the
+// worker that the page does not carry — a page/worker mismatch a real Chrome
+// never exhibits. Leaving UserAgent / NavigatorPlatform empty lets
+// workerStealthParityScript fall back to the worker's own native values
+// (which Chrome keeps consistent with the page).
+func workerStealthPersona(launchUA, chromeVersion string) stealth.BrowserPersona {
+ if strings.TrimSpace(launchUA) == "" {
+ return stealth.BrowserPersona{
+ Language: "en-US",
+ Languages: []string{"en-US", "en"},
+ AcceptLanguage: "en-US,en",
+ }
+ }
+ return stealth.BuildPersona(launchUA, chromeVersion)
+}
+
func workerStealthParityScript(persona stealth.BrowserPersona) string {
languagesJSON := safeJSONStringArray(persona.Languages, `["en-US","en"]`)
diff --git a/internal/bridge/worker_stealth_test.go b/internal/bridge/worker_stealth_test.go
new file mode 100644
index 00000000..0c047781
--- /dev/null
+++ b/internal/bridge/worker_stealth_test.go
@@ -0,0 +1,84 @@
+package bridge
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/stealth"
+)
+
+// PR #580 made the launch path stop pinning --user-agent when no explicit
+// custom UA is configured, so the page now uses Chrome's NATIVE userAgent
+// (which can be any installed Chrome build, e.g. 146.x). The worker stealth
+// parity path in applyWorkerStealth still calls
+// BuildPersona(launchUA, cfg.ChromeVersion), which synthesizes a UA from
+// the static configured major even when launchUA is empty — and then
+// workerStealthParityScript overrides the worker's navigator.userAgent to
+// that synthesized value. The result: page UA != worker UA. This test
+// reproduces the regression.
+func TestWorkerStealthParityDefersToNativeUAWhenNoCustomUA(t *testing.T) {
+ cfg := &config.RuntimeConfig{ChromeVersion: "144.0.7559.133"}
+ bundle := stealth.NewBundle(cfg, 1)
+
+ launchUA := bundle.LaunchUserAgent()
+ if launchUA != "" {
+ t.Fatalf("precondition: with no custom UA, LaunchUserAgent must be empty, got %q", launchUA)
+ }
+
+ persona := workerStealthPersona(launchUA, cfg.ChromeVersion)
+ if persona.UserAgent != "" {
+ t.Fatalf("worker persona must defer to native nav.userAgent when no custom UA is configured; got %q (this is forced onto the worker and creates a page/worker UA mismatch when installed Chrome is not %s)", persona.UserAgent, cfg.ChromeVersion)
+ }
+ if persona.NavigatorPlatform != "" {
+ t.Fatalf("worker persona must defer to native nav.platform when no custom UA is configured; got %q", persona.NavigatorPlatform)
+ }
+
+ script := workerStealthParityScript(persona)
+ if strings.Contains(script, "Chrome/144.0.0.0") {
+ t.Fatalf("worker stealth script embeds a static config-derived UA the page no longer pins:\n%s", script)
+ }
+}
+
+// In HEADLESS mode the launch path pins --user-agent (otherwise Chrome's
+// native userAgent leaks "HeadlessChrome"). Workers must carry that same
+// pinned UA so the page and workers stay in lockstep.
+func TestWorkerStealthParityAppliesPinnedUserAgentWhenHeadless(t *testing.T) {
+ cfg := &config.RuntimeConfig{ChromeVersion: "144.0.7559.133", Headless: true}
+ bundle := stealth.NewBundle(cfg, 1)
+
+ launchUA := bundle.LaunchUserAgent()
+ if launchUA == "" {
+ t.Fatalf("precondition: headless launch must pin a non-empty UA, got %q", launchUA)
+ }
+ if strings.Contains(launchUA, "HeadlessChrome") {
+ t.Fatalf("pinned headless UA must not contain HeadlessChrome, got %q", launchUA)
+ }
+
+ persona := workerStealthPersona(launchUA, cfg.ChromeVersion)
+ if persona.UserAgent != launchUA {
+ t.Fatalf("worker persona must carry the pinned headless UA, got %q want %q", persona.UserAgent, launchUA)
+ }
+}
+
+// When an operator EXPLICITLY configures a custom UA, the worker must carry
+// that same UA so it matches the page.
+func TestWorkerStealthParityAppliesCustomUserAgent(t *testing.T) {
+ customUA := "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"
+ cfg := &config.RuntimeConfig{ChromeVersion: "144.0.7559.133", UserAgent: customUA}
+ bundle := stealth.NewBundle(cfg, 1)
+
+ launchUA := bundle.LaunchUserAgent()
+ if launchUA != customUA {
+ t.Fatalf("precondition: explicit custom UA must be pinned, got %q", launchUA)
+ }
+
+ persona := workerStealthPersona(launchUA, cfg.ChromeVersion)
+ if persona.UserAgent != customUA {
+ t.Fatalf("worker persona must carry the explicit custom UA, got %q", persona.UserAgent)
+ }
+ script := workerStealthParityScript(persona)
+ if !strings.Contains(script, customUA) {
+ t.Fatalf("worker stealth script must embed the explicit custom UA:\n%s", script)
+ }
+}
diff --git a/internal/handlers/stealth.go b/internal/handlers/stealth.go
index 2f6528fe..af85ef49 100644
--- a/internal/handlers/stealth.go
+++ b/internal/handlers/stealth.go
@@ -13,6 +13,7 @@ import (
"github.com/chromedp/chromedp"
"github.com/pinchtab/pinchtab/internal/activity"
"github.com/pinchtab/pinchtab/internal/httpx"
+ "github.com/pinchtab/pinchtab/internal/stealth"
)
type fingerprintRequest struct {
@@ -121,22 +122,28 @@ type fingerprint struct {
func (h *Handlers) generateFingerprint(req fingerprintRequest) fingerprint {
fp := fingerprint{}
+ // Match the launch-pinned UA: real Chrome (UA reduction, v100+) freezes
+ // navigator.userAgent to <major>.0.0.0. Using h.Config.ChromeVersion
+ // verbatim here would emit Chrome/144.0.7559.133 while the launch path
+ // pins Chrome/144.0.0.0 — a page/post-rotate version drift.
+ reducedChromeVersion := stealth.ReducedChromeVersion(h.Config.ChromeVersion)
+
osConfigs := map[string]map[string]fingerprint{
"windows": {
"chrome": {
- UserAgent: fmt.Sprintf("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36", h.Config.ChromeVersion),
+ UserAgent: fmt.Sprintf("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36", reducedChromeVersion),
Platform: "Win32",
Vendor: "Google Inc.",
},
"edge": {
- UserAgent: fmt.Sprintf("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36 Edg/%s", h.Config.ChromeVersion, h.Config.ChromeVersion),
+ UserAgent: fmt.Sprintf("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36 Edg/%s", reducedChromeVersion, reducedChromeVersion),
Platform: "Win32",
Vendor: "Google Inc.",
},
},
"mac": {
"chrome": {
- UserAgent: fmt.Sprintf("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36", h.Config.ChromeVersion),
+ UserAgent: fmt.Sprintf("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36", reducedChromeVersion),
Platform: "MacIntel",
Vendor: "Google Inc.",
},
diff --git a/internal/handlers/stealth_test.go b/internal/handlers/stealth_test.go
index db6c6124..c585f950 100644
--- a/internal/handlers/stealth_test.go
+++ b/internal/handlers/stealth_test.go
@@ -78,6 +78,40 @@ func TestGenerateFingerprint_Config(t *testing.T) {
}
}
+// The launch path pins navigator.userAgent to Chrome's UA-reduced form
+// (Chrome/<major>.0.0.0). /fingerprint/rotate runs against the same browser
+// session and MUST emit the same reduced form, otherwise an initial UA of
+// Chrome/144.0.0.0 followed by a rotated UA of Chrome/144.0.7559.133 trips
+// the "Chrome version preserved" E2E contract (system-basic.sh).
+func TestGenerateFingerprint_MatchesLaunchPinnedUAReduction(t *testing.T) {
+ cfg := &config.RuntimeConfig{ChromeVersion: "144.0.7559.133", Headless: true}
+ bundle := stealth.NewBundle(cfg, 1)
+ launchUA := bundle.LaunchUserAgent()
+ if launchUA == "" {
+ t.Fatalf("precondition: headless launch must pin a UA, got empty")
+ }
+ if !strings.Contains(launchUA, "Chrome/144.0.0.0") {
+ t.Fatalf("precondition: launch UA should be reduced to Chrome/144.0.0.0, got %q", launchUA)
+ }
+
+ h := Handlers{Config: cfg}
+ for _, tc := range []struct {
+ os, browser string
+ }{
+ {"windows", "chrome"},
+ {"mac", "chrome"},
+ {"windows", "edge"},
+ } {
+ fp := h.generateFingerprint(fingerprintRequest{OS: tc.os, Browser: tc.browser})
+ if !strings.Contains(fp.UserAgent, "144.0.0.0") {
+ t.Errorf("rotate UA for %s/%s should carry reduced Chrome/144.0.0.0, got %q", tc.os, tc.browser, fp.UserAgent)
+ }
+ if strings.Contains(fp.UserAgent, "144.0.7559.133") {
+ t.Errorf("rotate UA for %s/%s leaks full build version (UA reduction violated): %q", tc.os, tc.browser, fp.UserAgent)
+ }
+ }
+}
+
func TestTimezoneIDFromOffset(t *testing.T) {
if got := timezoneIDFromOffset(-300); got != "America/New_York" {
t.Fatalf("timezoneIDFromOffset(-300) = %q, want America/New_York", got)
diff --git a/internal/stealth/launch.go b/internal/stealth/launch.go
index e5e4b4da..b9db8af9 100644
--- a/internal/stealth/launch.go
+++ b/internal/stealth/launch.go
@@ -14,9 +14,11 @@ type LaunchContract struct {
func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract {
persona := BrowserPersona{}
customUA := ""
+ headless := false
if cfg != nil {
persona = BuildPersona(cfg.UserAgent, cfg.ChromeVersion)
customUA = strings.TrimSpace(cfg.UserAgent)
+ headless = cfg.Headless
}
args := []string{
@@ -25,13 +27,17 @@ func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract
"--disable-blink-features=AutomationControlled",
"--enable-network-information-downlink-max",
}
- // 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 != ""
+ // Pin --user-agent when EITHER:
+ // - the operator configured an explicit custom UA, OR
+ // - Chrome runs HEADLESS — its native navigator.userAgent contains
+ // "HeadlessChrome/..." (a loud fingerprint tell), and its native UA-CH
+ // is already degraded under --headless=new, so the UA-CH realism cost
+ // of pinning does not apply.
+ //
+ // In HEADED mode with no custom UA we leave --user-agent off so Chrome's
+ // native, self-consistent UA + high-entropy UA Client Hints are served
+ // (passing --user-agent otherwise empties them).
+ pinUA := persona.UserAgent != "" && (customUA != "" || headless)
if pinUA {
args = append(args, "--user-agent="+persona.UserAgent)
}
diff --git a/internal/stealth/ua.go b/internal/stealth/ua.go
index fdced4fa..76cbaad4 100644
--- a/internal/stealth/ua.go
+++ b/internal/stealth/ua.go
@@ -31,6 +31,22 @@ type BrowserPersona struct {
UserAgentData UserAgentDataProfile `json:"userAgentData"`
}
+// ReducedChromeVersion returns the UA-reduced (v100+) "<major>.0.0.0" form
+// of a Chrome version string. navigator.userAgent in real Chrome never carries
+// the full build — exposing it is a fingerprint tell. The full build still
+// lives in the high-entropy UA Client Hints. Falls back to the default major
+// when chromeVersion is empty so all callers agree on a single value.
+func ReducedChromeVersion(chromeVersion string) string {
+ major := chromeVersion
+ if i := strings.Index(chromeVersion, "."); i > 0 {
+ major = chromeVersion[:i]
+ }
+ if major == "" {
+ major = "144"
+ }
+ return major + ".0.0.0"
+}
+
func ResolveUserAgent(userAgent, chromeVersion string) string {
if userAgent != "" {
return userAgent
@@ -50,19 +66,17 @@ func ResolveUserAgent(userAgent, chromeVersion string) string {
}
func BuildPersona(userAgent, chromeVersion string) BrowserPersona {
- major := chromeVersion
- if i := strings.Index(chromeVersion, "."); i > 0 {
- major = chromeVersion[:i]
- }
- if major == "" {
- major = "144"
+ reduced := ReducedChromeVersion(chromeVersion)
+ major := reduced
+ if i := strings.Index(reduced, "."); i > 0 {
+ major = reduced[:i]
}
// 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")
+ ua := ResolveUserAgent(userAgent, reduced)
language := "en-US"
languages := []string{"en-US", "en"}
acceptLanguage := "en-US,en"
diff --git a/tests/e2e/scenarios/infra/stealth-basic.sh b/tests/e2e/scenarios/infra/stealth-basic.sh
index 41458a4d..303a8b7c 100644
--- a/tests/e2e/scenarios/infra/stealth-basic.sh
+++ b/tests/e2e/scenarios/infra/stealth-basic.sh
@@ -18,7 +18,7 @@ assert_json_exists "$RESULT" '.scriptHash' "status includes script hash"
assert_json_eq "$RESULT" '.capabilities.webdriverNotTrue' 'true' "status reports webdriver-not-true capability"
assert_json_eq "$RESULT" '.capabilities.webdriverNativeStrategy' 'true' "status reports native webdriver strategy"
assert_json_eq "$RESULT" '.capabilities.downlinkMax' 'true' "status reports downlinkMax capability"
-assert_json_eq "$RESULT" '.flags.globalUserAgent' 'true' "status reports global launch UA"
+assert_json_eq "$RESULT" '.flags.globalUserAgent' 'true' "status reports global launch UA is pinned (default headless config or custom UA)"
assert_json_eq "$RESULT" '.flags.downlinkMaxFlag' 'true' "status reports downlinkMax launch flag"
assert_json_eq "$RESULT" '.capabilities.iframeIsolation' 'false' "light status keeps iframe isolation disabled"
assert_json_eq "$RESULT" '.capabilities.errorStackSanitized' 'false' "light status keeps stack sanitization disabled"
diff --git a/tests/e2e/scenarios/infra/stealth-extended.sh b/tests/e2e/scenarios/infra/stealth-extended.sh
index bce4dbeb..9b06f5be 100644
--- a/tests/e2e/scenarios/infra/stealth-extended.sh
+++ b/tests/e2e/scenarios/infra/stealth-extended.sh
@@ -37,7 +37,7 @@ run_stealth_level_matrix() {
MATRIX_STATUS="$RESULT"
assert_json_eq "$RESULT" '.level' "$STEALTH_LEVEL" "status level matches instance"
assert_json_exists "$RESULT" '.scriptHash' "status includes script hash"
- assert_json_eq "$RESULT" '.flags.globalUserAgent' 'true' "status reports global launch UA"
+ assert_json_eq "$RESULT" '.flags.globalUserAgent' 'true' "status reports global launch UA is pinned (default headless config or custom UA)"
assert_json_eq "$RESULT" '.capabilities.webdriverNativeStrategy' 'true' "status reports native webdriver strategy"
assert_json_eq "$RESULT" '.capabilities.downlinkMax' 'true' "status reports downlinkMax capability"
end_test