Puppeteer Extra Plugin Stealth

Puppeteer Extra Plugin Stealth is a comprehensive stealth mode plugin for puppeteer-extra and playwright-extra that applies various techniques to make detection of headless browsers harder. It provides 17 different evasion techniques that can be selectively enabled to avoid detection by anti-bot systems.

Package Information

• Package Name: puppeteer-extra-plugin-stealth
• Package Type: npm
• Language: JavaScript with TypeScript definitions
• Installation: npm install puppeteer-extra-plugin-stealth

Core Imports

const StealthPlugin = require('puppeteer-extra-plugin-stealth');

For TypeScript:

import StealthPlugin from 'puppeteer-extra-plugin-stealth';

Basic Usage

const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');

// Use stealth plugin with all evasions enabled
puppeteer.use(StealthPlugin());

// Launch browser with stealth mode
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();

// Navigate normally - stealth techniques are applied automatically
await page.goto('https://example.com');
await browser.close();

Using Individual Evasions

Individual evasion techniques can be used independently without the main stealth plugin:

const puppeteer = require('puppeteer-extra');

// Use only specific evasions
puppeteer.use(require('puppeteer-extra-plugin-stealth/evasions/navigator.webdriver')());
puppeteer.use(require('puppeteer-extra-plugin-stealth/evasions/user-agent-override')());

const browser = await puppeteer.launch({ headless: true });

Architecture

The Puppeteer Extra Plugin Stealth is built around several key components:

• Main Plugin Class: StealthPlugin extends PuppeteerExtraPlugin and manages evasion techniques
• Modular Evasions: 17 individual evasion techniques that can be independently enabled/disabled
• Utility System: Shared utilities for stealth API manipulation and proxy management
• Dynamic Dependencies: Plugin dependencies are loaded based on enabled evasions
• Browser Integration: Hooks into puppeteer's lifecycle events for seamless stealth application

Capabilities

Core Plugin Management

Main plugin functionality for configuring and managing stealth evasions. Controls which evasion techniques are active and provides access to plugin metadata.

/**
 * Creates a new stealth plugin instance
 * @param opts - Configuration options
 * @param opts.enabledEvasions - Set of evasion names to enable
 * @returns StealthPlugin instance
 */
function StealthPlugin(opts?: {
  enabledEvasions?: Set<string>;
}): StealthPlugin;

class StealthPlugin extends PuppeteerExtraPlugin {
  /** Plugin identifier */
  get name(): string;
  
  /** Default configuration with all available evasions */
  get defaults(): {
    availableEvasions: Set<string>;
    enabledEvasions: Set<string>;
  };
  
  /** Get all available evasion technique names */
  get availableEvasions(): Set<string>;
  
  /** Get/set currently enabled evasion techniques */
  get enabledEvasions(): Set<string>;
  set enabledEvasions(evasions: Set<string>): void;
  
  /** Browser setup hook for configuring browser-level options */
  onBrowser(browser: any): Promise<void>;
}

Core Plugin Management

Chrome API Evasions

Evasion techniques that mock Chrome-specific APIs to prevent detection through missing Chrome objects. These evasions simulate the presence of Chrome extension APIs.

// Available Chrome API evasions:
// - chrome.app: Mocks chrome.app API
// - chrome.csi: Mocks chrome.csi API  
// - chrome.loadTimes: Mocks chrome.loadTimes API
// - chrome.runtime: Mocks chrome.runtime API

Chrome API Evasions

Navigator Object Evasions

Evasion techniques that modify navigator properties to hide headless browser indicators. These techniques fix various navigator object properties that can reveal automation.

// Available Navigator evasions:
// - navigator.hardwareConcurrency: Fixes hardware concurrency reporting
// - navigator.languages: Fixes language array detection
// - navigator.permissions: Fixes permission API behavior
// - navigator.plugins: Mocks browser plugins
// - navigator.vendor: Overrides navigator.vendor property
// - navigator.webdriver: Removes webdriver property

Navigator Evasions

Browser Fingerprinting Evasions

Advanced evasion techniques that modify browser fingerprinting vectors including media codecs, WebGL properties, and user agent handling.

// Available fingerprinting evasions:
// - media.codecs: Fixes media codec detection
// - webgl.vendor: Fixes WebGL vendor information
// - user-agent-override: Comprehensive user agent management

Browser Fingerprinting Evasions

Window and Frame Evasions

Evasion techniques that fix window dimension and iframe-related detection methods.

// Available window/frame evasions:
// - window.outerdimensions: Fixes outer window dimensions in headless mode
// - iframe.contentWindow: Fixes iframe content window detection

Window and Frame Evasions

Miscellaneous Evasions

Additional evasion techniques for launch arguments and source code obfuscation.

// Available miscellaneous evasions:
// - defaultArgs: Modifies default Puppeteer launch arguments
// - sourceurl: Removes source URL traces from injected code

Miscellaneous Evasions

Configuration Options

interface StealthOptions {
  /** Set of evasion technique names to enable (default: all available) */
  enabledEvasions?: Set<string>;
}

Available Evasion Techniques

The following evasion techniques are available:

• chrome.app - Mocks Chrome app API
• chrome.csi - Mocks Chrome CSI API
• chrome.loadTimes - Mocks Chrome loadTimes API
• chrome.runtime - Mocks Chrome runtime API
• defaultArgs - Modifies default launch arguments
• iframe.contentWindow - Fixes iframe detection
• media.codecs - Fixes media codec fingerprinting
• navigator.hardwareConcurrency - Fixes hardware concurrency
• navigator.languages - Fixes language detection
• navigator.permissions - Fixes permission API
• navigator.plugins - Mocks browser plugins
• navigator.vendor - Overrides navigator.vendor property
• navigator.webdriver - Removes webdriver property
• sourceurl - Removes source URL traces
• user-agent-override - Comprehensive user agent handling
• webgl.vendor - Fixes WebGL vendor fingerprinting
• window.outerdimensions - Fixes window dimensions