agent-browser-stealth

Stealth-first fork of agent-browser for production browser automation under anti-bot pressure.

This README focuses on stealth architecture and principles. For full command coverage inherited from upstream, use:

• upstream docs: https://github.com/vercel-labs/agent-browser
• local help: agent-browser --help

What This Fork Optimizes

• Stealth is always on (legacy launch.stealth is accepted but ignored).
• Fingerprint surfaces are patched at multiple layers (launch args, CDP overrides, init scripts).
• Behavioral signals are humanized (typing cadence, cursor path, pacing, retry backoff).
• Region signals are auto-aligned (locale/timezone/Accept-Language) to reduce mismatch risk.
• Verification/captcha handling is policy-driven (--risk-mode off|warn|block).

Quick Start

Install

npm install -g agent-browser-stealth
agent-browser install

Minimal Usage

agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e2

Stealth Architecture

flowchart TD
  A["Command Input"] --> B["Stealth Policy Resolver"]
  B --> C["Connection Mode Detection"]
  C --> D["Launch Layer: Chromium Args"]
  C --> E["CDP Layer: UA + Metadata Override"]
  C --> F["Context Layer: Init Script Patches"]
  D --> G["Behavior Layer: Humanized Interaction"]
  E --> G
  F --> G
  G --> H["Risk Layer: Verification Detection and Handling"]
  H --> I["Response with warnings and riskSignals"]

Loading

Policy by Connection Mode

Mode	Stealth Capabilities	Notes
Local Chromium launch	Chromium launch args + CDP UA override + context init scripts	Most complete stack
Existing browser via CDP	CDP UA override + context init scripts	No local Chromium arg injection
Cloud provider (browserbase/browseruse)	Context init scripts	Remote browser runtime controls launch layer
Kernel provider	Context init scripts + provider-managed stealth	Provider-side stealth may also apply

Principle 1: Always-On Stealth with Explicit Boundaries

• Stealth defaults to enabled and does not depend on a runtime toggle.
• Project policy forbids:
  • --profile / AGENT_BROWSER_PROFILE
  • --channel / AGENT_BROWSER_CHANNEL
• Default CLI policy expects an existing browser on CDP localhost:9333 unless explicit connection options are provided.

Principle 2: Multi-Layer Fingerprint Hardening

2.1 Launch Layer (Local Chromium)

Injected Chromium args:

• --disable-blink-features=AutomationControlled
• --use-gl=angle
• --use-angle=default

If no custom UA is set, the runtime UA is normalized to remove HeadlessChrome tokens.

2.2 CDP Layer (Browser/Page Targets)

• Uses Emulation.setUserAgentOverride to align:
  • userAgent
  • acceptLanguage
  • userAgentMetadata brands and versions
• Applies overrides for existing/new targets, including worker-relevant contexts.
• Forces opaque white background (Emulation.setDefaultBackgroundColorOverride) to avoid headless transparency fingerprints.

2.3 Context Init-Script Layer (Patch Inventory)

The init script patch set is injected before page scripts and currently includes:

1. navigator.webdriver removal (including prototype-level cleanup).
2. CSS webdriver heuristic neutralization (CSS.supports('border-end-end-radius: initial') probe).
3. window.chrome.runtime bootstrap for missing runtime surfaces.
4. Locale/language normalization (navigator.language, navigator.languages).
5. Realistic navigator.plugins and navigator.mimeTypes.
6. navigator.permissions.query normalization for notifications.
7. WebGL vendor/renderer masking when SwiftShader indicators are present.
8. cdc_ property cleanup on document/documentElement.
9. Window/screen dimension normalization (outerWidth/outerHeight/screenX/screenY).
10. Screen availability patching (availWidth/availHeight).
11. Hardware concurrency stabilization.
12. Notification permission consistency.
13. Active text color heuristic patching.
14. navigator.connection normalization.
15. Worker network signal normalization (downlinkMax).
16. prefers-color-scheme light-mode heuristic neutralization.
17. navigator.share exposure.
18. navigator.contacts exposure.
19. contentIndex exposure.
20. navigator.pdfViewerEnabled normalization.
21. Media devices surface normalization.
22. navigator.userAgent cleanup (strip HeadlessChrome).
23. navigator.userAgentData brand cleanup.
24. performance.memory stabilization.
25. Default background color patching at script level.

Principle 3: Behavioral Humanization

• Navigation pacing jitter before goto (short randomized delay).
• Typing jitter for type --delay and keyboard type --delay:
  • per-character randomized delay around the requested base delay (about ±40%).
• Click path humanization:
  • cursor moves on a Bezier-like curve before click.
• Wait supports random ranges (wait min-max) for non-uniform timing.

Principle 4: Region Signal Alignment

Before navigation, the runtime derives region hints from target URL TLD and aligns:

• locale
• timezone
• Accept-Language

Examples of built-in mappings include tw, jp, kr, sg, de, fr, uk, in, au.

Manual overrides are supported:

• AGENT_BROWSER_LOCALE
• AGENT_BROWSER_TIMEZONE (or TZ)

Principle 5: Verification-Aware Risk Control

When a navigation lands on verification/captcha pages, structured risk signals are generated from URL/title evidence.

riskSignals include:

• code
• source (url or title)
• evidence
• confidence

Risk Mode

• warn (default): retry with randomized backoff and return warnings + riskSignals.
• block: fail fast once verification/captcha interstitial is detected.
• off: skip detection/retry path.

agent-browser --risk-mode warn open https://example.com
agent-browser --risk-mode block open https://example.com
AGENT_BROWSER_RISK_MODE=off agent-browser open https://example.com

flowchart TD
  A["Navigate"] --> B["Collect URL and Title Signals"]
  B --> C{"risk-mode"}
  C -->|off| D["Return Success"]
  C -->|block| E["Return Error with First Signal"]
  C -->|warn| F["Retry up to 2 times"]
  F --> G{"Signals Cleared"}
  G -->|yes| H["Return Success + recovery warning + riskSignals"]
  G -->|no| I["Return Success + warning + riskSignals"]

Loading

Operational Recommendations

• Prefer --headed for high-friction targets.
• Reuse session state with --session-name for continuity.
• Keep locale/timezone consistent with target market.
• Use --risk-mode block in strict pipelines that require explicit operator intervention on verification pages.
• For cookies set, use either --url <url>, or --domain <domain> --path <path> together.
• If --url, --domain, and --path are all omitted, the cookie is scoped from the current page URL.

Validation Scripts

Run public detector checks after stealth changes:

node scripts/check-sannysoft-webdriver.js --binary ./cli/target/release/agent-browser
node scripts/check-creepjs-headless.js --binary ./cli/target/release/agent-browser

Upstream Compatibility

This fork intentionally keeps command workflows close to upstream while concentrating custom behavior in stealth, policy, and anti-detection handling.

License

Apache-2.0