CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-puppeteer-extra-plugin-stealth

Stealth mode plugin for puppeteer-extra that applies various techniques to make detection of headless browsers harder.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

core-plugin.mddocs/

Core Plugin Management

Core plugin functionality for configuring and managing stealth evasions. The main StealthPlugin class controls which evasion techniques are active and provides access to plugin metadata.

Capabilities

StealthPlugin Factory Function

Creates a new stealth plugin instance with optional configuration.

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

Usage Examples:

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

// Enable all evasions (default behavior)
const stealthPlugin = StealthPlugin();

// Enable only specific evasions
const customStealth = StealthPlugin({
  enabledEvasions: new Set([
    'navigator.webdriver',
    'user-agent-override',
    'chrome.runtime'
  ])
});

// Use with puppeteer-extra
const puppeteer = require('puppeteer-extra');
puppeteer.use(stealthPlugin);

StealthPlugin Class

Main plugin class that extends PuppeteerExtraPlugin and manages stealth evasion techniques.

class StealthPlugin extends PuppeteerExtraPlugin {
  /**
   * Constructor for StealthPlugin
   * @param opts - Configuration options object
   */
  constructor(opts?: Record<string, any>);
}

Plugin Name

Unique identifier for the stealth plugin.

/**
 * Plugin identifier name
 * @returns Always returns 'stealth'
 */
get name(): string;

Default Configuration

Default configuration including all available evasion techniques.

/**
 * Default plugin configuration
 * @returns Object containing available and enabled evasions
 */
get defaults(): {
  availableEvasions: Set<string>;
  enabledEvasions: Set<string>;
};

Available Evasions

Get all available evasion technique names.

/**
 * Get all available evasion techniques
 * @returns Set of all available evasion technique names
 */
get availableEvasions(): Set<string>;

The available evasions include:

  • chrome.app
  • chrome.csi
  • chrome.loadTimes
  • chrome.runtime
  • defaultArgs
  • iframe.contentWindow
  • media.codecs
  • navigator.hardwareConcurrency
  • navigator.languages
  • navigator.permissions
  • navigator.plugins
  • navigator.webdriver
  • sourceurl
  • user-agent-override
  • webgl.vendor
  • window.outerdimensions

Enabled Evasions Management

Get or set which evasion techniques are currently enabled.

/**
 * Get currently enabled evasion techniques
 * @returns Set of enabled evasion technique names
 */
get enabledEvasions(): Set<string>;

/**
 * Set which evasion techniques should be enabled
 * @param evasions - Set of evasion technique names to enable
 */
set enabledEvasions(evasions: Set<string>): void;

Usage Examples:

const stealth = StealthPlugin();

// View enabled evasions
console.log(stealth.enabledEvasions);
// Set { 'chrome.app', 'chrome.csi', ... all evasions }

// Remove specific evasion
stealth.enabledEvasions.delete('navigator.plugins');

// Add specific evasion back
stealth.enabledEvasions.add('navigator.plugins');

// Replace with custom set
stealth.enabledEvasions = new Set([
  'navigator.webdriver',
  'user-agent-override'
]);

Browser Setup Hook

Browser-level configuration hook that executes when a browser instance is created.

/**
 * Browser setup hook for configuring browser-level options
 * @param browser - Browser instance from puppeteer
 * @returns Promise that resolves when setup is complete
 */
onBrowser(browser: any): Promise<void>;

This method:

  • Sets the maximum number of event listeners to 30 to prevent warnings
  • Is called automatically by the puppeteer-extra plugin system
  • Should not be called manually by users

Plugin Dependencies

Internal system for managing dynamic plugin dependencies based on enabled evasions.

/**
 * Internal dependency management (private)
 * @returns Set of plugin dependency paths
 */
get dependencies(): Set<string>;

This property:

  • Automatically generates dependency paths for enabled evasions
  • Is used internally by the puppeteer-extra plugin system
  • Should not be accessed directly by users
  • Returns paths in format: stealth/evasions/${evasionName}

Configuration Patterns

Selective Evasion Usage

// Enable only navigator-related evasions
const navigatorStealth = StealthPlugin({
  enabledEvasions: new Set([
    'navigator.webdriver',
    'navigator.languages',
    'navigator.plugins',
    'navigator.hardwareConcurrency',
    'navigator.permissions'
  ])
});

// Enable only Chrome API evasions
const chromeStealth = StealthPlugin({
  enabledEvasions: new Set([
    'chrome.app',
    'chrome.csi',
    'chrome.loadTimes',
    'chrome.runtime'
  ])
});

Dynamic Evasion Management

const stealth = StealthPlugin();

// Start with all evasions, then remove problematic ones
stealth.enabledEvasions.delete('chrome.runtime');
stealth.enabledEvasions.delete('navigator.plugins');

// Or start minimal and add as needed
const minimal = StealthPlugin({
  enabledEvasions: new Set(['navigator.webdriver'])
});

// Add more evasions later
minimal.enabledEvasions.add('user-agent-override');
minimal.enabledEvasions.add('window.outerdimensions');

Install with Tessl CLI

npx tessl i tessl/npm-puppeteer-extra-plugin-stealth

docs

chrome-evasions.md

core-plugin.md

fingerprinting-evasions.md

index.md

misc-evasions.md

navigator-evasions.md

window-frame-evasions.md

tile.json