agent-browser-stealth 0.14.0-fork.4 → 0.14.0-fork.5

package/README.md

@@ -1,163 +1,199 @@
 # agent-browser-stealth
 
-Stealth-focused fork of `agent-browser` for anti-bot evasion in production automation.
+Stealth-first fork of `agent-browser` for production browser automation under anti-bot pressure.
 
-This fork keeps core browser automation capabilities in sync with upstream `agent-browser`, and focuses its own changes on stealth and anti-detection behavior.
+This README focuses on stealth architecture and principles. For full command coverage inherited from upstream, use:
 
-## Positioning
+- upstream docs: <https://github.com/vercel-labs/agent-browser>
+- local help: `agent-browser --help`
 
-- Core commands and workflows: aligned with upstream `agent-browser`
-- Fork value: stronger anti-bot defaults and operational policies
-- Default mindset: no extra stealth toggle, stealth is always on
+## What This Fork Optimizes
 
-## Installation
+- 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`).
 
-### Global (recommended)
-
-```bash
-npm install -g agent-browser-stealth
-agent-browser install
-```
-
-### Quick try with npx
-
-```bash
-npx agent-browser-stealth install
-npx agent-browser-stealth open example.com
-```
+## Quick Start
 
-### From source
+### Install
 
 ```bash
-git clone https://github.com/leeguooooo/agent-browser
-cd agent-browser
-pnpm install
-pnpm build
-pnpm build:native
-pnpm link --global
+npm install -g agent-browser-stealth
 agent-browser install
 ```
 
-## Quick Start
+### Minimal Usage
 
 ```bash
 agent-browser open https://example.com
 agent-browser snapshot -i
 agent-browser click @e2
-agent-browser fill @e3 "test@example.com"
-agent-browser screenshot page.png
 ```
 
-## Anti-Bot Measures
+## Stealth Architecture
+
+```mermaid
+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"]
+```
 
-Stealth is always enabled. Legacy `launch.stealth` is accepted only for compatibility and ignored.
+### Policy by Connection Mode
 
-### 1) Fingerprint hardening
+| 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 |
 
-- Hides automation indicators such as `navigator.webdriver`
-- Adds Chromium launch args to reduce automation fingerprints
-- Rewrites headless UA markers (`HeadlessChrome`)
-- Patches high-signal surfaces such as:
-  - `navigator.plugins` / `navigator.mimeTypes`
-  - `window.chrome.runtime`
-  - WebGL vendor/renderer exposure
-  - permissions/language/media/device related probes
-- Applies both context init scripts and CDP-level UA overrides
-- Preserves explicit custom UA from `--user-agent` or `launch({ userAgent })`
+## Principle 1: Always-On Stealth with Explicit Boundaries
 
-### 2) Behavioral humanization
+- 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.
 
-- Randomized typing cadence when `--delay` is used
-- Random wait ranges (`wait 2000-5000`)
-- Bezier-curve mouse movement before click actions
-- Randomized navigation pacing
+## Principle 2: Multi-Layer Fingerprint Hardening
 
-### 3) Region signal alignment
+### 2.1 Launch Layer (Local Chromium)
 
-- Auto-aligns locale/timezone/Accept-Language by target TLD
-- Reduces locale-timezone mismatch risk on region-sensitive sites
+Injected Chromium args:
 
-### 4) Verification-aware retry
+- `--disable-blink-features=AutomationControlled`
+- `--use-gl=angle`
+- `--use-angle=default`
 
-- Detects common captcha/verification interstitial patterns
-- Retries navigation with randomized backoff when triggered
+If no custom UA is set, the runtime UA is normalized to remove `HeadlessChrome` tokens.
 
-## Typing `--delay` Correctly
+### 2.2 CDP Layer (Browser/Page Targets)
 
-Use `--delay` as an option:
+- 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.
 
-```bash
-agent-browser type @e2 "iphone" --delay 120
-agent-browser keyboard type "iphone" --delay 120
-```
+### 2.3 Context Init-Script Layer (Patch Inventory)
 
-If literal text includes `--delay`, stop option parsing with `--`:
+The init script patch set is injected before page scripts and currently includes:
 
-```bash
-agent-browser type @e2 -- "--delay 120"
-agent-browser keyboard type -- "--delay 120"
-```
+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.
 
-## Validation Snapshot
+## Principle 3: Behavioral Humanization
 
-Manual checks were run against common public detection pages in headed mode, including:
+- 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.
 
-- [bot.sannysoft.com](https://bot.sannysoft.com/)
-- [CreepJS](https://abrahamjuliot.github.io/creepjs/)
-- [areyouheadless](https://arh.antoinevastel.com/bots/areyouheadless)
-- [detect-headless](https://infosimples.github.io/detect-headless)
+## Principle 4: Region Signal Alignment
 
-Reproduce CreepJS check:
+Before navigation, the runtime derives region hints from target URL TLD and aligns:
 
-```bash
-node scripts/check-creepjs-headless.js --binary ./cli/target/release/agent-browser
-```
+- locale
+- timezone
+- `Accept-Language`
+
+Examples of built-in mappings include `tw`, `jp`, `kr`, `sg`, `de`, `fr`, `uk`, `in`, `au`.
 
-## Command Coverage And Docs
+Manual overrides are supported:
 
-Core command set is intentionally kept compatible with upstream `agent-browser`.
+- `AGENT_BROWSER_LOCALE`
+- `AGENT_BROWSER_TIMEZONE` (or `TZ`)
 
-- Full command reference: [upstream agent-browser docs](https://github.com/vercel-labs/agent-browser)
-- Local help: `agent-browser --help`
+## Principle 5: Verification-Aware Risk Control
 
-## Fork Policies
+When a navigation lands on verification/captcha pages, structured risk signals are generated from URL/title evidence.
 
-This fork enforces a few operational policies:
+`riskSignals` include:
 
-- `--profile` / `AGENT_BROWSER_PROFILE` are forbidden
-- `--channel` / `AGENT_BROWSER_CHANNEL` are forbidden
-- Default mode expects an existing browser via CDP on `localhost:9333`
+- `code`
+- `source` (`url` or `title`)
+- `evidence`
+- `confidence`
 
-## Maintainer Notes (Fork Release)
+### Risk Mode
 
-- Keep `upstream-main` for clean upstream sync
-- Merge upstream into short-lived sync branches, then PR into `main`
-- Recommended release format: `<upstream>-fork.<fork>` (example: `0.14.0-fork.3`)
-- Use npm Trusted Publishing (OIDC)
+- `warn` (default): retry with randomized backoff and return warnings + `riskSignals`.
+- `block`: fail fast once verification/captcha interstitial is detected.
+- `off`: skip detection/retry path.
 
-## OpenClaw Skill Sync
+```bash
+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
+```
 
-This repo includes a dedicated OpenClaw skill at:
+```mermaid
+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"]
+```
 
-- `skills/agent-browser-stealth/SKILL.md`
+## Operational Recommendations
 
-Local git `pre-push` hook auto-syncs skills before every push:
+- 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.
 
-- `.husky/pre-push` -> `pnpm run clawhub:sync`
+## Validation Scripts
 
-Manual sync command (same logic as hook):
+Run public detector checks after stealth changes:
 
 ```bash
-pnpm run clawhub:sync
+node scripts/check-sannysoft-webdriver.js --binary ./cli/target/release/agent-browser
+node scripts/check-creepjs-headless.js --binary ./cli/target/release/agent-browser
 ```
 
-This uses your existing local ClawHub login session (no GitHub secret required).
+## Upstream Compatibility
 
-Temporarily skip auto-sync for one push:
-
-```bash
-SKIP_CLAWHUB_SYNC=1 git push
-```
+This fork intentionally keeps command workflows close to upstream while concentrating custom behavior in stealth, policy, and anti-detection handling.
 
 ## License
 

package/dist/actions.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserManager, ScreencastFrame } from './browser.js';
-import type { Command, Response } from './types.js';
+import type { Command, Response, RiskSignal } from './types.js';
 /**
  * Set the callback for screencast frames
  * This is called by the daemon to set up frame streaming
@@ -14,4 +14,8 @@ export declare function toAIFriendlyError(error: unknown, selector: string): Err
  * Execute a command and return a response
  */
 export declare function executeCommand(command: Command, browser: BrowserManager): Promise<Response>;
+/**
+ * Detect verification/captcha interstitials and return structured risk evidence.
+ */
+export declare function detectRiskSignals(url: string, title: string): RiskSignal[];
 //# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAUpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAmIT,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuRjG"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAUpE,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAmIR,UAAU,EACX,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC,GAAG,IAAI,GAClD,IAAI,CAEN;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAqDzE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuRjG;AAyGD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CA8C1E"}

package/dist/actions.js

@@ -359,65 +359,114 @@ async function handleNavigate(command, browser) {
     await page.goto(command.url, {
         waitUntil: command.waitUntil ?? 'load',
     });
-    // Detect captcha/verification pages and retry with backoff
-    const finalUrl = page.url();
-    const title = await page.title();
-    const captchaDetected = isCaptchaPage(finalUrl, title);
-    if (captchaDetected) {
-        const maxRetries = 2;
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            const backoff = 3000 + Math.random() * 4000;
-            await page.waitForTimeout(Math.round(backoff));
-            await page.goto(command.url, {
-                waitUntil: command.waitUntil ?? 'load',
-            });
-            const retryUrl = page.url();
-            const retryTitle = await page.title();
-            if (!isCaptchaPage(retryUrl, retryTitle)) {
-                return successResponse(command.id, {
-                    url: retryUrl,
-                    title: retryTitle,
-                });
-            }
-        }
-        // All retries exhausted -- return the page as-is with a warning
+    const riskMode = command.riskMode ?? 'warn';
+    if (riskMode === 'off') {
         return successResponse(command.id, {
             url: page.url(),
             title: await page.title(),
-            warning: 'Captcha/verification page detected. Try --headed mode or use --session-name for state persistence.',
         });
     }
+    // Detect risk interstitials (captcha/verification) and handle by risk mode.
+    const finalUrl = page.url();
+    const title = await page.title();
+    let encounteredSignals = detectRiskSignals(finalUrl, title);
+    if (encounteredSignals.length === 0) {
+        return successResponse(command.id, {
+            url: finalUrl,
+            title,
+        });
+    }
+    if (riskMode === 'block') {
+        const first = encounteredSignals[0];
+        return errorResponse(command.id, `Navigation blocked by risk-mode=block: ${first.code} (${first.source}="${first.evidence}")`);
+    }
+    const maxRetries = 2;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        const backoff = 3000 + Math.random() * 4000;
+        await page.waitForTimeout(Math.round(backoff));
+        await page.goto(command.url, {
+            waitUntil: command.waitUntil ?? 'load',
+        });
+        const retryUrl = page.url();
+        const retryTitle = await page.title();
+        const retrySignals = detectRiskSignals(retryUrl, retryTitle);
+        if (retrySignals.length === 0) {
+            return successResponse(command.id, {
+                url: retryUrl,
+                title: retryTitle,
+                warning: 'Risk interstitial detected and recovered after retry. Review riskSignals for evidence.',
+                riskSignals: encounteredSignals,
+            });
+        }
+        encounteredSignals = mergeRiskSignals(encounteredSignals, retrySignals);
+    }
+    // All retries exhausted -- return the page as-is with a warning and evidence.
     return successResponse(command.id, {
-        url: finalUrl,
-        title,
+        url: page.url(),
+        title: await page.title(),
+        warning: 'Captcha/verification page detected. Try --headed mode or use --session-name for state persistence.',
+        riskSignals: encounteredSignals,
     });
 }
-function isCaptchaPage(url, title) {
+function mergeRiskSignals(current, next) {
+    const merged = new Map();
+    for (const signal of [...current, ...next]) {
+        const key = `${signal.code}|${signal.source}|${signal.evidence}`;
+        if (!merged.has(key) || (merged.get(key)?.confidence ?? 0) < signal.confidence) {
+            merged.set(key, signal);
+        }
+    }
+    return [...merged.values()];
+}
+/**
+ * Detect verification/captcha interstitials and return structured risk evidence.
+ */
+export function detectRiskSignals(url, title) {
     const lowerUrl = url.toLowerCase();
     const lowerTitle = title.toLowerCase();
-    const captchaPatterns = [
-        '/verify/captcha',
-        '/captcha',
-        '/challenge',
-        'scene=crawler',
-        'scene=anti_bot',
-        'recaptcha',
-        'hcaptcha',
+    const urlPatterns = [
+        { pattern: '/verify/captcha', code: 'captcha_interstitial', confidence: 0.98 },
+        { pattern: '/captcha', code: 'captcha_interstitial', confidence: 0.95 },
+        { pattern: '/challenge', code: 'verification_interstitial', confidence: 0.93 },
+        { pattern: 'scene=crawler', code: 'bot_challenge', confidence: 0.99 },
+        { pattern: 'scene=anti_bot', code: 'bot_challenge', confidence: 0.99 },
+        { pattern: 'recaptcha', code: 'captcha_interstitial', confidence: 0.97 },
+        { pattern: 'hcaptcha', code: 'captcha_interstitial', confidence: 0.97 },
     ];
     const titlePatterns = [
-        'verify',
-        'captcha',
-        'challenge',
-        'attention required',
-        'just a moment',
-        'checking your browser',
-        'access denied',
-        '驗證',
-        '验证',
-        '人机验证',
+        { pattern: 'verify', code: 'verification_interstitial', confidence: 0.78 },
+        { pattern: 'captcha', code: 'captcha_interstitial', confidence: 0.9 },
+        { pattern: 'challenge', code: 'verification_interstitial', confidence: 0.8 },
+        { pattern: 'attention required', code: 'verification_interstitial', confidence: 0.96 },
+        { pattern: 'just a moment', code: 'verification_interstitial', confidence: 0.95 },
+        { pattern: 'checking your browser', code: 'verification_interstitial', confidence: 0.97 },
+        { pattern: 'access denied', code: 'access_gate', confidence: 0.86 },
+        { pattern: '驗證', code: 'verification_interstitial', confidence: 0.88 },
+        { pattern: '验证', code: 'verification_interstitial', confidence: 0.88 },
+        { pattern: '人机验证', code: 'captcha_interstitial', confidence: 0.95 },
     ];
-    return (captchaPatterns.some((p) => lowerUrl.includes(p)) ||
-        titlePatterns.some((p) => lowerTitle.includes(p)));
+    const signals = [];
+    for (const item of urlPatterns) {
+        if (lowerUrl.includes(item.pattern)) {
+            signals.push({
+                code: item.code,
+                source: 'url',
+                evidence: item.pattern,
+                confidence: item.confidence,
+            });
+        }
+    }
+    for (const item of titlePatterns) {
+        if (lowerTitle.includes(item.pattern)) {
+            signals.push({
+                code: item.code,
+                source: 'title',
+                evidence: item.pattern,
+                confidence: item.confidence,
+            });
+        }
+    }
+    return mergeRiskSignals([], signals);
 }
 function bezierPoint(t, p0, p1, p2, p3) {
     const u = 1 - t;