@zorilla/puppeteer-extra-plugin-stealth 1.0.0

package/dist/index.js

@@ -0,0 +1,164 @@
+import { PuppeteerExtraPlugin } from '@zorilla/puppeteer-extra-plugin';
+/**
+ * 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](./evasions/)
+ * 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):
+ *
+ * ```es6
+ * // bypass main module and require a specific stealth plugin directly:
+ * puppeteer.use(require('@zorilla/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](./evasions/_template) to kickstart things.
+ *
+ * ### Kudos
+ * Thanks to [Evan Sangaline](https://intoli.com/blog/not-possible-to-block-chrome-headless/) and [Paul Irish](https://github.com/paulirish/headless-cat-n-mouse) for kickstarting the discussion!
+ *
+ * ---
+ *
+ * @todo
+ * - white-/blacklist with url globs (make this a generic plugin method?)
+ * - dynamic whitelist based on function evaluation
+ *
+ * @example
+ * const puppeteer = require('@zorilla/puppeteer-extra')
+ * // Enable stealth plugin with all evasions
+ * puppeteer.use(require('@zorilla/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()
+ * })()
+ *
+ * @param {Object} [opts] - Options
+ * @param {Set<string>} [opts.enabledEvasions] - Specify which evasions to use (by default all)
+ *
+ */
+class StealthPlugin extends PuppeteerExtraPlugin {
+    constructor(opts = {}) {
+        super(opts);
+    }
+    get name() {
+        return 'stealth';
+    }
+    get defaults() {
+        const availableEvasions = new Set([
+            'chrome.app',
+            'chrome.csi',
+            'chrome.loadTimes',
+            'chrome.runtime',
+            'defaultArgs',
+            'iframe.contentWindow',
+            'media.codecs',
+            'navigator.hardwareConcurrency',
+            'navigator.languages',
+            'navigator.permissions',
+            'navigator.plugins',
+            'navigator.webdriver',
+            'sourceurl',
+            'user-agent-override',
+            'webgl.vendor',
+            'window.outerdimensions',
+        ]);
+        return {
+            availableEvasions,
+            // Enable all available evasions by default
+            enabledEvasions: new Set([...availableEvasions]),
+        };
+    }
+    /**
+     * Requires evasion techniques dynamically based on configuration.
+     *
+     * @private
+     */
+    get dependencies() {
+        const enabledEvasions = this.opts.enabledEvasions;
+        return new Set([...enabledEvasions].map(e => `${this.name}/evasions/${e}`));
+    }
+    /**
+     * Get all available evasions.
+     *
+     * Please look into the [evasions directory](./evasions/) for an up to date list.
+     *
+     * @type {Set<string>} - A Set of all available evasions.
+     *
+     * @example
+     * const pluginStealth = require('@zorilla/puppeteer-extra-plugin-stealth')()
+     * console.log(pluginStealth.availableEvasions) // => Set { 'user-agent', 'console.debug' }
+     * puppeteer.use(pluginStealth)
+     */
+    get availableEvasions() {
+        return this.defaults.availableEvasions;
+    }
+    /**
+     * Get all enabled evasions.
+     *
+     * Enabled evasions can be configured either through `opts` or by modifying this property.
+     *
+     * @type {Set<string>} - A Set of all enabled evasions.
+     *
+     * @example
+     * // Remove specific evasion from enabled ones dynamically
+     * const pluginStealth = require('@zorilla/puppeteer-extra-plugin-stealth')()
+     * pluginStealth.enabledEvasions.delete('console.debug')
+     * puppeteer.use(pluginStealth)
+     */
+    get enabledEvasions() {
+        return this.opts.enabledEvasions;
+    }
+    /**
+     * @private
+     */
+    set enabledEvasions(evasions) {
+        this.opts.enabledEvasions = evasions;
+    }
+    async onBrowser(browser, _opts) {
+        // Browser extends EventEmitter, increase listeners to prevent MaxListenersExceededWarning
+        const emitter = browser;
+        if (emitter?.setMaxListeners) {
+            emitter.setMaxListeners(30);
+        }
+    }
+}
+/**
+ * Default export, PuppeteerExtraStealthPlugin
+ *
+ * @param {Object} [opts] - Options
+ * @param {Set<string>} [opts.enabledEvasions] - Specify which evasions to use (by default all)
+ */
+export default (opts) => new StealthPlugin(opts);
+// Named export
+export { StealthPlugin };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAavE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,aAAc,SAAQ,oBAAoB;IAC9C,YAAY,OAAsB,EAAE;QAClC,KAAK,CAAC,IAAI,CAAC,CAAC;IACd,CAAC;IAED,IAAa,IAAI;QACf,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAa,QAAQ;QACnB,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;YAChC,YAAY;YACZ,YAAY;YACZ,kBAAkB;YAClB,gBAAgB;YAChB,aAAa;YACb,sBAAsB;YACtB,cAAc;YACd,+BAA+B;YAC/B,qBAAqB;YACrB,uBAAuB;YACvB,mBAAmB;YACnB,qBAAqB;YACrB,WAAW;YACX,qBAAqB;YACrB,cAAc;YACd,wBAAwB;SACzB,CAAC,CAAC;QACH,OAAO;YACL,iBAAiB;YACjB,2CAA2C;YAC3C,eAAe,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC;SACjD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,IAAa,YAAY;QACvB,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,eAA8B,CAAC;QACjE,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,eAA8B,CAAC;IAClD,CAAC;IAED;;OAEG;IACH,IAAI,eAAe,CAAC,QAAqB;QACvC,IAAI,CAAC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC;IACvC,CAAC;IAEQ,KAAK,CAAC,SAAS,CACtB,OAA0B,EAC1B,KAAqB;QAErB,0FAA0F;QAC1F,MAAM,OAAO,GAAG,OAAkC,CAAC;QACnD,IAAI,OAAO,EAAE,eAAe,EAAE,CAAC;YAC7B,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,eAAe,CAAC,IAAoB,EAAiB,EAAE,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;AAEhF,eAAe;AACf,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/examples/detect-headless.js

@@ -0,0 +1,95 @@
+// taken from: https://github.com/paulirish/headless-cat-n-mouse/blob/master/detect-headless.js
+// initial detects from @antoinevastel
+//   http://antoinevastel.github.io/bot%20detection/2018/01/17/detect-chrome-headless-v2.html
+
+export default async () => {
+  const results = {};
+
+  async function test(name, fn) {
+    const detectionPassed = await fn();
+    if (detectionPassed) {
+      console.log(`WARNING: Chrome headless detected via ${name}`);
+    } else {
+      console.log(`PASS: Chrome headless NOT detected via ${name}`);
+    }
+    results[name] = detectionPassed;
+  }
+
+  await test('userAgent', _ => {
+    return /HeadlessChrome/.test(window.navigator.userAgent);
+  });
+
+  // Detects the --enable-automation || --headless flags
+  // Will return true in headful if --enable-automation is provided
+  await test('navigator.webdriver present', _ => {
+    return 'webdriver' in navigator;
+  });
+
+  await test('window.chrome missing', _ => {
+    return /Chrome/.test(window.navigator.userAgent) && !window.chrome;
+  });
+
+  await test('permissions API', async _ => {
+    const permissionStatus = await navigator.permissions.query({
+      name: 'notifications',
+    });
+    // eslint-disable-next-line
+    return (
+      Notification.permission === 'denied' && // eslint-disable-line no-undef
+      permissionStatus.state === 'prompt'
+    );
+  });
+
+  await test('permissions API overriden', _ => {
+    const permissions = window.navigator.permissions;
+    if (permissions.query.toString() !== 'function query() { [native code] }')
+      return true;
+    if (
+      permissions.query.toString.toString() !==
+      'function toString() { [native code] }'
+    )
+      return true;
+    if (
+      Object.hasOwn(permissions.query.toString, '[[Handler]]') && // eslint-disable-line no-prototype-builtins
+      Object.hasOwn(permissions.query.toString, '[[Target]]') && // eslint-disable-line no-prototype-builtins
+      Object.hasOwn(permissions.query.toString, '[[IsRevoked]]') // eslint-disable-line no-prototype-builtins
+    )
+      return true;
+    if (Object.hasOwn(permissions, 'query')) return true; // eslint-disable-line no-prototype-builtins
+  });
+
+  await test('navigator.plugins empty', _ => {
+    return navigator.plugins.length === 0;
+  });
+
+  await test('navigator.languages blank', _ => {
+    return navigator.languages === '';
+  });
+
+  await test('iFrame for fresh window object', _ => {
+    // evaluateOnNewDocument scripts don't apply within [srcdoc] (or [sandbox]) iframes
+    // https://github.com/GoogleChrome/puppeteer/issues/1106#issuecomment-359313898
+    const iframe = document.createElement('iframe');
+    iframe.srcdoc = 'page intentionally left blank';
+    document.body.appendChild(iframe);
+
+    // Here we would need to rerun all tests with `iframe.contentWindow` as `window`
+    // Example:
+    return iframe.contentWindow.navigator.plugins.length === 0;
+  });
+
+  // This detects that a devtools protocol agent is attached.
+  // So it will also pass true in headful Chrome if the devtools window is attached
+  await test('toString', _ => {
+    let gotYou = 0;
+    const spooky = /./;
+    spooky.toString = () => {
+      gotYou++;
+      return 'spooky';
+    };
+    console.debug(spooky);
+    return gotYou > 1;
+  });
+
+  return results;
+};

package/examples/test1.js

@@ -0,0 +1,20 @@
+import puppeteer from '@zorilla/puppeteer-extra';
+import stealthPlugin from '@zorilla/puppeteer-extra-plugin-stealth';
+import detectHeadless from './detect-headless.js';
+
+puppeteer.use(stealthPlugin());
+
+const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
+const page = await browser.newPage();
+page.on('console', msg => {
+  console.log('Page console: ', msg.text());
+});
+
+await page.goto('about:blank');
+const detectionResults = await page.evaluate(detectHeadless);
+console.assert(
+  Object.keys(detectionResults).length,
+  'No detection results returned.'
+);
+
+await browser.close();

package/examples/test2.js

@@ -0,0 +1,25 @@
+import puppeteer from '@zorilla/puppeteer-extra';
+import stealthPlugin from '@zorilla/puppeteer-extra-plugin-stealth';
+
+// Enable stealth plugin
+puppeteer.use(stealthPlugin());
+
+// 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();

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@zorilla/puppeteer-extra-plugin-stealth",
+  "version": "1.0.0",
+  "description": "Stealth mode: Applies various techniques to make detection of headless puppeteer harder.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./evasions/*": "./dist/evasions/*/index.js"
+  },
+  "repository": "zorillajs/zorilla",
+  "homepage": "https://github.com/zorillajs/zorilla/tree/main/packages/puppeteer-extra-plugin-stealth#readme",
+  "authors": [
+    "berstend",
+    "Justin Beckwith <justin.beckwith@gmail.com>"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "puppeteer",
+    "puppeteer-extra",
+    "puppeteer-extra-plugin",
+    "stealth",
+    "stealth-mode",
+    "detection-evasion",
+    "crawler",
+    "chrome",
+    "headless",
+    "pupeteer"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.0.6",
+    "fpcollect": "^1.0.5",
+    "fpscanner": "^0.1.5",
+    "loop": "^3.3.6",
+    "npm-run-all": "^4.1.5",
+    "puppeteer": "^24.35.0",
+    "vitest": "^4.0.17",
+    "@zorilla/puppeteer-extra": "1.0.0"
+  },
+  "dependencies": {
+    "debug": "^4.4.3",
+    "@zorilla/puppeteer-extra-plugin": "1.0.0",
+    "@zorilla/puppeteer-extra-plugin-user-preferences": "1.0.0"
+  },
+  "peerDependencies": {
+    "playwright-extra": "*",
+    "puppeteer-extra": "*"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer-extra": {
+      "optional": true
+    },
+    "playwright-extra": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc && cp -r src/evasions dist/ && find dist/evasions -name '*.js' -exec sed -i '' \"s|'puppeteer-extra-plugin'|'@zorilla/puppeteer-extra-plugin'|g\" {} \\;",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint --ext .js,.ts ."
+  }
+}

package/src/evasions/README.md

@@ -0,0 +1,13 @@
+# puppeteer-extra-plugin-stealth/evasions
+
+Various detection evasion plugins for `puppeteer-extra-plugin-stealth`.
+
+You can bypass the main module and require specific evasion plugins yourself, if you wish to do so:
+
+```es6
+puppeteer.use(
+  require('@zorilla/puppeteer-extra-plugin-stealth/evasions/console.debug')()
+)
+```
+
+If you want to add a new evasion technique I suggest you look at the [template](./_template/) to kickstart things.

package/src/evasions/_template/README.md

@@ -0,0 +1,18 @@
+## API
+
+
+#### Table of Contents
+
+- [class: Plugin](#class-plugin)
+
+### class: [Plugin](https://github.com/zorillajs/zorilla/blob/e6133619b051febed630ada35241664eba59b9fa/packages/puppeteer-extra-plugin-stealth/evasions/_template/index.js#L10-L24)
+
+- `opts` (optional, default `{}`)
+
+**Extends: PuppeteerExtraPlugin**
+
+Minimal stealth plugin template, not being used. :-)
+
+Feel free to copy this folder as the basis for additional detection evasion plugins.
+
+---

package/src/evasions/_template/index.js

@@ -0,0 +1,26 @@
+import { PuppeteerExtraPlugin } from '@zorilla/puppeteer-extra-plugin';
+
+/**
+ * Minimal stealth plugin template, not being used. :-)
+ *
+ * Feel free to copy this folder as the basis for additional detection evasion plugins.
+ */
+class Plugin extends PuppeteerExtraPlugin {
+  constructor(opts = {}) {
+    super(opts);
+  }
+
+  get name() {
+    return 'stealth/evasions/_template';
+  }
+
+  async onPageCreated(page) {
+    await page.evaluateOnNewDocument(() => {
+      console.debug('hello world');
+    });
+  }
+}
+
+export default function (pluginConfig) {
+  return new Plugin(pluginConfig);
+}

package/src/evasions/_template/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "type": "module",
+  "main": "index.js"
+}