browser-with-fingerprints

browser-with-fingerprints

This is the repo for browser-with-fingerprints, a plugin for automation frameworks that allows you to use fingerprints, generate a virtual identity and improve your browser's stealth.

In order to achieve this, the FingerprintSwitcher service is used, which allows you to replace all browser properties, and thus you will act like a completely new user.

This package is the basis for other plugins and doesn't allow you to automate browser actions directly. It's needed primarily for the implementation of other plugins for various frameworks.

About

The library allows you to change browser fingerprints and use any automation framework with enhanced anonymity. When using ready-made plugins for frameworks, a minimum of modifications and code changes for migration is required.

Browser fingerprinting - is a technique that allows to identify the user by a combination of browser properties, such as - fonts, resolution, list of plugins, navigator properties, etc. By adding new factors and using browser API in a special way, a site can determine exactly which user is visiting it, even if the user is using a proxy. When using this package and replacing fingerprints, websites will not be able to identify you from other users, as all these properties and results of API calls will be replaced with values from real devices.

Let's look at a small example of WebGL property substitution. In the screenshot below, the left column shows the values from the regular browser, and the right column shows the values substituted using ready-made fingerprints. This result cannot be achieved using only the replacement of various browser properties via JavaScript, that's what this plugin and service is for:

You can learn more about this by following the link to the fingerprint changing service used by plugins to bypass such technologies. There are many other examples on this website - you can also see a list of pre-made properties from a real fingerprint.

Getting started

To use this plugin in your project, install it with your favorite package manager:

npm i browser-with-fingerprints
# or
pnpm i browser-with-fingerprints
# or
yarn add browser-with-fingerprints

Other plugins

You can use this package directly to launch browsers and write your own plugins. But it's much better to use ready-made plugins for popular automation frameworks:

• Plugin for selenium - selenium-with-fingrprints
• Plugin for puppeteer - puppeteer-with-fingerprints
• Plugin for playwright - playwright-with-fingerprints

These plugins are already configured to integrate with each specific library, and have a convenient API to work with. They are not a complete replacement for automation frameworks, but only extend their functionality.

To launch the browser, the most compatible API is used, copying the options of the original libraries so that it is easy to add new code to your project. You can find detailed information in the corresponding repositories.

When using plugins, don't forget about dependencies. Libraries do not install dependencies directly, they are listed as optional to make things easier for you. Also be aware of the possible need for additional packages or programs - for example, the chromedriver executable for the selenium-webdriver package, and so on.

Launching the browser

You can launch the browser in two different ways. There are two methods for this - launch and spawn.

The first one uses the native launcher of the library, the integration with which is implemented in a specific plugin. This does not apply to the base library and this method cannot be used with it.

The launch method uses the framework's built-in methods to launch the browser under the hood and, accordingly, accepts the same options. The only difference is the presence of additional code inside the plugin that applies the fingerprint and proxy. The sample code may look something like this:

const browser = await plugin.launch({
  args: ['--mute-audio'],
  headless: true,
});

The spawn method works in a similar way, but uses a separate mechanism to launch the browser. It just starts the process, but doesn't connect to it for automation - you can do it yourself later.

This method returns a running browser instance that can be used to connect via CDP or via the desired automation framework:

const { plugin } = require('browser-with-fingerprints');

const chrome = await plugin.spawn({
  headless: true,
});

// Pseudocode for connection setup.
await framework.connect({
  debuggingPort: chrome.port,
});

// Pseudocode for connection setup.
await framework.connect({
  websocketUrl: chrome.url,
});

await chrome.close();

If possible, use it only in extreme cases. It is much more convenient to use the launch method to launch the browser, which minimizes the number of steps for proper initialization and configuration.

Annotations are described for all plugins methods directly in the library code via the TypeScript declarations, so when using it you will be able to see hints for all options and types. You can also find out about it directly here.

Advanced usage

In order to change the fingerprint and proxy for your browser, you should use special separate methods:

• useProxy - to change the proxy configuration.
• useFingerprint - to change the fingerprint configuration.

These methods directly affect only the next launch of the browser. That is, you should always use them before using the spawn plugin method.

You cannot change the settings once the browser is launched - more specifically, an already launched instance will not be affected by the new configuration. But you can safely change the options for the next run, or for a separate browser instance with a different unique configuration.

You can also chain calls, since both methods return the current plugin instance. It does not matter in which order the settings will be applied. It might look like this:

const { plugin } = require('browser-with-fingerprints');

const browser = await plugin.useProxy().useFingerprint().spawn({
  headless: true,
  timeout: 0,
  args: [],
});

If these methods have not been called, the fingerprint and proxy will not be changed. In this case, all the specific settings will be left in their original values.

Fingerprint and proxy are not applied instantly when calling methods. Instead, the configuration is saved and used directly when the browser is launched using the launch or spawn methods. Thus, you can pre-configure the plugin in a certain way, or change something immediately before launching the browser.

The use of these methods is very similar - they both take two parameters, the first of which is the configuration data itself, and the second is additional options.

Fingerprint usage

The useFingerprint method takes two parameters. The first is a string with fingerprint data that you can request from the service. The second is additional options for applying a fingerprint, most of which are applied automatically - for example, the safe replacement of the BatteryAPI and AudioAPI properties:

const { plugin } = require('browser-with-fingerprints');

const fingerprint = await plugin.fetch('', {
  tags: ['Microsoft Windows', 'Chrome'],
});

plugin.useFingerprint(fingerprint, {
  // It's disabled by default.
  safeElementSize: true,
  // It's enabled by default.
  safeBattery: false,
});

In order to obtain fingerprints you should use the fetch plugin method. Pass the service key as the first argument and additional parameters as the second, if necessary:

const { plugin } = require('browser-with-fingerprints');

const fingerprint = await plugin.fetch('SERVICE_KEY', {
  tags: ['Microsoft Windows', 'Chrome'],
  minBrowserVersion: 98,
  timeLimit: '15 days',
});

You can reuse fingerprints instead of requesting new ones each time. To do this, you can save them to a file or to a database - use any option convenient for you. In this way, you can speed up the process of launching the browser with the parameters you need, organize your storage, filter and sort fingerprints locally, and much more:

const { readFile, writeFile } = require('fs').promises;
const { plugin } = require('browser-with-fingerprints');

// Save the fingerprint to a file:
const fingerprint = await plugin.fetch('', {
  tags: ['Microsoft Windows', 'Chrome'],
});
await writeFile('fingerprint.json', fingerprint);

// Load fingerprint from file at next run:
plugin.useFingerprint(await readFile('fingerprint.json', 'utf8'));

You can learn more about the options directly when adding these methods - just use the built-in annotations.

You can use any tags, filters and settings if you have a service key. The premium version has the most advanced functionality, although for many tasks the free one will be enough.

If you specify an empty string as the first argument, the free version will be used. But note that you won't be able to use other tags than the default ones, as well as some options:

const fingerprint = await plugin.fetch('', {
  // You can only use these tags with the free version.
  tags: ['Microsoft Windows', 'Chrome'],
  // You also cannot use such filters.
  minBrowserVersion: 105,
});

First of all, this concerns the options that filter fingerprints in one way or another, as well as the use of PerfectCanvas technology. There are other limitations when using the free version - for example, limiting the number of requests in a certain period of time. To see the differences and limits of different versions, visit the service website, which is listed just below in the section with additional information.

Proxy usage

In order to set up a proxy, you should use the useProxy method. The first parameter of this method is a string with information about the proxy. The second parameter is additional options that will be applied to the browser, for example, automatic change of language and time zone:

const { plugin } = require('browser-with-fingerprints');

plugin.useProxy('127.0.0.1:8080', {
  changeTimezone: true,
  changeGeolocation: true,
});

The browser supports two types of proxies - https and socks5. It is better to always specify the proxy type in the address line - otherwise, https will be used by default.

You can use aliases - http instead of https and socks instead of socks5. Proxies with authorization (with login and password) are also supported.

In general, when specifying addresses, you can use many different formats, for example:

• 127.0.0.1:8080
• https://127.0.0.1:8080
• socks5://127.0.0.1:8181
• username:password@127.0.0.1:8080
• socks:127.0.0.1:8080:username:password
• https://username:password:127.0.0.1:8080

In order to preserve some compatibility, the proxy can be obtained from the arguments you specified. The proxy-server option will be used as the value, and all other options will be set to their default values. But this will be done only if you did not call the appropriate method for the proxy configuration:

const { plugin } = require('browser-with-fingerprints');

const browser = await plugin.spawn({
  args: ['--proxy-server=https://127.0.0.1:8080'],
});

It's better to replace such code with the useProxy method. This is much more convenient because you can immediately set the additional options you need.

More info

If you want to learn more about fingerprint substitution technology, explore the list of replaceable properties and various options, such as tags, get or configure your service key, use this link. There you can also get a test fingerprint and see ready-made values that can be applied to your browser.

Architecture

This plugin uses the FingerprintSwitcher service to get fingerprints. The resulting fingerprints are used later directly when working with the browser and are applied in a special way using a custom configuration files.

Also keep in mind that all plugins only work on the Windows operating system. This is a forced measure due to the presence of some critical Windows-only dependencies, without which the plugins would not work correctly. If you install or run the libraries on other platforms, you will get the corresponding errors.

There are some limitations in using the plugin, which may be critical or non-critical depending on your task. For example, for the correct operation of the fingerprint substitution technology, a custom browser with various patches is required. It will be used automatically when working with plugins.

The plugin architecture can be summarized as the following diagram:

All plugins can only work with the Chrome browser, which comes bundled with the libraries and loads automatically. The path to the executable file is defined on the plugin side and cannot be changed. It means that you will not be able to use not only other versions of Chrome or Chromium, but also other browser engines. The same goes for some framework-specific launch options.

Alternatives

Also check out BAS - a great alternative to automate the Chrome browser without programming skills. It also supports fingerprint substitution, has simple and powerful multithreading and other advantages.

Testing

The excellent mocha framework is used for tests in this library. Use the command line or ready-made scripts if you want to run them yourself.

In order to test getting fingerprints from the service (as well as premium functionality), set the FINGERPRINT_KEY environment variable:

FINGERPRINT_KEY="VALUE"

This variable will be used when calling the fetch method. You can also use the FINGERPRINT_CWD variable to specify the directory where the engine will be stored, for example:

FINGERPRINT_CWD="../plugin-engine"

You can define it in any way convenient for you, but by default variables are read from the env files using the dotenv library.

License

Copyright © 2022 - 2022, CheshireCaat. Released under the MIT license.