Skip to content

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

12.3 KB
Raw Blame
package stealth

import (
	"crypto/sha256"
	"encoding/json"
	"fmt"
	"strings"

	"github.com/pinchtab/pinchtab/internal/assets"
	"github.com/pinchtab/pinchtab/internal/browsers"
	"github.com/pinchtab/pinchtab/internal/config"
)

type Level string

const (
	LevelLight  Level = "light"
	LevelMedium Level = "medium"
	LevelFull   Level = "full"
)

type LaunchMode string

const (
	LaunchModeUninitialized  LaunchMode = "uninitialized"
	LaunchModeAllocator      LaunchMode = "allocator"
	LaunchModeDirectFallback LaunchMode = "direct_fallback"
	LaunchModeAttached       LaunchMode = "attached"
	LaunchModeRemoteCDP      LaunchMode = "remote-cdp"
)

type WebdriverMode string

const (
	WebdriverModeNativeBaseline WebdriverMode = "native_baseline"
)

type Bundle struct {
	Level                    Level           `json:"level"`
	Provider                 string          `json:"provider"`
	Native                   bool            `json:"native"`
	PinchTabOverlaysDisabled bool            `json:"pinchtabOverlaysDisabled"`
	Seed                     int64           `json:"seed"`
	Script                   string          `json:"-"`
	ScriptHash               string          `json:"scriptHash"`
	Launch                   LaunchContract  `json:"-"`
	PatchIDs                 []string        `json:"patchIds"`
	Capabilities             map[string]bool `json:"capabilities"`
	Tradeoffs                []string        `json:"tradeoffs,omitempty"`
	Webdriver                WebdriverMode   `json:"webdriverMode"`
}

type Status struct {
	Level                    Level           `json:"level"`
	Provider                 string          `json:"provider"`
	Native                   bool            `json:"native"`
	Headless                 bool            `json:"headless"`
	LaunchMode               LaunchMode      `json:"launchMode"`
	ScriptHash               string          `json:"scriptHash"`
	UserAgent                string          `json:"userAgent,omitempty"`
	FingerprintSeed          string          `json:"fingerprintSeed,omitempty"`
	WebdriverMode            WebdriverMode   `json:"webdriverMode"`
	PinchTabOverlaysDisabled bool            `json:"pinchtabOverlaysDisabled"`
	PatchIDs                 []string        `json:"patchIds"`
	Flags                    map[string]bool `json:"flags"`
	Capabilities             map[string]bool `json:"capabilities"`
	// ProviderCapabilities is advisory; omitted for empty/unknown providers to preserve legacy JSON shape.
	ProviderCapabilities   []string        `json:"providerCapabilities,omitempty"`
	Tradeoffs              []string        `json:"tradeoffs,omitempty"`
	TabOverrides           map[string]bool `json:"tabOverrides"`
	AttachMutationsSkipped bool            `json:"attachMutationsSkipped,omitempty"`
	// AdvertisedBrowserVersion is the version the persona presents to pages.
	// BrowserBinaryVersion is what the launched binary reports for itself; the
	// two disagreeing is the defect a caller can now observe rather than infer.
	AdvertisedBrowserVersion string `json:"advertisedBrowserVersion,omitempty"`
	BrowserBinaryVersion     string `json:"browserBinaryVersion,omitempty"`
}

func NewBundle(cfg *config.RuntimeConfig, seed int64) *Bundle {
	levelName := ""
	headless := false
	provider := config.BrowserChrome
	if cfg != nil {
		levelName = cfg.StealthLevel
		headless = cfg.Headless
		provider = config.NormalizeBrowser(cfg.DefaultBrowser)
	}
	level := NormalizeLevel(levelName)
	nativeCloak := config.CloakBrowserActive(cfg)
	disablePinchTabStealth := config.PinchTabStealthDefaultsDisabled(cfg)
	personaJSON := "{}"
	if cfg != nil {
		if encoded, err := json.Marshal(BuildPersona(cfg.UserAgent, ResolveBrowserVersion(cfg))); err == nil {
			personaJSON = string(encoded)
		}
	}
	script := renderBundleScript(level, personaJSON, seed, headless)
	hashSource := renderBundleScript(level, personaJSON, 0, headless)
	patchIDs := patchIDsForLevel(level, headless)
	capabilities := capabilityMap(level, headless)
	tradeoffIDs := tradeoffs(level)
	if disablePinchTabStealth {
		script = renderNativeCloakScript()
		hashSource = script
		patchIDs = nativeCloakPatchIDs()
		capabilities = nativeCloakCapabilityMap()
		tradeoffIDs = nil
	}

	return &Bundle{
		Level:                    level,
		Provider:                 provider,
		Native:                   nativeCloak,
		PinchTabOverlaysDisabled: disablePinchTabStealth,
		Seed:                     seed,
		Script:                   script,
		// Keep the status hash stable across identical configs even when the
		// per-process seed changes. The seed is runtime entropy, not contract.
		ScriptHash:   hashScript(hashSource),
		Launch:       BuildLaunchContract(cfg, level),
		PatchIDs:     patchIDs,
		Capabilities: capabilities,
		Tradeoffs:    tradeoffIDs,
		Webdriver:    WebdriverModeNativeBaseline,
	}
}

func renderBundleScript(level Level, personaJSON string, seed int64, headless bool) string {
	return fmt.Sprintf(
		"var __pinchtab_seed = %d;\nvar __pinchtab_stealth_level = %q;\nvar __pinchtab_headless = %t;\nvar __pinchtab_profile = %s;\n%s\n%s",
		seed,
		level,
		headless,
		personaJSON,
		assets.StealthScript,
		PopupGuardInitScript,
	)
}

func renderNativeCloakScript() string {
	return PopupGuardInitScript
}

func NormalizeLevel(level string) Level {
	switch strings.ToLower(strings.TrimSpace(level)) {
	case string(LevelMedium):
		return LevelMedium
	case string(LevelFull):
		return LevelFull
	default:
		return LevelLight
	}
}

func StatusFromBundle(bundle *Bundle, cfg *config.RuntimeConfig, launchMode LaunchMode) *Status {
	if bundle == nil {
		return nil
	}

	status := &Status{
		Level:                    bundle.Level,
		Provider:                 bundle.Provider,
		Native:                   bundle.Native,
		Headless:                 cfg != nil && cfg.Headless,
		LaunchMode:               launchMode,
		ScriptHash:               bundle.ScriptHash,
		UserAgent:                bundle.LaunchUserAgent(),
		FingerprintSeed:          statusFingerprintSeed(cfg),
		WebdriverMode:            bundle.Webdriver,
		PinchTabOverlaysDisabled: bundle.PinchTabOverlaysDisabled,
		PatchIDs:                 append([]string(nil), bundle.PatchIDs...),
		Flags:                    statusFlags(bundle, cfg),
		Capabilities:             cloneBoolMap(bundle.Capabilities),
		ProviderCapabilities:     providerCapabilityStrings(bundle.Provider),
		Tradeoffs:                append([]string(nil), bundle.Tradeoffs...),
		TabOverrides: map[string]bool{
			"fingerprintRotateActive": false,
		},
	}
	if status.LaunchMode == "" {
		status.LaunchMode = LaunchModeUninitialized
	}
	if status.LaunchMode == LaunchModeAttached || status.LaunchMode == LaunchModeRemoteCDP {
		status.AttachMutationsSkipped = true
		status.Tradeoffs = append(status.Tradeoffs,
			"external attach: PinchTab skips launch-only stealth, locale, animation, and Runtime-domain mutations")
	}
	return status
}

func providerCapabilityStrings(provider string) []string {
	b, ok := browsers.Get(provider)
	if !ok {
		return nil
	}
	caps := b.Capabilities().List()
	if len(caps) == 0 {
		return nil
	}
	out := make([]string, len(caps))
	for i, c := range caps {
		out[i] = string(c)
	}
	return out
}

func statusFingerprintSeed(cfg *config.RuntimeConfig) string {
	if cfg == nil || !config.IsCloakBrowser(cfg.DefaultBrowser) {
		return ""
	}
	return cfg.Cloak.FingerprintSeed
}

func hashScript(script string) string {
	sum := sha256.Sum256([]byte(script))
	return fmt.Sprintf("sha256:%x", sum)
}

func statusFlags(bundle *Bundle, cfg *config.RuntimeConfig) map[string]bool {
	var extraFlags []string
	headless := false
	if cfg != nil {
		extraFlags = config.AllowedBrowserExtraFlags(cfg.BrowserExtraFlags)
		headless = cfg.Headless
	}

	flags := map[string]bool{}
	if bundle != nil {
		flags = cloneBoolMap(bundle.Launch.Flags)
	}
	flags["headlessNew"] = headless
	flags["swiftshader"] = headless
	flags["testTypeGPU"] = hasFlag(extraFlags, "--test-type=gpu")
	flags["disableInfobars"] = hasFlag(extraFlags, "--disable-infobars")
	flags["disableDesktopNotifications"] = hasFlag(extraFlags, "--disable-desktop-notifications")
	flags["disableWindowActivation"] = hasFlag(extraFlags, "--disable-window-activation")
	flags["silentDebuggerExtensionAPI"] = hasFlag(extraFlags, "--silent-debugger-extension-api")
	return flags
}

func hasFlag(args []string, want string) bool {
	for _, field := range args {
		if field == want {
			return true
		}
	}
	return false
}

func capabilityMap(level Level, headless bool) map[string]bool {
	caps := map[string]bool{
		"webdriverNotTrue":                  true,
		"webdriverNativeStrategy":           true,
		"batteryAPIBaseline":                true,
		"pluginArray":                       true,
		"workerHardwareConsistency":         true,
		"workerUserAgentConsistency":        true,
		"serviceWorkerHardwareConsistency":  true,
		"serviceWorkerUserAgentConsistency": true,
		"userAgentData":                     false,
		"chromeRuntimeConnect":              false,
		"chromeRuntimeSendMessage":          false,
		"chromeApp":                         false,
		"videoCodecs":                       false,
		"maxTouchPoints":                    false,
		"iframeIsolation":                   false,
		"errorStackSanitized":               false,
		"functionToStringMasked":            false,
		"functionToStringNative":            true,
		"intlLocaleCoherent":                true,
		"errorPrepareStackTraceNative":      true,
		"navigatorOverridesAbsent":          true,
		"userAgentDataVersionCoherent":      true,
		"downlinkMax":                       true,
		"webglSpoofing":                     false,
		"canvasNoise":                       false,
		"systemColorFix":                    false,
		"transparentPixelCanvasNoise":       false,
		"audioNoise":                        false,
		"webrtcMitigation":                  false,
	}

	if level == LevelMedium || level == LevelFull {
		caps["userAgentData"] = true
		caps["maxTouchPoints"] = true
	}
	if level == LevelMedium {
		caps["iframeIsolation"] = true
		caps["chromeRuntimeConnect"] = true
		caps["chromeRuntimeSendMessage"] = true
	}
	if level == LevelFull {
		caps["functionToStringMasked"] = true
		caps["errorStackSanitized"] = true
		if headless {
			caps["webglSpoofing"] = true
		}
	}

	return caps
}

func patchIDsForLevel(level Level, headless bool) []string {
	patches := []string{
		"marker-cleanup",
		"webdriver-native-baseline",
		"plugins",
		"languages",
		"platform",
		"downlink-max",
		"permissions",
		"battery",
	}
	if headless {
		patches = append(patches, "screen")
	}

	if level == LevelMedium || level == LevelFull {
		patches = append(patches,
			"user-agent-data",
			"touch-points",
		)
	}
	if level == LevelMedium {
		patches = append(patches, "chrome-runtime", "iframe-isolation")
	}
	if level == LevelFull {
		if headless {
			patches = append(patches, "screen-position")
		}
		if headless {
			patches = append(patches, "webgl")
		}
	}

	return patches
}

func nativeCloakPatchIDs() []string {
	return []string{
		"native-cloakbrowser",
		"popup-guard",
	}
}

func nativeCloakCapabilityMap() map[string]bool {
	caps := capabilityMap(LevelLight, false)
	caps["nativeCloakBrowser"] = true
	caps["sourceLevelFingerprinting"] = true
	caps["pinchtabJSOverlays"] = false
	caps["canvasNoise"] = true
	caps["audioNoise"] = true
	caps["webglSpoofing"] = true
	caps["webrtcMitigation"] = true
	// The PinchTab worker-UA-parity script is replaced by the popup-guard-only
	// native cloak script, so don't advertise PinchTab-provided worker UA
	// parity. (workerHardwareConsistency/serviceWorkerHardwareConsistency also
	// inherit true and warrant the same native-vs-advertised confirmation —
	// follow-up, not flipped here.)
	caps["workerUserAgentConsistency"] = false
	caps["serviceWorkerUserAgentConsistency"] = false
	return caps
}

func tradeoffs(level Level) []string {
	switch level {
	case LevelMedium:
		return []string{
			"non-default-risk-mode",
			"api-realism-risk",
		}
	case LevelFull:
		return []string{
			"non-default-risk-mode",
			"api-realism-risk",
			"graphics-and-media-breakage-risk",
		}
	default:
		return nil
	}
}

func cloneBoolMap(src map[string]bool) map[string]bool {
	if src == nil {
		return nil
	}
	dst := make(map[string]bool, len(src))
	for k, v := range src {
		dst[k] = v
	}
	return dst
}

func (b *Bundle) LaunchUserAgent() string {
	if b == nil {
		return ""
	}
	for _, arg := range b.Launch.Args {
		if strings.HasPrefix(arg, "--user-agent=") {
			return strings.TrimPrefix(arg, "--user-agent=")
		}
	}
	return ""
}