Invisible Automation: Using puppeteer-extra-plugin-stealth to Bypass Bot Protection
Learn how to effectively use stealth automation techniques to bypass bot detection systems while browsing.
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">'puppeteer-extra'</span>;
<span class="hljs-keyword">import</span> <span class="hljs-title class_">StealthPlugin</span> <span class="hljs-keyword">from</span> <span class="hljs-string">'puppeteer-extra-plugin-stealth'</span>;
puppeteer.<span class="hljs-title function_">use</span>(<span class="hljs-title class_">StealthPlugin</span>());
(<span class="hljs-title function_">async</span> () => {
<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">'https://bot.sannysoft.com'</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">'puppeteer-extra'</span>;
<span class="hljs-keyword">import</span> <span class="hljs-title class_">StealthPlugin</span> <span class="hljs-keyword">from</span> <span class="hljs-string">'puppeteer-extra-plugin-stealth'</span>;
puppeteer.<span class="hljs-title function_">use</span>(<span class="hljs-title class_">StealthPlugin</span>());
(<span class="hljs-title function_">async</span> () => {
<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">'https://nowsecure.nl/'</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> () => {
<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">'https://bot.sannysoft.com'</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">'stealth-test.png'</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
HeadlessChromeuser-agent with a more natural one - Setting realistic
Accept-Languageheaders - Adjusting codec support for media playback
- Modifying
navigator.vendorto 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.webdriverproperty - Adds
chrome.appandchrome.csiobjects, which are present in regular Chrome browsers - Hides the
sourceurlattribute in Puppeteer scripts - Adjusts
permissionsproperties 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">'puppeteer-extra-plugin-stealth'</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">"Google Inc. (Intel)"</span>,
<span class="hljs-attr">webglRenderer</span>: <span class="hljs-string">"Intel Iris OpenGL Engine"</span>,
<span class="hljs-attr">navigator</span>: {
<span class="hljs-attr">platform</span>: <span class="hljs-string">"MacIntel"</span>,
<span class="hljs-attr">languages</span>: [<span class="hljs-string">"en-US"</span>, <span class="hljs-string">"en"</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>) => {
<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">'--disable-features=IsolateOrigins,site-per-process'</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">() =></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">'smooth'</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">'./sessions/user1'</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">'_ga'</span>,
<span class="hljs-attr">domain</span>: <span class="hljs-string">'.example.com'</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 < 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.
Related posts
