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

fingerprinting-evasions.mddocs/

Browser Fingerprinting Evasions

Advanced evasion techniques that modify browser fingerprinting vectors including media codecs, WebGL properties, and comprehensive user agent handling. These evasions target sophisticated detection methods that analyze browser capabilities and characteristics.

Capabilities

User Agent Override Evasion

Comprehensive user agent management that fixes user agent strings, platform information, and user agent client hints.

// Evasion name: 'user-agent-override'
// Fixes: User agent string, Accept-Language header, navigator.platform, UA client hints

Configuration Options:

interface UserAgentOptions {
  /** Custom user agent string (default: auto-generated from browser) */
  userAgent?: string;
  /** Locale for Accept-Language header (default: 'en-US,en') */
  locale?: string;
  /** Whether to mask Linux as Windows (default: true) */
  maskLinux?: boolean;
}

This evasion:

  • Strips "HeadlessChrome" from user agent strings
  • Optionally masks Linux systems as Windows for better anonymity
  • Sets consistent Accept-Language headers
  • Provides accurate user agent client hints (brands, platform, architecture)
  • Coordinates with user preferences plugin for browser language settings

Detection Methods Prevented:

// These detection methods will be fooled:

// 1. Headless Chrome detection
if (navigator.userAgent.includes('HeadlessChrome')) {
  // Would detect headless mode
}

// 2. Platform inconsistency detection  
if (navigator.platform === 'Linux' && navigator.userAgent.includes('Windows')) {
  // Would detect user agent spoofing
}

// 3. Language header inconsistency
// Accept-Language header now matches navigator.languages

Usage Examples:

// Use default user agent override
const stealth = StealthPlugin({
  enabledEvasions: new Set(['user-agent-override'])
});

// Custom user agent and locale
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
const UserAgentOverride = require('puppeteer-extra-plugin-stealth/evasions/user-agent-override');

const customUA = UserAgentOverride({
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
  locale: 'de-DE,de',
  maskLinux: false
});

puppeteer.use(customUA);

Media Codecs Evasion

Fixes media codec detection to prevent fingerprinting through supported audio/video formats.

// Evasion name: 'media.codecs'
// Fixes: HTMLMediaElement.canPlayType() responses for realistic codec support

This evasion:

  • Provides realistic responses to video.canPlayType() and audio.canPlayType()
  • Ensures codec support matches the simulated browser environment
  • Prevents detection through unusual codec support patterns
  • Covers common formats: MP4, WebM, OGG, etc.

Detection Method Prevented:

// This detection method will be fooled:
const video = document.createElement('video');
const codecs = ['video/mp4', 'video/webm', 'video/ogg'];
const support = codecs.map(codec => video.canPlayType(codec));

if (support.every(s => s === '')) {
  // Would detect unusual lack of codec support
}

WebGL Vendor Evasion

Fixes WebGL vendor and renderer information to prevent graphics-based fingerprinting.

// Evasion name: 'webgl.vendor'
// Fixes: WebGL vendor and renderer strings for realistic GPU fingerprinting

This evasion:

  • Modifies WEBGL_debug_renderer_info extension responses
  • Provides realistic vendor strings (e.g., "Google Inc.")
  • Sets believable renderer information (e.g., "ANGLE (Intel HD Graphics)")
  • Prevents detection through unusual WebGL properties

Detection Method Prevented:

// This detection method will be fooled:
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl');
const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');

if (debugInfo) {
  const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
  const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
  
  if (vendor.includes('SwiftShader') || renderer.includes('SwiftShader')) {
    // Would detect software rendering indicating automation
  }
}

Usage Examples:

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

// Enable fingerprinting evasions
const fingerprintStealth = StealthPlugin({
  enabledEvasions: new Set([
    'user-agent-override',
    'media.codecs',
    'webgl.vendor'
  ])
});

puppeteer.use(fingerprintStealth);

const browser = await puppeteer.launch();
const page = await browser.newPage();

// Fingerprinting will now return realistic values
await page.evaluate(() => {
  // User agent is clean
  console.log(navigator.userAgent); // No "HeadlessChrome"
  
  // Media codecs work normally
  const video = document.createElement('video');
  console.log(video.canPlayType('video/mp4')); // "probably" or "maybe"
  
  // WebGL vendor is realistic
  const canvas = document.createElement('canvas');
  const gl = canvas.getContext('webgl');
  const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
  if (debugInfo) {
    console.log(gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL)); // "Google Inc."
  }
});

Advanced Configuration

User Agent Override Options

// Minimal user agent override (keeps original user agent, just removes headless indicators)
const minimalUA = StealthPlugin({
  enabledEvasions: new Set(['user-agent-override'])
});

// Custom user agent with specific locale
const UserAgentOverride = require('puppeteer-extra-plugin-stealth/evasions/user-agent-override');
const customUA = UserAgentOverride({
  userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
  locale: 'en-GB,en',
  maskLinux: false
});

// Don't mask Linux (keep original platform)
const linuxUA = UserAgentOverride({
  maskLinux: false,
  locale: 'en-US,en'
});

Coordinated Fingerprinting Protection

These evasions work together to provide comprehensive fingerprinting protection:

// Full fingerprinting protection
const fullFingerprintProtection = StealthPlugin({
  enabledEvasions: new Set([
    'user-agent-override',  // Clean user agent and headers
    'media.codecs',         // Realistic media support  
    'webgl.vendor',         // Clean WebGL fingerprint
    'navigator.languages',  // Consistent language reporting
    'navigator.plugins',    // Realistic plugin list
    'window.outerdimensions' // Proper window dimensions
  ])
});

Implementation Details

User Agent Processing

The user agent override evasion:

  1. Captures Original: Gets the browser's natural user agent
  2. Removes Headless Indicators: Strips "HeadlessChrome/" and similar markers
  3. Platform Masking: Optionally changes Linux indicators to Windows
  4. Client Hints Generation: Creates matching user agent client hints
  5. Header Coordination: Sets Accept-Language header to match navigator.languages

Media Codec Simulation

The media codecs evasion:

  1. Overrides canPlayType: Intercepts HTMLMediaElement.prototype.canPlayType calls
  2. Provides Realistic Responses: Returns appropriate "probably", "maybe", or "" responses
  3. Format Coverage: Handles all common video/audio formats and codecs
  4. Version Awareness: Adapts responses based on the browser version being simulated

WebGL Fingerprint Modification

The WebGL vendor evasion:

  1. Extension Interception: Modifies WEBGL_debug_renderer_info extension
  2. Parameter Override: Changes UNMASKED_VENDOR_WEBGL and UNMASKED_RENDERER_WEBGL
  3. Realistic Values: Provides common vendor/renderer combinations
  4. Consistency Maintenance: Ensures WebGL properties align with user agent

Security and Privacy Considerations

These fingerprinting evasions:

  • Reduce Trackability: Make browsers harder to fingerprint and track
  • Improve Privacy: Reduce the uniqueness of browser fingerprints
  • Maintain Functionality: Don't break websites that rely on proper codec/WebGL detection
  • Require Responsibility: Should be used ethically and in compliance with website terms

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