Skip to content

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

fix: probe the launched browser and advertise its real version instead of a hardcoded Chrome version (PIN-074)

Luigi Agosti532770d2b01f
diff --git a/internal/bridge/handler_support.go b/internal/bridge/handler_support.go
index 9e59de87..8a1a6854 100644
--- a/internal/bridge/handler_support.go
+++ b/internal/bridge/handler_support.go
@@ -10,6 +10,7 @@ import (
"github.com/chromedp/cdproto/network"
"github.com/chromedp/cdproto/page"
"github.com/chromedp/chromedp"
+ "github.com/pinchtab/pinchtab/internal/stealth"
)
func (b *Bridge) EnableFetchWithAuth(ctx context.Context) error {
@@ -195,10 +196,7 @@ func (b *Bridge) SetUserAgentOverride(ctx context.Context, params UserAgentOverr
}
func (b *Bridge) browserVersion() string {
- if b.Config == nil {
- return ""
- }
- return b.Config.BrowserVersion
+ return stealth.ResolveBrowserVersion(b.Config)
}
func (b *Bridge) SetLocaleOverride(ctx context.Context, locale string) error {
diff --git a/internal/bridge/runtime/init.go b/internal/bridge/runtime/init.go
index a45ba63b..542cc678 100644
--- a/internal/bridge/runtime/init.go
+++ b/internal/bridge/runtime/init.go
@@ -71,6 +71,7 @@ func InitBrowser(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks)
}
}
+ stealth.WarnBrowserVersionMismatch(launchCfg)
bundle = ensureStealthBundle(launchCfg, bundle)
geoAlignment, err := resolveLaunchGeoAlignment(context.Background(), launchCfg)
if err != nil {
diff --git a/internal/bridge/worker_stealth.go b/internal/bridge/worker_stealth.go
index 50be6f96..24e9277d 100644
--- a/internal/bridge/worker_stealth.go
+++ b/internal/bridge/worker_stealth.go
@@ -53,7 +53,7 @@ func (b *Bridge) applyWorkerStealth(parent context.Context, targetID target.ID,
ua = b.StealthBundle.LaunchUserAgent()
}
- persona := workerStealthPersona(ua, b.Config.BrowserVersion)
+ persona := workerStealthPersona(ua, stealth.ResolveBrowserVersion(b.Config))
if err := chromedp.Run(runCtx,
chromedp.ActionFunc(func(ctx context.Context) error {
diff --git a/internal/handlers/stealth.go b/internal/handlers/stealth.go
index 1f02b49d..7a05d02d 100644
--- a/internal/handlers/stealth.go
+++ b/internal/handlers/stealth.go
@@ -137,7 +137,7 @@ func (h *Handlers) fingerprintMatrix() map[string]map[string]fingerprint {
// navigator.userAgent to <major>.0.0.0. Using h.Config.BrowserVersion
// verbatim here would emit the full build where the launch path pins the
// reduced form — a page/post-rotate version drift.
- reducedBrowserVersion := stealth.ReducedBrowserVersion(h.Config.BrowserVersion)
+ reducedBrowserVersion := stealth.ReducedBrowserVersion(stealth.ResolveBrowserVersion(h.Config))
// The Chrome UA strings come from stealth.ChromeUserAgent, the same template the
// launch persona uses, so the frozen OS tokens are spelled out once. mac/safari
diff --git a/internal/handlers/stealth_status.go b/internal/handlers/stealth_status.go
index e436be00..086fbcf0 100644
--- a/internal/handlers/stealth_status.go
+++ b/internal/handlers/stealth_status.go
@@ -3,17 +3,10 @@ package handlers
import (
"net/http"
- "github.com/pinchtab/pinchtab/internal/browserprobe"
- "github.com/pinchtab/pinchtab/internal/browsers/runtimekit"
- "github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/httpx"
+ "github.com/pinchtab/pinchtab/internal/stealth"
)
-// browserVersionCache keeps the per-binary probe off the request path. The
-// cache seam that tests exercise lives in browserprobe.VersionCache; this is
-// only the process-wide instance the handler reads through.
-var browserVersionCache = browserprobe.NewVersionCache(browserprobe.RunVersion)
-
func (h *Handlers) HandleStealthStatus(w http.ResponseWriter, r *http.Request) {
status := h.Bridge.StealthStatus()
if status == nil {
@@ -22,11 +15,11 @@ func (h *Handlers) HandleStealthStatus(w http.ResponseWriter, r *http.Request) {
}
// Both fields come from one config here so they can never be read from
// different sources: what the persona claims, and what the binary that
- // config resolves to reports for itself.
- if h.Config != nil {
- status.AdvertisedBrowserVersion = h.Config.BrowserVersion
- }
- status.BrowserBinaryVersion = probedBrowserVersion(r, h.Config)
+ // config resolves to reports for itself. The advertised value is what the
+ // persona actually presents — the probed version when browser.version is
+ // unset — so page and status agree.
+ status.AdvertisedBrowserVersion = stealth.ResolveBrowserVersion(h.Config)
+ status.BrowserBinaryVersion = stealth.ProbedBinaryVersion(h.Config)
if tabID := r.URL.Query().Get("tabId"); tabID != "" {
if tracker, ok := h.Bridge.(interface{ FingerprintRotateActive(string) bool }); ok {
status.TabOverrides["fingerprintRotateActive"] = tracker.FingerprintRotateActive(tabID)
@@ -34,14 +27,3 @@ func (h *Handlers) HandleStealthStatus(w http.ResponseWriter, r *http.Request) {
}
httpx.JSON(w, 200, status)
}
-
-// probedBrowserVersion reports the version the launched binary states for
-// itself, resolved through the same resolver the launch path uses. It is empty
-// when no binary is found or the probe fails, so a caller can tell "unknown"
-// from a real disagreement with the advertised version.
-func probedBrowserVersion(r *http.Request, cfg *config.RuntimeConfig) string {
- if cfg == nil {
- return ""
- }
- return browserVersionCache.Version(r.Context(), runtimekit.ResolveEffectiveBrowser(cfg).Binary)
-}
diff --git a/internal/handlers/stealth_status_test.go b/internal/handlers/stealth_status_test.go
index b8e79a9d..f2db9c82 100644
--- a/internal/handlers/stealth_status_test.go
+++ b/internal/handlers/stealth_status_test.go
@@ -74,6 +74,24 @@ func TestStealthStatusReportsAgreementWhenTheVersionsMatch(t *testing.T) {
}
}
+// With browser.version unset, the advertised version is the one the persona now
+// actually presents — the probed binary version — so page and status agree. This
+// is the wiring the fix adds: before it, advertised was the frozen fallback while
+// the binary reported something newer.
+func TestStealthStatusAdvertisesTheProbedVersionWhenConfigIsUnset(t *testing.T) {
+ resp := stealthStatusBody(t, &config.RuntimeConfig{
+ BrowserBinary: fakeBrowserBinary(t, "150.0.7871.187"),
+ })
+
+ if got := resp["advertisedBrowserVersion"]; got != "150.0.7871.187" {
+ t.Errorf("advertisedBrowserVersion = %v, want the probed binary version when browser.version is unset", got)
+ }
+ if resp["advertisedBrowserVersion"] != resp["browserBinaryVersion"] {
+ t.Errorf("advertised %v vs binary %v; with no explicit version the persona must advertise the probed one",
+ resp["advertisedBrowserVersion"], resp["browserBinaryVersion"])
+ }
+}
+
// An unprobeable binary must read as unknown rather than as a disagreement,
// or every sandboxed deployment looks like the defect.
func TestStealthStatusOmitsTheBinaryVersionWhenTheProbeFails(t *testing.T) {
diff --git a/internal/stealth/browser_version.go b/internal/stealth/browser_version.go
new file mode 100644
index 00000000..16e3db2f
--- /dev/null
+++ b/internal/stealth/browser_version.go
@@ -0,0 +1,63 @@
+package stealth
+
+import (
+ "context"
+ "log/slog"
+ "strings"
+
+ "github.com/pinchtab/pinchtab/internal/browserprobe"
+ "github.com/pinchtab/pinchtab/internal/browsers/runtimekit"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+var browserVersionCache = browserprobe.NewVersionCache(browserprobe.RunVersion)
+
+// ResolveBrowserVersion is the Chrome version the persona advertises. An explicit
+// browser.version in config wins; otherwise the launched binary is probed once per
+// resolved path and that version is advertised. A missing binary or failed probe
+// returns "", which the persona builders reduce to browserprobe.FallbackChromeVersion,
+// so a probe failure never blocks a launch.
+func ResolveBrowserVersion(cfg *config.RuntimeConfig) string {
+ return resolveBrowserVersion(browserVersionCache, cfg)
+}
+
+func resolveBrowserVersion(cache *browserprobe.VersionCache, cfg *config.RuntimeConfig) string {
+ if cfg == nil {
+ return ""
+ }
+ if explicit := strings.TrimSpace(cfg.BrowserVersion); explicit != "" {
+ return explicit
+ }
+ return cache.Version(context.Background(), runtimekit.ResolveEffectiveBrowser(cfg).Binary)
+}
+
+// ProbedBinaryVersion is the version the launched binary reports for itself,
+// independent of what the persona advertises, so a caller can compare the two. It
+// shares the resolver's cache, so a binary is probed at most once per process.
+// Empty when no binary resolves or the probe fails.
+func ProbedBinaryVersion(cfg *config.RuntimeConfig) string {
+ if cfg == nil {
+ return ""
+ }
+ return browserVersionCache.Version(context.Background(), runtimekit.ResolveEffectiveBrowser(cfg).Binary)
+}
+
+// WarnBrowserVersionMismatch logs once at launch when an explicit browser.version
+// disagrees with the launched binary. The explicit value stays authoritative — a
+// deliberate pin is honoured — but the stale-pin population the probe skips is made
+// visible and actionable rather than silently overridden.
+func WarnBrowserVersionMismatch(cfg *config.RuntimeConfig) {
+ if cfg == nil {
+ return
+ }
+ explicit := strings.TrimSpace(cfg.BrowserVersion)
+ if explicit == "" {
+ return
+ }
+ probed := ProbedBinaryVersion(cfg)
+ if probed == "" || browserprobe.CompareSemver(explicit, probed) == 0 {
+ return
+ }
+ slog.Warn("configured browser.version disagrees with the launched browser binary; the persona advertises the configured value",
+ "configured", explicit, "binary", probed, "configKey", "browser.version")
+}
diff --git a/internal/stealth/browser_version_test.go b/internal/stealth/browser_version_test.go
new file mode 100644
index 00000000..4fb65fd8
--- /dev/null
+++ b/internal/stealth/browser_version_test.go
@@ -0,0 +1,195 @@
+package stealth
+
+import (
+ "context"
+ "errors"
+ "os"
+ "path/filepath"
+ goruntime "runtime"
+ "strings"
+ "testing"
+
+ "github.com/chromedp/cdproto/emulation"
+ "github.com/pinchtab/pinchtab/internal/browserprobe"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+func majorOf(version string) string {
+ return strings.SplitN(version, ".", 2)[0]
+}
+
+func secCHUAMajor(md *emulation.UserAgentMetadata) string {
+ for _, b := range md.Brands {
+ if b.Brand == BrandChrome {
+ return b.Version
+ }
+ }
+ return ""
+}
+
+func versionLineProbe(byBinary map[string]string) func(context.Context, string) (string, error) {
+ return func(_ context.Context, binary string) (string, error) {
+ v, ok := byBinary[binary]
+ if !ok {
+ return "", errors.New("unknown binary")
+ }
+ return "Google Chrome " + v, nil
+ }
+}
+
+func personaMajor(p BrowserPersona) string {
+ for _, b := range p.UserAgentData.Brands {
+ if b.Brand == BrandChrome {
+ return b.Version
+ }
+ }
+ return ""
+}
+
+// AC2: an explicit browser.version wins and the binary is not probed at all — a
+// deliberate pin must not depend on, or pay for, spawning the binary.
+func TestResolveBrowserVersionPrefersExplicitConfigWithoutProbing(t *testing.T) {
+ cache := browserprobe.NewVersionCache(func(context.Context, string) (string, error) {
+ t.Fatal("the binary was probed even though browser.version was set explicitly")
+ return "", nil
+ })
+ got := resolveBrowserVersion(cache, &config.RuntimeConfig{
+ BrowserVersion: "199.0.1234.5",
+ BrowserBinary: "/fake/chrome",
+ })
+ if got != "199.0.1234.5" {
+ t.Errorf("resolved %q, want the explicit config version", got)
+ }
+}
+
+// AC1/AC8: with browser.version unset the resolver returns the probed binary
+// version, and that version reaches both the persona brands and the Sec-CH-UA
+// metadata. Bumping the fake binary's version changes both and nothing else.
+func TestProbedVersionReachesPersonaAndSecCHUA(t *testing.T) {
+ for _, full := range []string{"150.0.7871.187", "151.0.8000.10"} {
+ cache := browserprobe.NewVersionCache(versionLineProbe(map[string]string{"/fake/chrome": full}))
+ resolved := resolveBrowserVersion(cache, &config.RuntimeConfig{BrowserBinary: "/fake/chrome"})
+ if resolved != full {
+ t.Fatalf("resolved %q, want the probed %q", resolved, full)
+ }
+
+ persona := BuildPersona("", resolved)
+ wantMajor := majorOf(full)
+ if got := personaMajor(persona); got != wantMajor {
+ t.Errorf("persona brand major = %q, want %q", got, wantMajor)
+ }
+ if got := fullVersionMajorList(persona); got != full {
+ t.Errorf("persona fullVersionList = %q, want the full probed build %q", got, full)
+ }
+
+ override := BuildUserAgentOverride("", resolved)
+ if override == nil || override.UserAgentMetadata == nil {
+ t.Fatal("no UA-CH metadata built; Sec-CH-UA would carry no version")
+ }
+ if got := secCHUAMajor(override.UserAgentMetadata); got != wantMajor {
+ t.Errorf("Sec-CH-UA brand major = %q, want %q", got, wantMajor)
+ }
+ }
+}
+
+// AC3: a binary is probed at most once per process no matter how many persona
+// builds ask for its version — the cache stands between the request path and the
+// process spawn.
+func TestBinaryIsProbedAtMostOncePerProcess(t *testing.T) {
+ cache := browserprobe.NewVersionCache(versionLineProbe(map[string]string{"/fake/chrome": "150.0.7871.187"}))
+ cfg := &config.RuntimeConfig{BrowserBinary: "/fake/chrome"}
+ for i := 0; i < 5; i++ {
+ if v := resolveBrowserVersion(cache, cfg); v != "150.0.7871.187" {
+ t.Fatalf("resolve %d returned %q", i, v)
+ }
+ }
+ if cache.Probes() != 1 {
+ t.Errorf("probes = %d, want 1 — RunVersion spawns a process, so repeats must be served from the cache", cache.Probes())
+ }
+}
+
+// AC6: the cache is keyed by resolved binary path, so two binaries reporting
+// different versions produce two personas — cloak and ghost-chrome are separate
+// binaries and are covered by construction, with no provider-specific code.
+func TestTwoBinariesYieldTwoPersonas(t *testing.T) {
+ cache := browserprobe.NewVersionCache(versionLineProbe(map[string]string{
+ "/bin/chrome": "150.0.7871.187",
+ "/bin/cloak": "151.0.8000.10",
+ }))
+ va := resolveBrowserVersion(cache, &config.RuntimeConfig{BrowserBinary: "/bin/chrome"})
+ vb := resolveBrowserVersion(cache, &config.RuntimeConfig{BrowserBinary: "/bin/cloak"})
+
+ pa := personaMajor(BuildPersona("", va))
+ pb := personaMajor(BuildPersona("", vb))
+ if pa == pb {
+ t.Fatalf("both binaries produced persona major %q; a path-keyed probe must distinguish them", pa)
+ }
+ if pa != "150" || pb != "151" {
+ t.Errorf("persona majors = %q, %q; want 150, 151", pa, pb)
+ }
+}
+
+// AC4: a probe that fails resolves to the empty string, which the persona builders
+// reduce to the fallback, so a missing or unrunnable binary never blocks the build.
+func TestFailedProbeFallsBackWithoutError(t *testing.T) {
+ cache := browserprobe.NewVersionCache(func(context.Context, string) (string, error) {
+ return "", errors.New("binary missing")
+ })
+ resolved := resolveBrowserVersion(cache, &config.RuntimeConfig{BrowserBinary: "/does/not/exist"})
+ if resolved != "" {
+ t.Fatalf("resolved %q, want empty so the persona falls back", resolved)
+ }
+ persona := BuildPersona("", resolved)
+ wantMajor := majorOf(browserprobe.FallbackChromeVersion)
+ if got := personaMajor(persona); got != wantMajor {
+ t.Errorf("fallback persona major = %q, want %q", got, wantMajor)
+ }
+}
+
+func fullVersionMajorList(p BrowserPersona) string {
+ for _, b := range p.UserAgentData.FullVersionList {
+ if b.Brand == BrandChrome {
+ return b.Version
+ }
+ }
+ return ""
+}
+
+func fakeChromeBinary(t *testing.T, version string) string {
+ t.Helper()
+ if goruntime.GOOS == "windows" {
+ t.Skip("fake binary uses a shell script")
+ }
+ path := filepath.Join(t.TempDir(), "fake-chrome")
+ script := "#!/bin/sh\necho 'Google Chrome " + version + "'\n"
+ if err := os.WriteFile(path, []byte(script), 0o755); err != nil {
+ t.Fatalf("write fake binary: %v", err)
+ }
+ return path
+}
+
+// Wiring proof (native, since the Docker e2e that checks the wire cannot run
+// here): with browser.version unset, NewBundle's persona JSON — the script that
+// sets navigator.userAgent and userAgentData on every page — carries the version
+// the launched binary actually reports, not the frozen fallback. This is the
+// bundle.go half of AC1 that no BuildPersona-level test reaches.
+func TestNewBundlePersonaAdvertisesTheProbedBinaryVersion(t *testing.T) {
+ binary := fakeChromeBinary(t, "150.0.7871.187")
+ bundle := NewBundle(&config.RuntimeConfig{BrowserBinary: binary}, 0)
+
+ if !strings.Contains(bundle.Script, "Chrome/150.0.0.0") {
+ t.Errorf("persona script does not advertise the probed major 150; it still carries a frozen version:\n%s", firstPersonaLine(bundle.Script))
+ }
+ if strings.Contains(bundle.Script, "Chrome/144.0.0.0") {
+ t.Errorf("persona script still advertises the fallback 144 though the binary reports 150")
+ }
+}
+
+func firstPersonaLine(script string) string {
+ for _, line := range strings.Split(script, "\n") {
+ if strings.Contains(line, "userAgent") {
+ return line
+ }
+ }
+ return script
+}
diff --git a/internal/stealth/bundle.go b/internal/stealth/bundle.go
index 6ee3eb02..96735ac0 100644
--- a/internal/stealth/bundle.go
+++ b/internal/stealth/bundle.go
@@ -90,7 +90,7 @@ func NewBundle(cfg *config.RuntimeConfig, seed int64) *Bundle {
disablePinchTabStealth := config.PinchTabStealthDefaultsDisabled(cfg)
personaJSON := "{}"
if cfg != nil {
- if encoded, err := json.Marshal(BuildPersona(cfg.UserAgent, cfg.BrowserVersion)); err == nil {
+ if encoded, err := json.Marshal(BuildPersona(cfg.UserAgent, ResolveBrowserVersion(cfg))); err == nil {
personaJSON = string(encoded)
}
}
diff --git a/internal/stealth/emulation.go b/internal/stealth/emulation.go
index 4ba69e25..4323fb79 100644
--- a/internal/stealth/emulation.go
+++ b/internal/stealth/emulation.go
@@ -87,7 +87,7 @@ func ApplyTargetEmulation(ctx context.Context, cfg *config.RuntimeConfig, userAg
return fmt.Errorf("automation override: %w", err)
}
- if localeOverride := BuildLocaleOverride(userAgent, cfg.BrowserVersion); localeOverride != nil {
+ if localeOverride := BuildLocaleOverride(userAgent, ResolveBrowserVersion(cfg)); localeOverride != nil {
if err := localeOverride.Do(ctx); err != nil {
return fmt.Errorf("locale override: %w", err)
}
@@ -100,7 +100,7 @@ func ApplyTargetEmulation(ctx context.Context, cfg *config.RuntimeConfig, userAg
// (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.BrowserVersion); uaOverride != nil {
+ if uaOverride := BuildUserAgentOverride(userAgent, ResolveBrowserVersion(cfg)); 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 c5e3eedf..27871339 100644
--- a/internal/stealth/launch.go
+++ b/internal/stealth/launch.go
@@ -25,7 +25,7 @@ func BuildLaunchContract(cfg *config.RuntimeConfig, level Level) LaunchContract
customUA := ""
headless := false
if cfg != nil {
- persona = BuildPersona(cfg.UserAgent, cfg.BrowserVersion)
+ persona = BuildPersona(cfg.UserAgent, ResolveBrowserVersion(cfg))
customUA = strings.TrimSpace(cfg.UserAgent)
headless = cfg.Headless
}