@nxhung/stealth-browser

Playwright integration for browser fingerprinting evasion — stealth capabilities for automated browsers.

npm install @nxhung/stealth-browser
npm install playwright
npx playwright install chromium

Why?

Modern anti-bot systems detect automation by fingerprinting browser properties: canvas rendering, WebGL output, AudioContext, Navigator APIs, timezone, and dozens of other signals. @nxhung/stealth-browser neutralizes these vectors with a modular Playwright integration.

Features

| Category | Features | |----------|----------| | Automation markers | webdriver undefined, chrome.runtime stub, Playwright globals removal | | Canvas | getImageData noise injection | | WebGL | vendor/renderer spoofing | | Audio | AudioContext hook with noise | | Navigator | userAgent, platform, languages, permissions, doNotTrack | | Timezone | locale and timezone spoofing | | Hardware | hardwareConcurrency, deviceMemory, devicePixelRatio | | Screen | resolution, colorDepth |

Quick Start

StealthBrowser (Recommended)

import { StealthBrowser } from '@nxhung/stealth-browser';

const browser = await StealthBrowser.launch({
  headless: true,
  stealth: {
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/124.0.0.0',
    locale: 'en-US',
    timezone: 'America/New_York',
    screen: { width: 1920, height: 1080, availWidth: 1920, availHeight: 1040 },
    hardwareConcurrency: 8,
    deviceMemory: 8,
    devicePixelRatio: 1,
  },
});

const page = await browser.newPage();
await page.goto('https://example.com');
// ... you're now stealthy
await browser.close();

Payload Injection

Generate stealth payload for manual injection:

import { buildStealthPayload } from '@nxhung/stealth-browser';

const payload = buildStealthPayload({
  userAgent: 'Mozilla/5.0 Chrome/124',
  locale: 'en-US',
  timezone: 'America/New_York',
});

await page.addInitScript(payload);

CDP Patches (Chromium only)

For advanced stealth, apply CDP-level patches:

import { applyAllCDPPatches } from '@nxhung/stealth-browser';

const browser = await chromium.launch();
const page = await browser.newPage();
await applyAllCDPPatches(page);

CLI

Launch any URL with a preset stealth profile:

npx stealth --url https://example.com --preset windows_chrome

Available Presets

| Preset | Browser | OS | Screen | |--------|---------|-----|--------| | windows_chrome | Chrome 124 | Windows 10 | 1920×1080 | | macos_chrome | Chrome 124 | macOS | 1440×900 | | linux_firefox | Firefox 125 | Linux | 1920×1080 | | windows_edge | Edge 124 | Windows 10 | 1920×1080 | | mobile_chrome | Chrome 124 | Android | 412×915 |

CLI Options

--url <url>        Target URL (required)
--preset <name>    Use a preset (windows_chrome, macos_chrome, etc.)
--headless         Run in headless mode
--no-stealth       Disable stealth features (for comparison)
--browser <name>   Override browser (chromium, firefox, webkit)
--timeout <ms>     Navigation timeout (default: 30000)

API Reference

StealthBrowser

Static factory for launching stealth browsers.

class StealthBrowser {
  static async launch(options: BrowserLaunchOptions & {
    stealth?: StealthConfig;
  }): Promise<Browser>;

  static buildStealthPayload(config: StealthConfig): string;
}

StealthConfig

interface StealthConfig {
  userAgent?: string;
  locale?: string;
  timezone?: string;
  screen?: { width: number; height: number; availWidth: number; availHeight: number };
  hardwareConcurrency?: number;
  deviceMemory?: number;
  devicePixelRatio?: number;
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Public API (integrations/)                   │
├─────────────────────────────────────────────────────────────┤
│  playwright-stealth.ts     │  cdp-patches.ts   │  cli/       │
│  • StealthBrowser          │  • applyCDP*     │  • presets  │
│  • buildStealthPayload     │  • removeCDP*   │  • flags    │
├─────────────────────────────────────────────────────────────┤
│                    stealth.ts (Orchestrator)                  │
│  • StealthConfig interface                                    │
│  • applyAllPatches()                                        │
├─────────────────────────────────────────────────────────────┤
│                    Browser Context                            │
│  Patches modify prototypes to return spoofed values          │
└─────────────────────────────────────────────────────────────┘

Two integration paths:

• JS Injection: Patches run in page context via addInitScript
• CDP: Patches run before page JS via Page.addScriptToEvaluateOnNewDocument (Chromium only)

Browser Support

| Browser | JS Injection | CDP | |---------|-------------|-----| | Chromium 112+ | ✅ | ✅ | | Firefox 111+ | ✅ | ❌ | | WebKit 16.4+ | ✅ | ❌ |

Documentation

• docs/project-overview-pdr.md — Motivation, problem statement, user stories
• docs/codebase-summary.md — File-by-file breakdown
• docs/code-standards.md — TypeScript standards, integration patterns
• docs/system-architecture.md — Architecture diagrams, data flow
• docs/project-roadmap.md — Roadmap, feature priorities
• docs/deployment-guide.md — npm publishing, build process
• docs/design-guidelines.md — Design principles

License

MIT