puppeteer-extra-plugin-stealth

What is puppeteer-extra-plugin-stealth?

The puppeteer-extra-plugin-stealth package is designed to make headless puppeteer browsers less detectable by web servers. It achieves this by applying various techniques to mask the fact that a browser is being controlled by automation scripts.

What are puppeteer-extra-plugin-stealth's main functionalities?

Bypass WebDriver Detection

This feature allows you to bypass WebDriver detection by websites. The plugin modifies the navigator.webdriver property and other related properties to make the browser appear as if it is not being controlled by automation scripts.

const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
puppeteer.use(StealthPlugin());
(async () => {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  // Perform actions on the page
  await browser.close();
})();

Masking Browser Fingerprints

This feature helps in masking various browser fingerprints such as user-agent, languages, and other properties that can be used to detect automated browsing.

const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
puppeteer.use(StealthPlugin());
(async () => {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  // Perform actions on the page
  await browser.close();
})();

Evading Chrome Headless Detection

This feature evades detection mechanisms that check for headless Chrome. It modifies various properties and behaviors to make the headless browser appear as a regular browser.

const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
puppeteer.use(StealthPlugin());
(async () => {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  // Perform actions on the page
  await browser.close();
})();

Other packages similar to puppeteer-extra-plugin-stealth

puppeteer-extra

puppeteer-extra is a modular plugin framework for puppeteer. It allows you to add various plugins to enhance puppeteer's functionality. While it includes the stealth plugin, it also offers other plugins for ad-blocking, recaptcha solving, and more.

puppeteer-cluster

puppeteer-cluster is a library that allows you to create a cluster of puppeteer workers to perform parallel tasks. While it does not focus on stealth, it is useful for scaling up web scraping tasks efficiently.

playwright

playwright is a Node.js library to automate Chromium, Firefox, and WebKit with a single API. It offers built-in features to handle headless detection and provides more control over browser contexts and sessions compared to puppeteer.

README

puppeteer-extra-plugin-stealth

A plugin for puppeteer-extra to prevent detection.

Install

yarn add puppeteer-extra-plugin-stealth
# - or -
npm install puppeteer-extra-plugin-stealth

If this is your first puppeteer-extra plugin here's everything you need:

yarn add puppeteer puppeteer-extra puppeteer-extra-plugin-stealth
# - or -
npm install puppeteer puppeteer-extra puppeteer-extra-plugin-stealth

Usage

// puppeteer-extra is a drop-in replacement for puppeteer,
// it augments the installed puppeteer with plugin functionality
const puppeteer = require('puppeteer-extra')

// add stealth plugin and use defaults (all evasion techniques)
const pluginStealth = require('puppeteer-extra-plugin-stealth')
puppeteer.use(pluginStealth())

// puppeteer usage as normal
puppeteer.launch({ headless: true }).then(async browser => {
  const page = await browser.newPage()
  await page.setViewport({ width: 800, height: 600 })
  await page.goto('https://bot.sannysoft.com')
  await page.waitFor(5000)
  await page.screenshot({ path: 'testresult.png', fullPage: true })
  await browser.close()
})

Changelog

v2.1.2

• Improved: navigator.plugins - we fully emulate plugins/mimetypes in headless now 🎉
• New: webgl.vendor - is otherwise set to "Google" in headless
• New: window.outerdimensions - fix missing window.outerWidth/outerHeight and viewport
• Fixed: navigator.webdriver now returns undefined instead of false

Test results (red is bad)

Vanilla puppeteer without stealth 😢

Chromium + headless

Chromium + headful

Chrome + headless

Chrome + headful

Puppeteer with stealth plugin 💯

Chromium + headless

Chromium + headful

Chrome + headless

Chrome + headful

Tests have been done using this test site and these scripts.

Improved reCAPTCHA v3 scores

Using stealth also seems to help with maintaining a normal reCAPTCHA v3 score.

Regular Puppeteer

Stealth Puppeteer

Note: The official test is to be taken with a grain of salt, as the score is calculated individually per site and multiple other factors (past behaviour, IP address, etc). Based on anecdotal observations it still seems to work as a rough indicator.

Tip: Have a look at the recaptcha plugin if you have issues with reCAPTCHAs.

API

Table of Contents

• class: StealthPlugin
  • Purpose
  • Modularity
  • Contributing
  • Kudos
  • .availableEvasions
  • .enabledEvasions
• defaultExport(opts?)

class: StealthPlugin

• opts Object? Options (optional, default {})
  • opts.enabledEvasions Set<string>? Specify which evasions to use (by default all)

Extends: PuppeteerExtraPlugin

Stealth mode: Applies various techniques to make detection of headless puppeteer harder. 💯

Purpose

There are a couple of ways the use of puppeteer can easily be detected by a target website. The addition of HeadlessChrome to the user-agent being only the most obvious one.

The goal of this plugin is to be the definite companion to puppeteer to avoid detection, applying new techniques as they surface.

As this cat & mouse game is in it's infancy and fast-paced the plugin is kept as flexibile as possible, to support quick testing and iterations.

Modularity

This plugin uses puppeteer-extra's dependency system to only require code mods for evasions that have been enabled, to keep things modular and efficient.

The stealth plugin is a convenience wrapper that requires multiple evasion techniques automatically and comes with defaults. You could also bypass the main module and require specific evasion plugins yourself, if you whish to do so (as they're standalone puppeteer-extra plugins):

// bypass main module and require a specific stealth plugin directly:
puppeteer.use(
  require('puppeteer-extra-plugin-stealth/evasions/console.debug')()
)

Contributing

PRs are welcome, if you want to add a new evasion technique I suggest you look at the template to kickstart things.

Kudos

Thanks to Evan Sangaline and Paul Irish for kickstarting the discussion!

---

Example:

const puppeteer = require('puppeteer-extra')
// Enable stealth plugin with all evasions
puppeteer.use(require('puppeteer-extra-plugin-stealth')())
;(async () => {
  // Launch the browser in headless mode and set up a page.
  const browser = await puppeteer.launch({
    args: ['--no-sandbox'],
    headless: true
  })
  const page = await browser.newPage()

  // Navigate to the page that will perform the tests.
  const testUrl =
    'https://intoli.com/blog/' +
    'not-possible-to-block-chrome-headless/chrome-headless-test.html'
  await page.goto(testUrl)

  // Save a screenshot of the results.
  const screenshotPath = '/tmp/headless-test-result.png'
  await page.screenshot({ path: screenshotPath })
  console.log('have a look at the screenshot:', screenshotPath)

  await browser.close()
})()

---

.availableEvasions

Type: Set<string>

Get all available evasions.

Please look into the evasions directory for an up to date list.

Example:

const pluginStealth = require('puppeteer-extra-plugin-stealth')()
console.log(pluginStealth.availableEvasions) // => Set { 'user-agent', 'console.debug' }
puppeteer.use(pluginStealth)

---

.enabledEvasions

Type: Set<string>

Get all enabled evasions.

Enabled evasions can be configured either through opts or by modifying this property.

Example:

// Remove specific evasion from enabled ones dynamically
const pluginStealth = require('puppeteer-extra-plugin-stealth')()
pluginStealth.enabledEvasions.delete('console.debug')
puppeteer.use(pluginStealth)

---

defaultExport(opts?)

• opts Object? Options
  • opts.enabledEvasions Set<string>? Specify which evasions to use (by default all)

Default export, PuppeteerExtraStealthPlugin

---

License

Copyright © 2019, berstend̡̲̫̹̠̖͚͓̔̄̓̐̄͛̀͘. Released under the MIT License.