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.goindex 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 := falsefor _, arg := range custom {diff --git a/internal/bridge/worker_stealth.go b/internal/bridge/worker_stealth.goindex 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.gonew file mode 100644index 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.goindex 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.goindex 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.goindex 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 := falseif 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.goindex 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.shindex 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.shindex 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