stealthii/STEALTH_PATCHES.md

# Stealth Patches

`retoor <retoor@molodetz.nl>`

This document enumerates every modification stealthii applies to the
underlying Chromium/Playwright stack and the rationale for each. It is
maintained as living documentation: any change to `stealth_js.py` or the
launch arguments in `client.py` must be reflected here in the same commit.

## Launch-level patches

Applied in `Stealthii._ensure_browser_locked()` at browser launch.

| Flag | Effect |
|---|---|
| `--disable-blink-features=AutomationControlled` | Removes the `navigator.webdriver` flag and associated automation-only code paths at the engine level, before any JS patch runs. |
| `ignore_default_args=['--enable-automation']` | Playwright passes `--enable-automation` to Chromium by default, which enables the automation infobar and related detectable behaviour. Suppressed. |
| `--no-sandbox` | Required to run headless Chromium as a non-root, unprivileged process in this deployment environment. Not a stealth measure. |
| `--disable-dev-shm-usage` | Avoids `/dev/shm` exhaustion under containerized/limited-memory environments. Not a stealth measure. |
| `--disk-cache-size=<bytes>` / `--media-cache-size=<bytes>` | Bounds Chromium's own on-disk HTTP/media cache, configurable via `disk_cache_bytes` (default near-zero). Not a stealth measure - an operational safeguard against unbounded disk growth in a long-lived process. |

## JS-level patches

Applied via `context.add_init_script(STEALTH_INIT_JS)` on every context
before any page script runs, so the patched state is present from the very
first document, including cross-origin iframes.

### `navigator.webdriver`

Redefined to return `undefined`. This flag is `true` on any
CDP-automated Chromium and is the single most widely checked automation
signal.

### `window.chrome`

A stock headless Chromium launched via Playwright does not expose
`window.chrome` at all, unlike a real Chrome install. When absent, a
`window.chrome` object is constructed with `runtime`, `loadTimes`, `csi`,
and `app` members shaped like the real object's public surface.

### `navigator.permissions.query`

A stock headless Chromium reports `denied` for a `notifications`
permission query while `Notification.permission` itself still reports
`default` - a mismatch a real browser never produces. The query is
patched to always return the same value as `Notification.permission`
for that one permission name; all other permission names are passed
through to the original implementation unmodified.

### `navigator.plugins` / `navigator.mimeTypes`

A stock headless Chromium reports an empty plugin list and a
`navigator.plugins` value that is a plain array rather than a
`PluginArray`. Five entries matching Chrome's real built-in PDF-plugin
set (`PDF Viewer`, `Chrome PDF Viewer`, `Chromium PDF Viewer`,
`Microsoft Edge PDF Viewer`, `WebKit built-in PDF`) are constructed, each
individually reassigned the real `Plugin.prototype`, and the containing
array reassigned `PluginArray.prototype` - including
`Symbol.toStringTag`, so both a property count check and a
`Object.prototype.toString.call(...)` type check pass. `navigator.mimeTypes`
is patched the same way for the corresponding `application/pdf` MIME type.

### `navigator.deviceMemory`, `navigator.hardwareConcurrency`

Set to `8` each. Present mainly for consistency with the spoofed WebGL
GPU (below) and a realistic desktop profile; a stock headless Chromium
already reports plausible values here in most cases.

### `WebGLRenderingContext.prototype.getParameter` / `WebGL2RenderingContext.prototype.getParameter`

A stock headless Chromium renders WebGL through SwiftShader (a software
rasterizer), which reports `UNMASKED_VENDOR_WEBGL` (constant `37445`) as
`Google Inc. (Google)` and `UNMASKED_RENDERER_WEBGL` (constant `37446`)
containing the literal string `SwiftShader` - an unambiguous headless
signal checked by essentially every fingerprinting script. Both
constants are intercepted and rewritten to report a real discrete GPU
(`Google Inc. (NVIDIA)` / an ANGLE-wrapped `NVIDIA GeForce RTX 3060`
string); every other parameter is passed through unmodified.

### `HTMLIFrameElement.prototype.contentWindow`

A known secondary check reads `window.chrome` from inside a freshly
created, same-origin iframe rather than the top-level document - since
each document gets its own JS globals, an iframe's `window.chrome` can
be absent even when the top-level one was patched. The `contentWindow`
getter is wrapped so that, whenever the returned window is missing
`chrome`, it is assigned from the outer patched value before being
returned.

### `Function.prototype.toString` spoofing on every patch above

Every function or getter installed by the patches above is wrapped in a
`Proxy` whose own `toString` is overridden to return the exact string a
real native function produces (`function name() { [native code] }`).
Without this, a page can distinguish a patched native method from a real
one by calling `.toString()` on it and observing actual JavaScript source
instead of the native-code marker - a check used by several stealth-
detection scripts specifically to unmask other stealth patches.

## Verification

Patches are verified against
[bot.sannysoft.com](https://bot.sannysoft.com)'s full detection table
(`tests/test_stealth_detection.py::test_sannysoft_detection_suite_is_clean`),
run on every change. As of the current `STEALTH_INIT_JS`, every row on
that page passes, including `WebDriver (New)`, `Chrome (New)`,
`Plugins is of type PluginArray`, `WebGL Vendor`/`WebGL Renderer`, and
the `HEADCHR_*`/`PHANTOM_*`/`SELENIUM_DRIVER` probe blocks.

The `get`/`post`/`put`/`patch`/`delete`/`head`/`download` fast path (no
tab, `context.request`) is separately verified
(`test_fast_path_uses_real_chromium_fingerprint`) to carry a JA3/JA4
hash distinct from a plain Python `aiohttp` client, confirming it uses
the browser's own TLS stack rather than Python's.

## Known limitations

- The `context.request` fast path negotiates HTTP/1.1, not HTTP/2 - a
  real Chrome page load always uses HTTP/2 against an HTTP/2-capable
  server. A system that cross-checks the TLS fingerprint against the
  negotiated protocol can detect this specific inconsistency. `render()`
  (full page navigation) does not have this limitation.
- None of the above defeats IP-reputation-based rate limiting, nor the
  behavioural layer of systems such as DataDome or a Cloudflare managed
  challenge. Those require a clean source IP and, for the hardest
  targets, human-like interaction; stealthii's patches remove
  fingerprint-level tells, not behavioural ones.
- Verified against Chromium's stock headless build as shipped with
  Playwright at the time of writing. A Chromium upgrade can change
  default values the patches assume (plugin list shape, WebGL constants,
  permission defaults); re-run the sannysoft regression test after any
  Playwright/Chromium version bump.