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

Usage

const puppeteer = require("puppeteer-extra")
const pluginStealth = require("puppeteer-extra-plugin-stealth")
puppeteer.use(pluginStealth())

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 😢

Puppeteer with stealth plugin 💯

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

API

Table of Contents

• Plugin
  • Purpose
  • Modularity
  • Contributing
  • Kudos
  • availableEvasions
  • enabledEvasions

Plugin

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!

Type: function (opts)

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

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

Get all available evasions.

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

Type: Set<string>

Example:

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

enabledEvasions

Get all enabled evasions.

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

Type: Set<string>

Example:

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