Puppeteer Stealth and Anti-Detection

How Websites Detect Headless Browsers

Bot detection has become a sophisticated discipline. Anti-bot services like Cloudflare, DataDome, PerimeterX (now HUMAN), and Akamai Bot Manager analyze browser sessions across multiple dimensions to distinguish humans from automated scripts. Detection techniques fall into several categories.

JavaScript Property Checks

The most straightforward detection method examines JavaScript properties that differ between headless and regular Chrome. The navigator.webdriver property is the primary indicator. In a standard Chrome session, this property is undefined or false. In a Puppeteer-controlled browser, Chrome sets it to true by default, explicitly marking the session as automated. This single property is checked by virtually every anti-bot system as its first line of defense.

Beyond webdriver, detection scripts examine navigator.plugins (headless Chrome reports zero plugins, while regular Chrome has at least a few built-in plugins like the PDF viewer), navigator.languages (headless Chrome may report an empty or incomplete language list), and navigator.permissions (the permissions API behavior differs subtly in automated sessions). Each of these properties has a "normal" value that real browsers expose and an abnormal value that headless browsers reveal.

Browser Fingerprinting

Fingerprinting goes deeper than simple property checks. Detection services probe WebGL rendering to identify the GPU and driver combination, since headless Chrome uses software rendering with a generic GPU signature that does not match any real hardware. They examine the canvas element by rendering specific patterns and measuring the pixel-level output, which differs between GPU-accelerated and software-rendered contexts. They check the list of installed fonts, screen dimensions, color depth, hardware concurrency, and device memory values, building a composite fingerprint that is evaluated against known automation signatures.

Audio fingerprinting uses the Web Audio API to generate a short audio signal and measure its precise digital output. The computation involves the AudioContext and OscillatorNode, and the resulting fingerprint differs between real and emulated audio hardware. This technique is particularly effective because it probes a subsystem that most stealth plugins do not modify.

Behavioral Analysis

Advanced detection systems go beyond static fingerprinting and analyze how the user interacts with the page. Mouse movements, scroll patterns, typing rhythm, click timing, and navigation sequences all create behavioral signatures. Human mouse movements follow curved, slightly erratic paths with natural acceleration and deceleration. Automated cursor movements tend to be perfectly linear, instantaneous, or follow predictable patterns. Some detection systems inject invisible interactive elements (honeypots) that real users would never engage with, catching bots that click or interact with every element indiscriminately.

Timing analysis examines how quickly the page is processed after loading. Real users take time to read content, scan the page, and decide where to click. Automated scripts typically process pages in milliseconds or with unnaturally consistent timing between actions. Detection systems measure the intervals between page events and flag sessions where the timing pattern is inconsistent with human behavior.

Network and Protocol Analysis

Detection also happens at the network level. HTTP header order and composition can identify automated requests, since headless Chrome may send headers in a different order than regular Chrome, or omit headers that real browsers always include. TLS fingerprinting (JA3/JA4 hashes) examines the cipher suites and extensions offered during the TLS handshake, which differ between browser versions and automation tools. IP reputation scoring flags datacenter IP addresses, VPN endpoints, and known proxy services as higher risk than residential connections.

How Puppeteer Stealth Works

The puppeteer-extra-plugin-stealth is a plugin for the puppeteer-extra wrapper library. You install both with npm (npm install puppeteer-extra puppeteer-extra-plugin-stealth), then use puppeteer-extra instead of regular Puppeteer in your scripts. The stealth plugin hooks into the browser and page creation process and applies a collection of evasion modules automatically.

Core Evasion Modules

The stealth plugin bundles several modules, each targeting a specific detection vector. The navigator.webdriver module is the most critical, removing or overriding the webdriver property so it returns undefined instead of true. This alone defeats the most basic bot detection checks.

The chrome.runtime module adds the chrome.runtime object that exists in real Chrome extensions but is absent in headless sessions. Some detection scripts check for this object as an indicator of a genuine browser environment. The navigator.plugins module injects a realistic set of browser plugins, including the Chrome PDF Plugin and Chrome PDF Viewer that are present in standard Chrome installations but missing in headless mode.

The user-agent-override module ensures the User-Agent string is consistent across all surfaces: the HTTP request header, navigator.userAgent, and Client Hints (the modern replacement for User-Agent strings). Without this module, a mismatch between the HTTP User-Agent and the JavaScript-accessible userAgent property is a clear automation signal.

Additional modules modify WebGL vendor and renderer strings to match real GPU hardware, override the navigator.languages property with realistic language configurations, patch the navigator.permissions API behavior, and modify the iframe.contentWindow detection that some fingerprinting scripts use.

What Stealth Does Not Fix

Stealth is not a complete invisibility cloak. It primarily addresses static fingerprinting vectors, the property checks and API probes that detection scripts run when the page loads. It does not address behavioral analysis (mouse movement patterns, typing rhythm, scroll behavior), TLS fingerprinting at the network level, IP reputation scoring, or advanced audio and font fingerprinting that goes beyond the patched surfaces.

The plugin's effectiveness varies by target. Against basic Cloudflare protection and simple bot checks, stealth passes consistently. Against enterprise-grade bot detection like DataDome or HUMAN with full behavioral analysis enabled, stealth alone is not sufficient. These systems combine fingerprinting with behavioral signals and traffic reputation analysis that require additional measures beyond what any browser-side plugin can provide.

Beyond the Plugin: Additional Stealth Techniques

For targets with more aggressive bot detection, supplement the stealth plugin with additional measures.

Residential proxy rotation routes your traffic through real residential IP addresses instead of datacenter IPs, dramatically reducing the IP reputation signal that detection systems rely on. Services like Bright Data, Oxylabs, and SOAX provide rotating residential proxy pools. The cost is higher than datacenter proxies, but the detection bypass rate improves significantly for protected targets.

Human-like interaction simulation adds realistic delays, cursor movements, and scroll behavior to your automation. Instead of instant page.click() calls, move the mouse along a curved path to the target element with randomized speed and slight jitter. Add random delays between actions that follow a natural distribution (200 to 2000 milliseconds) rather than fixed intervals. Scroll in increments with variable speed rather than jumping directly to target elements.

Browser profile persistence maintains consistent fingerprints across sessions by reusing the same user data directory, cookies, and cache. Fresh browser profiles that start with no history and no cookies raise suspicion because they do not match typical user behavior. Warm up profiles by visiting a few popular sites before navigating to your target, establishing a browsing history that looks natural.

Session management distributes your requests across multiple browser profiles, IP addresses, and time windows. Avoid sending too many requests from a single profile in a short period. Rotate through a pool of browser profiles, each with its own fingerprint configuration, proxy assignment, and request budget.

Ethical and Legal Considerations

Anti-detection techniques exist in a gray area between legitimate automation and terms-of-service violations. There are valid use cases: testing your own website's bot detection, verifying that your public content is accessible, competitive price monitoring where the data is publicly visible, and academic research on web accessibility and detection systems.

However, using stealth to bypass access controls on content that is behind authentication walls, rate-limited APIs, or explicit robots.txt restrictions raises ethical and potentially legal concerns. The Computer Fraud and Abuse Act (CFAA) in the United States and similar laws in other jurisdictions can apply to accessing computer systems in ways that violate terms of service, particularly when circumventing technical access controls.

The responsible approach is to respect robots.txt directives, honor rate limits, avoid accessing content that requires authentication unless you have explicit permission, and consider whether your automation serves a legitimate purpose that the website operator would not object to. When in doubt, contact the website operator and ask for permission or an API endpoint that serves the data you need.