Invisible Automation: Using puppeteer-extra-plugin-stealth to Bypass Bot Protection

Want to bypass bot detection systems while automating Chrome? The puppeteer-extra-plugin-stealth is a tool that helps hide automation fingerprints, making it harder for websites to detect bots.

Key Takeaways:

What it does: Masks automation markers (like navigator.webdriver) and mimics real browser behavior.
How it works: Adjusts browser fingerprints, introduces natural browsing patterns, and manages session details.
Why it matters: Helps avoid detection from advanced anti-bot systems like CAPTCHA challenges and browser fingerprinting.
Setup: Install Puppeteer, puppeteer-extra, and the stealth plugin via npm or Yarn. Use the stealth plugin to configure your browser to behave like a real user.

Quick Example:

<span class="hljs-keyword">import</span> puppeteer <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;puppeteer-extra&#x27;</span>;
<span class="hljs-keyword">import</span> <span class="hljs-title class_">StealthPlugin</span> <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;puppeteer-extra-plugin-stealth&#x27;</span>;

puppeteer.<span class="hljs-title function_">use</span>(<span class="hljs-title class_">StealthPlugin</span>());

(<span class="hljs-title function_">async</span> () =&gt; {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({ <span class="hljs-attr">headless</span>: <span class="hljs-literal">true</span> });
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">&#x27;https://bot.sannysoft.com&#x27;</span>);
  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
})();

This tool is perfect for automating tasks on websites with strict bot detection. Learn how to set it up, optimize its settings, and simulate human-like behavior to stay undetected.

Nodejs Puppeteer Tutorial #7 - Bypass Detection using ...

Installation and Setup

To get started, you'll need to install the necessary packages and configure them to minimize detection during automation. This section covers the installation process, initial setup, and testing to ensure everything works as intended.

Required Package Installation

First, install Puppeteer, Puppeteer Extra, and the Stealth plugin. Open your terminal and run the following command:

npm install puppeteer puppeteer-extra puppeteer-extra-plugin-stealth

If you're using Yarn, use this command instead:

yarn add puppeteer puppeteer-extra puppeteer-extra-plugin-stealth

Initial Setup Steps

After installation, set up your JavaScript file to integrate the stealth plugin. Here's the code you need:

<span class="hljs-keyword">import</span> puppeteer <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;puppeteer-extra&#x27;</span>;
<span class="hljs-keyword">import</span> <span class="hljs-title class_">StealthPlugin</span> <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;puppeteer-extra-plugin-stealth&#x27;</span>;

puppeteer.<span class="hljs-title function_">use</span>(<span class="hljs-title class_">StealthPlugin</span>());

(<span class="hljs-title function_">async</span> () =&gt; {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({ <span class="hljs-attr">headless</span>: <span class="hljs-literal">true</span> });
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">&#x27;https://nowsecure.nl/&#x27;</span>);
  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
})();

Important: Make sure to import Puppeteer from 'puppeteer-extra' instead of 'puppeteer' to access the added functionality [2].

Once you've completed the setup, it's time to verify that everything is working correctly.

Testing Your Installation

Run these tests to confirm your setup is functioning as expected:

Basic Functionality Test: Try navigating to a site that detects bots and review the results.
Screenshot Verification: Take a screenshot of the test page to confirm that stealth features are properly applied.
reCAPTCHA Score Check: Observe your reCAPTCHA v3 scores to determine if there are any improvements.

For a quick verification, use the following script:

(<span class="hljs-title function_">async</span> () =&gt; {
  <span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({ <span class="hljs-attr">headless</span>: <span class="hljs-literal">true</span> });
  <span class="hljs-keyword">const</span> page = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">newPage</span>();
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(<span class="hljs-string">&#x27;https://bot.sannysoft.com&#x27;</span>);
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">waitForTimeout</span>(<span class="hljs-number">5000</span>);
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">screenshot</span>({ <span class="hljs-attr">path</span>: <span class="hljs-string">&#x27;stealth-test.png&#x27;</span> });
  <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">close</span>();
})();

This script will take a screenshot of the test page. Check the screenshot to see if your browser behaves like a regular Chrome browser without revealing signs of automation.

Once your setup passes these tests, you're ready to dive into the plugin's advanced features, which are covered in the next section.

Main Stealth Features

The puppeteer-extra-plugin-stealth uses various techniques to make automated browsing harder to detect.

Browser Identity Masking

The plugin tweaks key browser properties to mimic a typical Chrome browser. These include:

Replacing the default HeadlessChrome user-agent with a more natural one
Setting realistic Accept-Language headers
Adjusting codec support for media playback
Modifying navigator.vendor to match standard Chrome behavior

These changes help create a browser profile that looks like a regular user, not a bot. On top of this, the plugin employs anti-fingerprinting techniques to further reduce detection risk.

Anti-Fingerprinting Methods

Feature	Method	Purpose
Processor Emulation	Limits logical processors to 4	Mimics typical user hardware
Plugin Emulation	Mocks navigator.mimeTypes and plugins	Imitates standard Chrome functionality
Window Properties	Adds outerWidth and outerHeight	Completes the browser simulation
Vendor Properties	Tweaks Chrome's Google identifier	Helps avoid automation detection

These methods ensure the browser behaves in a way that aligns with what websites expect from real users.

Removing Automation Markers

To further disguise automation, the plugin removes or modifies tell-tale signs of bot activity:

Deletes the navigator.webdriver property
Adds chrome.app and chrome.csi objects, which are present in regular Chrome browsers
Hides the sourceurl attribute in Puppeteer scripts
Adjusts permissions properties to match natural browser behavior

CAPTCHA Management

The plugin also helps reduce CAPTCHA challenges by maintaining consistent browser behavior and managing sessions effectively. This creates a browsing pattern that aligns with human activity, allowing it to bypass most bot detection tests on platforms like sannysoft.com [2]. However, advanced anti-bot systems, such as those used by Cloudflare, may still detect automation in some cases [1].

sbb-itb-23997f1

Custom Configuration

Custom configuration allows you to tweak stealth settings and browser behavior, helping you avoid detection more effectively.

Stealth Module Settings

Puppeteer Stealth lets you manage its evasion modules for specific websites. You can enable or disable modules as needed:

<span class="hljs-keyword">const</span> <span class="hljs-title class_">StealthPlugin</span> = <span class="hljs-built_in">require</span>(<span class="hljs-string">&#x27;puppeteer-extra-plugin-stealth&#x27;</span>)
<span class="hljs-keyword">const</span> stealth = <span class="hljs-title class_">StealthPlugin</span>({
  <span class="hljs-attr">webglVendor</span>: <span class="hljs-string">&quot;Google Inc. (Intel)&quot;</span>,
  <span class="hljs-attr">webglRenderer</span>: <span class="hljs-string">&quot;Intel Iris OpenGL Engine&quot;</span>,
  <span class="hljs-attr">navigator</span>: {
    <span class="hljs-attr">platform</span>: <span class="hljs-string">&quot;MacIntel&quot;</span>,
    <span class="hljs-attr">languages</span>: [<span class="hljs-string">&quot;en-US&quot;</span>, <span class="hljs-string">&quot;en&quot;</span>]
  }
})

After setting up stealth modules, you can adjust browser behavior to better imitate real user activity.

Browser Behavior Settings

Fine-tune browser parameters to mimic a genuine browsing experience:

Category	Options	Purpose
User Identity	User-Agent, Platform, Languages	Creates a consistent browser identity
Hardware Profile	WebGL vendor, Screen dimensions	Imitates actual device characteristics
Runtime Environment	Chrome runtime objects, Navigator properties	Emulates normal browser behavior

Introduce natural delays between actions to make automation less detectable:

<span class="hljs-keyword">const</span> <span class="hljs-title function_">randomDelay</span> = (<span class="hljs-params">min, max</span>) =&gt; {
  <span class="hljs-keyword">return</span> <span class="hljs-title class_">Math</span>.<span class="hljs-title function_">floor</span>(<span class="hljs-title class_">Math</span>.<span class="hljs-title function_">random</span>() * (max - min + <span class="hljs-number">1</span>) + min);
}

<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">waitForTimeout</span>(<span class="hljs-title function_">randomDelay</span>(<span class="hljs-number">1000</span>, <span class="hljs-number">3000</span>));

Adding these delays helps your automation resemble human behavior.

Proxy Configuration

Using proxies during browser launch enhances anonymity:

<span class="hljs-keyword">const</span> browser = <span class="hljs-keyword">await</span> puppeteer.<span class="hljs-title function_">launch</span>({
  <span class="hljs-attr">args</span>: [
    <span class="hljs-string">`--proxy-server=http://proxy.example.com:8080`</span>,
    <span class="hljs-string">&#x27;--disable-features=IsolateOrigins,site-per-process&#x27;</span>
  ]
});

"It's probably impossible to prevent all ways to detect headless chromium, but it should be possible to make it so difficult that it becomes cost-prohibitive or triggers too many false-positives to be feasible." - TiZho, GitHub contributor [3]

Rotate proxies and set up automatic failover to maintain reliable connectivity. These configurations help minimize detection risks while ensuring stable performance.

Stealth Best Practices

To keep automated sessions under the radar, careful planning and execution are key.

Natural Browsing Patterns

Simulate realistic browsing by adding random delays and actions:

<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">emulateHumanBehavior</span>(<span class="hljs-params">page</span>) {
  <span class="hljs-comment">// Random scrolling behavior</span>
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">evaluate</span>(<span class="hljs-function">() =&gt;</span> {
    <span class="hljs-variable language_">window</span>.<span class="hljs-title function_">scrollBy</span>({
      <span class="hljs-attr">top</span>: <span class="hljs-title class_">Math</span>.<span class="hljs-title function_">random</span>() * <span class="hljs-number">500</span>,
      <span class="hljs-attr">behavior</span>: <span class="hljs-string">&#x27;smooth&#x27;</span>
    });
  });

  <span class="hljs-comment">// Random pauses between actions</span>
  <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">waitForTimeout</span>(<span class="hljs-number">1500</span> + <span class="hljs-title class_">Math</span>.<span class="hljs-title function_">random</span>() * <span class="hljs-number">2500</span>);
}

Behavior Pattern	Implementation	Purpose
Mouse Movement	Random curves and speeds	Imitates natural cursor movement
Page Interaction	Vary scroll depths and pauses	Simulates reading habits
Navigation Timing	Random delays (1.5–4 seconds)	Avoids predictable timing patterns
Input Speed	Randomized keystroke intervals	Mimics human typing behavior

These simulated interactions work alongside the configuration settings outlined earlier.

Session Management

Proper session handling ensures that stealth settings remain consistent. Use persistent storage to save cookies and session data:

<span class="hljs-keyword">const</span> browserContext = <span class="hljs-keyword">await</span> browser.<span class="hljs-title function_">createIncognitoBrowserContext</span>({
  <span class="hljs-attr">userDataDir</span>: <span class="hljs-string">&#x27;./sessions/user1&#x27;</span>,
  <span class="hljs-attr">persistentContext</span>: <span class="hljs-literal">true</span>
});

You can also manage cookies effectively:

<span class="hljs-comment">// Remove specific cookies but keep session-critical data</span>
<span class="hljs-keyword">await</span> page.<span class="hljs-title function_">deleteCookie</span>({
  <span class="hljs-attr">name</span>: <span class="hljs-string">&#x27;_ga&#x27;</span>,
  <span class="hljs-attr">domain</span>: <span class="hljs-string">&#x27;.example.com&#x27;</span>
});

Usage Guidelines

Combine the above techniques with these practical steps for better automation:

Request Rate Management: Start with a 2-second delay between requests and increase it if CAPTCHAs emerge.

Error Handling: Create a retry system to handle failed requests:

<span class="hljs-keyword">const</span> maxRetries = <span class="hljs-number">3</span>;
<span class="hljs-keyword">const</span> baseDelay = <span class="hljs-number">2000</span>;

<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">fetchWithRetry</span>(<span class="hljs-params">page, url</span>) {
  <span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>; i &lt; maxRetries; i++) {
    <span class="hljs-keyword">try</span> {
      <span class="hljs-keyword">return</span> <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">goto</span>(url);
    } <span class="hljs-keyword">catch</span> (error) {
      <span class="hljs-keyword">await</span> page.<span class="hljs-title function_">waitForTimeout</span>(baseDelay * <span class="hljs-title class_">Math</span>.<span class="hljs-title function_">pow</span>(<span class="hljs-number">2</span>, i));
    }
  }
}

Proxy Rotation: Use multiple IP addresses to avoid being flagged for excessive activity.

"It's probably impossible to prevent all ways to detect headless chromium, but it should be possible to make it so difficult that it becomes cost-prohibitive or triggers too many false-positives to be feasible." - TiZho, GitHub contributor [3]

Keep an eye on evolving anti-bot detection methods and adjust your settings as needed. These practices complement the stealth techniques covered earlier in the article.

Conclusion

Here's a quick summary of the main points and tips for using Puppeteer-extra-plugin-stealth effectively.

Main Benefits

Puppeteer-extra-plugin-stealth helps automate browsing without being flagged. It works by hiding automation markers using built-in evasion modules [2].

Some key features include:

Removing the 'HeadlessChrome' identifier from User-Agent headers.
Hiding critical automation markers, like navigator.webdriver.
Adjusting browser fingerprints to mimic real user behavior.
Allowing tailored evasion strategies for specific website needs.

Tips for Implementation

To refine your automation setup, keep these strategies in mind:

Focus Area	Strategy	Outcome
Evasion Modules	Enable only the features you need	Lower detection risk, better performance
Error Management	Use retry logic with exponential backoff	More reliable handling of temporary issues
Session Handling	Use persistent browser contexts	Consistent stealth profile across sessions

Additional suggestions:

Start with the default stealth settings, then tweak them to match your needs.
Stay updated on new anti-bot techniques and adjust your approach accordingly.
Combine stealth features with natural browsing behaviors for better results.
Focus on consistent session management to avoid detection.

While no setup is 100% foolproof, combining multiple evasion tactics makes detection much harder. Success relies on careful setup and regular updates to your methods. These tips, paired with the plugin's features, create a strong foundation for undetectable automation.