browserforge

<h1 align="center"> BrowserForge </h1> <p align="center"> <a href="https://github.com/daijro/browserforge/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/daijro/browserforge.svg?color=yellow"> </a> <a href="https://python.org/"> <img src="https://img.shields.io/badge/python-3.8&#8208;3.12-blue"> </a> <a href="https://pypi.org/project/browserforge/"> <img alt="PyPI" src="https://img.shields.io/pypi/v/browserforge.svg?color=orange"> </a> <a href="https://pepy.tech/project/browserforge"> <img alt="PyPI" src="https://static.pepy.tech/badge/browserforge"> </a> <a href="https://github.com/ambv/black"> <img src="https://img.shields.io/badge/code%20style-black-black.svg"> </a> <a href="https://github.com/PyCQA/isort"> <img src="https://img.shields.io/badge/imports-isort-yellow.svg"> </a> <a href="http://mypy-lang.org"> <img src="http://www.mypy-lang.org/static/mypy_badge.svg"> </a> </p> <h4 align="center"> 🎭 Intelligent browser header & fingerprint generator </h4>

---

What is it?

BrowserForge is a browser header and fingerprint generator that mimics the frequency of different browsers, operating systems, and devices found in the wild.

It is a reimplementation of Apify's fingerprint-suite in Python.

Features

• Uses a Bayesian generative network to mimic actual web traffic
• Extremely fast runtime (0.1-0.2 miliseconds)
• Easy and simple for humans to use
• Extensive customization options for browsers, operating systems, devices, locales, and HTTP version
• Written with type safety

Installation

pip install browserforge[all]

Usage

Generating Headers

Simple usage

>>> from browserforge.headers import HeaderGenerator
>>> headers = HeaderGenerator()
>>> headers.generate()
{'sec-ch-ua': '"Chromium";v="142", "Google Chrome";v="142", "Not_A Brand";v="99"', 'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"Windows"', 'Upgrade-Insecure-Requests': '1', 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36', 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8', 'Sec-Fetch-Site': '?1', 'Sec-Fetch-Mode': 'same-site', 'Sec-Fetch-User': 'document', 'Sec-Fetch-Dest': 'navigate', 'Accept-Encoding': 'gzip, deflate, br, zstd', 'Accept-Language': 'en-US;q=1.0, en;q=0.9, de;q=0.8'}

Using with requests

Headers can be added to a session in requests (or similar libraries) by assigning them to the headers attribute:

import requests
session = requests.Session()
# Set the session headers
session.headers = headers.generate()

<details> <summary>Parameters for HeaderGenerator</summary>

Parameters:
    browser (Union[ListOrString, Iterable[Browser]], optional): Browser(s) or Browser object(s).
    os (ListOrString, optional): Operating system(s) to generate headers for.
    device (ListOrString, optional): Device(s) to generate the headers for.
    locale (ListOrString, optional): List of at most 10 languages for the Accept-Language header. Default is 'en-US'.
    http_version (Literal[1, 2], optional): Http version to be used to generate headers. Defaults to 2.
    strict (bool, optional): Throws an error if it cannot generate headers based on the input. Defaults to False.

</details> <details> <summary>Parameters for HeaderGenerator.generate</summary>

Generates headers using the default options and their possible overrides.

Parameters:
    browser (Optional[Iterable[Union[str, Browser]]], optional): Browser(s) to generate the headers for.
    os (Optional[ListOrString], optional): Operating system(s) to generate the headers for.
    device (Optional[ListOrString], optional): Device(s) to generate the headers for.
    locale (Optional[ListOrString], optional): Language(s) to include in the Accept-Language header.
    http_version (Optional[Literal[1, 2]], optional): HTTP version to be used to generate headers.
    user_agent (Optional[ListOrString], optional): User-Agent(s) to use.
    request_dependent_headers (Optional[Dict[str, str]], optional): Known values of request-dependent headers.
    strict (Optional[bool], optional): If true, throws an error if it cannot generate headers based on the input.

</details>

Constraining headers

Single constraint

Set constraints for browsers by passing the optional strings below:

headers = HeaderGenerator(
    browser='chrome',
    os='windows',
    device='desktop',
    locale='en-US',
    http_version=2
)

Multiple constraints

Set multiple constraints to select from. Options are selected based on their actual frequency in the wild:

headers = HeaderGenerator(
    browser=('chrome', 'firefox', 'safari', 'edge'),
    os=('windows', 'macos', 'linux', 'android', 'ios'),
    device=('desktop', 'mobile'),
    locale=('en-US', 'en', 'de'),
    http_version=2
)

Browser specifications

Set specificiations for browsers, including version ranges and HTTP version:

from browserforge.headers import Browser

browsers = [
    Browser(name='chrome', min_version=140, max_version=145),
    Browser(name='firefox', min_version=144),
    Browser(name='edge', max_version=140, http_version=1),
]
headers = HeaderGenerator(browser=browsers)

Note that all constraints passed into the HeaderGenerator constructor can be overridden by passing them into the generate method.

Generate headers given User-Agent

Headers can be generated given an existing user agent:

>>> headers.generate(user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36')

Select from multiple User-Agents based on their frequency in the wild:

>>> headers.generate(user_agent=(
    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:144.0) Gecko/20100101 Firefox/144.0',
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36'
))

<hr width=50>

Generating Fingerprints

Simple usage

Initialize FingerprintGenerator:

from browserforge.fingerprints import FingerprintGenerator
fingerprints = FingerprintGenerator()
fingerprints.generate()

<details> <summary>Parameters for FingerprintGenerator</summary>

Parameters:
    screen (Screen, optional): Screen constraints for the generated fingerprint.
    strict (bool, optional): Whether to raise an exception if the constraints are too strict. Default is False.
    mock_webrtc (bool, optional): Whether to mock WebRTC when injecting the fingerprint. Default is False.
    slim (bool, optional): Disables performance-heavy evasions when injecting the fingerprint. Default is False.
    **header_kwargs: Header generation options for HeaderGenerator

</details> <details> <summary>Parameters for FingerprintGenerator.generate</summary>

Generates a fingerprint and a matching set of ordered headers using a combination of the default options specified in the constructor and their possible overrides provided here.

Parameters:
    screen (Screen, optional): Screen constraints for the generated fingerprint.
    strict (bool, optional): Whether to raise an exception if the constraints are too strict.
    mock_webrtc (bool, optional): Whether to mock WebRTC when injecting the fingerprint. Default is False.
    slim (bool, optional): Disables performance-heavy evasions when injecting the fingerprint. Default is False.
    **header_kwargs: Additional header generation options for HeaderGenerator.generate

</details> <details> <summary>Example response</summary>

Fingerprint(screen=ScreenFingerprint(availHeight=784,
                                     availWidth=1440,
                                     availTop=25,
                                     availLeft=0,
                                     colorDepth=30,
                                     height=900,
                                     pixelDepth=30,
                                     width=1440,
                                     devicePixelRatio=2,
                                     pageXOffset=0,
                                     pageYOffset=0,
                                     innerHeight=0,
                                     outerHeight=718,
                                     outerWidth=1440,
                                     innerWidth=0,
                                     screenX=0,
                                     clientWidth=0,
                                     clientHeight=19,
                                     hasHDR=True),
            navigator=NavigatorFingerprint(userAgent='Mozilla/5.0 (Macintosh; '
                                                     'Intel Mac OS X 10_15_7) '
                                                     'AppleWebKit/537.36 '
                                                     '(KHTML, like Gecko) '
                                                     'Chrome/121.0.0.0 '
                                                     'Safari/537.36',
                                           userAgentData={'architecture': 'arm',
                                                          'bitness': '64',
                                                          'brands': [{'brand': 'Not '
                                                                               'A(Brand',
                                                                      'version': '99'},
                                                                     {'brand': 'Google '
                                                                               'Chrome',
                                                                      'version': '121'},