CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-06-19 08:10:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: sync browser stealth docs to Layer C (v1.58.3.0)

Browse Source 
BROWSER.md "Stealth scope" still described the default as navigator.webdriver
masking only; Layer C is now the always-on default across all four
context-creation paths. Update the stealth-scope prose, the "What GStack
Browser means" blurb (stock-Chrome UA, no GStackBrowser suffix, captchas can
still get through at the CDP layer), the stealth.ts source-map line, and the
env-vars table (GSTACK_STEALTH, GSTACK_CDP_STEALTH, GSTACK_GPU_*, GSTACK_PLATFORM,
GSTACK_HW_CONCURRENCY/GSTACK_DEVICE_MEMORY + the explicit --gstack-* switches and
ignoreDefaultArgs stripping). Correct the stale "narrows to navigator.webdriver
masking only" premise on the open CDP-patch TODO (the TODO itself stays open —
the CDP-protocol layer is still unaddressed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-06-18 10:34:58 -07:00
parent 7b8e932eaa
commit d04e06acd3
2 changed files with 53 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BROWSER.md
+52 -12
View File
@@ -527,10 +527,16 @@ window is being controlled.
### What "GStack Browser" means
Not your daily Chrome — a Playwright-managed Chromium with custom branding
in the Dock and menu bar, anti-bot stealth (sites like Google and NYTimes
work without captchas), a custom user agent, and the gstack extension
pre-loaded via `launchPersistentContext`. Your regular Chrome with your tabs
and bookmarks stays untouched.
in the Dock and menu bar (the `.app` name, Dock icon, and tray, NOT the UA
string), always-on Layer C anti-bot stealth (most JS-observable automation
tells are masked, so many anti-bot-protected sites load cleanly), a
stock-Chrome user agent that reports the underlying Chromium version, and the
gstack extension pre-loaded via `launchPersistentContext`. The UA no longer
carries a `GStackBrowser` suffix — that branding string was itself a
high-entropy tell, so the browser now reports a plain `Chrome/<version>` UA.
Deepest-layer CDP-protocol detection still gets through (Google can still
trigger captchas; see the CDP-patch item in `TODOS.md`). Your regular Chrome
with your tabs and bookmarks stays untouched.
### When to use headed mode
@@ -581,13 +587,42 @@ A running daemon with config A meeting a new invocation with config B exits
1 with a `browse disconnect` hint instead of silently restarting and dropping
tab state, cookies, or sessions.
**Stealth scope.** When `--headed` or `--proxy` are set, `$B` masks
`navigator.webdriver` only — via Chromium's
`--disable-blink-features=AutomationControlled` plus a small init script.
We do NOT fake `navigator.plugins`, `navigator.languages`, or `window.chrome`
— modern fingerprinters check those for consistency, and synthesizing fixed
values can flag MORE bot-like, not less. ChromeDriver's `cdc_` runtime
artifacts and the Permissions API patch are still cleaned up.
**Stealth scope (Layer C, always on).** Every context — headless `launch`,
`--headed`/`--proxy`, `handoff`, and the `useragent`/`viewport --scale`
rebuild (`recreateContext`) — gets the full Layer C mask, no opt-in flag.
Layer C masks `navigator.webdriver`, restores the `window.chrome.*` shape
(`runtime`, `app`, `csi`, `loadTimes`), aligns `Notification.permission`
with the Permissions API, reports a per-install
`hardwareConcurrency`/`deviceMemory` from the host profile, sweeps the known
Selenium/Phantom/Nightmare/Playwright globals, and installs a
`Function.prototype.toString` proxy so every patched getter reports
`[native code]` even under the depth-3 recursion check. It still does NOT
fake `navigator.plugins` or `navigator.languages` — modern fingerprinters
cross-check those for consistency, and synthesizing fixed values flags MORE
bot-like, not less. ChromeDriver's `cdc_`/`__webdriver` runtime artifacts and
the Permissions notifications tell are also cleaned up on every path.
`GSTACK_STEALTH=extended` (also accepts `1` or `true`; off by default) layers
six more aggressive patches on top — WebGL renderer spoof, a faked
`navigator.plugins` PluginArray, `navigator.mediaDevices`. That mode actively
lies and can break sites that reflect on those properties; use it only when
the default triggers detection. For gbrowser builds with the C++ patches, the
`GSTACK_*` host-profile env (GPU vendor/renderer, UA-CH platform/model,
hardware) emits the Pack 1 `--gstack-gpu-vendor` / `--gstack-gpu-renderer` /
`--gstack-ua-platform` / `--gstack-ua-model` / `--gstack-hw-concurrency` /
`--gstack-device-memory` switches that push the GPU/UA-CH/hardware spoof down
to native code, and `GSTACK_CDP_STEALTH=on` (or `1`/`true`) emits the Pack 2
`--gstack-suppress-prepare-stack-trace` switch (closes the Cloudflare
`Error.prepareStackTrace` canary). On stock Playwright Chromium every one of
these switches is a safe no-op.
`launchHeaded` / `handoff` also strip Playwright's automation-tell launch
defaults via `ignoreDefaultArgs` (`STEALTH_IGNORE_DEFAULT_ARGS`):
`--enable-automation` (the "Chrome is being controlled by automated test
software" infobar), `--disable-extensions`,
`--disable-component-extensions-with-background-pages`,
`--disable-popup-blocking`, `--disable-component-update`, and
`--disable-default-apps`.
**Container support.** `--headed` on Linux without `DISPLAY` walks the
display range (`:99`, `:100`, ...) until `xdpyinfo` reports a free slot,
@@ -1164,6 +1199,11 @@ the global `~/.gstack/browser-skills/foo/` only inside project-a.
| `GSTACK_BROWSE_MAX_HTML_BYTES` | 52428800 (50MB) | `load-html` size cap |
| `GSTACK_SECURITY_OFF` | unset | Emergency kill switch — disable ML classifier |
| `GSTACK_SECURITY_ENSEMBLE` | unset | Set to `deberta` for 3-classifier ensemble (721MB download) |
| `GSTACK_STEALTH` | unset | Set to `extended` (also accepts `1`/`true`) to layer six aggressive patches (WebGL spoof, faked plugins, mediaDevices) on top of Layer C. Actively lies; can break sites. |
| `GSTACK_CDP_STEALTH` | unset | Set to `on`/`1`/`true` to emit `--gstack-suppress-prepare-stack-trace` (gbrowser Pack 2 / B11 C++ patch only; no-op on stock Chromium) |
| `GSTACK_GPU_VENDOR`, `GSTACK_GPU_RENDERER`, `GSTACK_GPU_CHIPSET` | unset | Per-install GPU spoof fed to the Pack 1 WebGL/UA-CH C++ patches. Set by gbd from the host profile; emitted as `--gstack-gpu-vendor` / `--gstack-gpu-renderer` / `--gstack-ua-model` cmdline switches only when present. |
| `GSTACK_PLATFORM` | unset | Host platform classification (`MacARM`/`MacIntel` → `macOS`, `Win32` → `Windows`, `Linux*` → `Linux`) emitted as `--gstack-ua-platform` |
| `GSTACK_HW_CONCURRENCY`, `GSTACK_DEVICE_MEMORY` | host profile (fallback 8) | Per-install `hardwareConcurrency`/`deviceMemory` reported by Layer C and emitted as `--gstack-hw-concurrency` / `--gstack-device-memory` for the worker-navigator C++ patch |
---
@@ -1179,7 +1219,7 @@ browse/
│ ├── proxy-config.ts # --proxy URL parsing + cred resolution (URL vs env, fail-fast on both)
│ ├── proxy-redact.ts # Cred-redaction helper for any proxy URL surfaced to logs/errors
│ ├── xvfb.ts # Xvfb auto-spawn + orphan cleanup with PID + start-time validation
│ ├── stealth.ts # navigator.webdriver mask + cdc_ cleanup + Permissions API patch
│ ├── stealth.ts # Layer C: webdriver mask + window.chrome.* + Notification/Permissions + per-install hardware + toString proxy + automation-global sweep; buildGStackLaunchArgs (GSTACK_* cmdline switches); GSTACK_STEALTH=extended opt-in
│ ├── browse-client.ts # Canonical SDK — what skills import as _lib/browse-client.ts
│ ├── snapshot.ts # AX tree → @e/@c refs → Locator map; -D/-a/-C handling
│ ├── read-commands.ts # Non-mutating: text, html, links, js, css, is, dialog, ...
TODOS.md
+1 -1
View File
@@ -1994,7 +1994,7 @@ Shipped in v0.6.5. TemplateContext in gen-skill-docs.ts bakes skill name into pr
**What:** Write a postinstall script that patches Playwright's CDP layer to suppress `Runtime.enable` and use `addBinding` for context ID discovery, same approach as rebrowser-patches. Eliminates the `navigator.webdriver`, `cdc_` markers, and other CDP artifacts that sites like Google use to detect automation.
**Why:** Our current stealth narrows to `navigator.webdriver` masking + ChromeDriver `cdc_` runtime cleanup + Permissions API patch (v1.28.0.0 narrowed it from also faking plugins/languages, since modern fingerprinters punish inconsistent fakes more than they punish admitted defaults). That's enough for most sites but Google still triggers captchas, because the real detection is at the CDP protocol level. rebrowser-patches proved the approach works but their patches target Playwright 1.52.0 and don't apply to our 1.58.2. We need our own patcher using string matching instead of line-number diffs. 6 files, ~200 lines of patches total.
**Why:** As of v1.58.3.0 our JS-layer stealth is "Layer C" — always-on `navigator.webdriver` mask + `window.chrome.*` shape + `Notification.permission`/Permissions alignment + per-install `hardwareConcurrency`/`deviceMemory` + a `Function.prototype.toString` proxy + an automation-global sweep + ChromeDriver `cdc_`/`__webdriver` cleanup (still NOT faking plugins/languages, since modern fingerprinters punish inconsistent fakes more than they punish admitted defaults). That closes most JS-observable tells, but Google still triggers captchas because the deepest detection is at the CDP protocol level, which a page-world init script can't reach. rebrowser-patches proved the CDP approach works but their patches target Playwright 1.52.0 and don't apply to our 1.58.2. We need our own patcher using string matching instead of line-number diffs. 6 files, ~200 lines of patches total. (Layer C's toString proxy still has descriptor/Reflect.ownKeys surfaces; pushing the spoofs to native code via CDP suppression or the Chromium fork makes the JS layer obsolete.)
**Context:** Full analysis of rebrowser-patches source: patches 6 files in `playwright-core/lib/server/` (crConnection.js, crDevTools.js, crPage.js, crServiceWorker.js, frames.js, page.js). Key technique: suppress `Runtime.enable` (the main CDP detection vector), use `Runtime.addBinding` + `CustomEvent` trick to discover execution context IDs without it. Our extension communicates via Chrome extension APIs, not CDP Runtime, so it should be unaffected. Write E2E tests that verify: (1) extension still loads and connects, (2) Google.com loads without captcha, (3) sidebar chat still works.