cannaiq

Note: If for whatever reason you need to use this outside of puppeteer-extra: Just remove the module.exports statement at the very bottom, the rest can be copy pasted into any browser context.

Alternatively take a look at the extract-stealth-evasions package to create a finished bundle which includes these utilities.

.stripProxyFromErrors(handler)

handler object The JS Proxy handler to wrap (optional, default {})

Wraps a JS Proxy Handler and strips it's presence from error stacks, in case the traps throw.

The presence of a JS Proxy can be revealed as it shows up in error stack traces.

.stripErrorWithAnchor(err, anchor)

err object The error to sanitize
anchor string The string the anchor line starts with

Strip error lines from stack traces until (and including) a known line the stack.

.replaceProperty(obj, propName, descriptorOverrides)

obj object The object which has the property to replace
propName string The property name to replace
descriptorOverrides object e.g. { value: "alice" } (optional, default {})

Replace the property of an object in a stealthy way.

Note: You also want to work on the prototype of an object most often, as you'd otherwise leave traces (e.g. showing up in Object.getOwnPropertyNames(obj)).

Example:

replaceProperty(WebGLRenderingContext.prototype, 'getParameter', {
  value: 'alice'
})
// or
replaceProperty(Object.getPrototypeOf(navigator), 'languages', {
  get: () => ['en-US', 'en']
})

See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty

.preloadCache()

Preload a cache of function copies and data.

For a determined enough observer it would be possible to overwrite and sniff usage of functions we use in our internal Proxies, to combat that we use a cached copy of those functions.

This is evaluated once per execution context (e.g. window)

.makeNativeString(name?)

name string? Optional function name (optional, default '')

Utility function to generate a cross-browser toString result representing native code.

There's small differences: Chromium uses a single line, whereas FF & Webkit uses multiline strings. To future-proof this we use an existing native toString result as the basis.

The only advantage we have over the other team is that our JS runs first, hence we cache the result of the native toString result once, so they cannot spoof it afterwards and reveal that we're using it.

Note: Whenever we add a Function.prototype.toString proxy we should preload the cache before, by executing utils.preloadCache() before the proxy is applied (so we don't cause recursive lookups).

Example:

makeNativeString('foobar') // => `function foobar() { [native code] }`

.patchToString(obj, str)

obj object The object for which to modify the toString() representation
str string Optional string used as a return value (optional, default '')

Helper function to modify the toString() result of the provided object.

Note: Use utils.redirectToString instead when possible.

There's a quirk in JS Proxies that will cause the toString() result to differ from the vanilla Object. If no string is provided we will generate a [native code] thing based on the name of the property object.

Example:

patchToString(
  WebGLRenderingContext.prototype.getParameter,
  'function getParameter() { [native code] }'
)

.patchToStringNested(obj)

obj object (optional, default {})

Make all nested functions of an object native.

.redirectToString(proxyObj, originalObj)

proxyObj object The object that toString will be called on
originalObj object The object which toString result we wan to return

Redirect toString requests from one object to another.

.replaceWithProxy(obj, propName, handler)

obj object The object which has the property to replace
propName string The name of the property to replace
handler object The JS Proxy handler to use

All-in-one method to replace a property with a JS Proxy using the provided Proxy handler with traps.

Will stealthify these aspects (strip error stack traces, redirect toString, etc). Note: This is meant to modify native Browser APIs and works best with prototype objects.

Example:

replaceWithProxy(WebGLRenderingContext.prototype, 'getParameter', proxyHandler)

.mockWithProxy(obj, propName, pseudoTarget, handler)

obj object The object which has the property to replace
propName string The name of the property to replace or create
pseudoTarget object The JS Proxy target to use as a basis
handler object The JS Proxy handler to use

All-in-one method to mock a non-existing property with a JS Proxy using the provided Proxy handler with traps.

Will stealthify these aspects (strip error stack traces, redirect toString, etc).

Example:

mockWithProxy(
  chrome.runtime,
  'sendMessage',
  function sendMessage() {},
  proxyHandler
)

.createProxy(pseudoTarget, handler)

pseudoTarget object The JS Proxy target to use as a basis
handler object The JS Proxy handler to use

All-in-one method to create a new JS Proxy with stealth tweaks.

This is meant to be used whenever we need a JS Proxy but don't want to replace or mock an existing known property.

Will stealthify certain aspects of the Proxy (strip error stack traces, redirect toString, etc).

Example:

createProxy(navigator.mimeTypes.__proto__.namedItem, proxyHandler) // => Proxy

.splitObjPath(objPath)

objPath string The full path to an object as dot notation string

Helper function to split a full path to an Object into the first part and property.

Example:

splitObjPath(`HTMLMediaElement.prototype.canPlayType`)
// => {objName: "HTMLMediaElement.prototype", propName: "canPlayType"}

.replaceObjPathWithProxy(objPath, handler)

objPath string The full path to an object (dot notation string) to replace
handler object The JS Proxy handler to use

Convenience method to replace a property with a JS Proxy using the provided objPath.

Supports a full path (dot notation) to the object as string here, in case that makes it easier.

Example:

replaceObjPathWithProxy(
  'WebGLRenderingContext.prototype.getParameter',
  proxyHandler
)

.execRecursively(obj, typeFilter, fn)

obj object (optional, default {})
typeFilter array e.g. ['function'] (optional, default [])
fn Function e.g. utils.patchToString

Traverse nested properties of an object recursively and apply the given function on a whitelist of value types.

.stringifyFns(fnObj)

fnObj object An object containing functions as properties (optional, default {hello:()=>'world'})

Everything we run through e.g. page.evaluate runs in the browser context, not the NodeJS one. That means we cannot just use reference variables and functions from outside code, we need to pass everything as a parameter.

Unfortunately the data we can pass is only allowed to be of primitive types, regular functions don't survive the built-in serialization process. This utility function will take an object with functions and stringify them, so we can pass them down unharmed as strings.

We use this to pass down our utility functions as well as any other functions (to be able to split up code better).

See: utils.materializeFns

.materializeFns(fnStrObj)

fnStrObj object An object containing stringified functions as properties (optional, default {hello:"() => 'world'"})

Utility function to reverse the process of utils.stringifyFns. Will materialize an object with stringified functions (supports classic and fat arrow functions).

readme.md

API

Table of Contents

utils()

.stripProxyFromErrors(handler)

.stripErrorWithAnchor(err, anchor)

.replaceProperty(obj, propName, descriptorOverrides)

.preloadCache()

.makeNativeString(name?)

.patchToString(obj, str)

.patchToStringNested(obj)

.redirectToString(proxyObj, originalObj)

.replaceWithProxy(obj, propName, handler)

.mockWithProxy(obj, propName, pseudoTarget, handler)

.createProxy(pseudoTarget, handler)

.splitObjPath(objPath)

.replaceObjPathWithProxy(objPath, handler)

.execRecursively(obj, typeFilter, fn)

.stringifyFns(fnObj)

.materializeFns(fnStrObj)