fpgen Browser Fingerprint Generator

You can narrow down generated fingerprints by specifying filters for any data field. You can pass these as keyword arguments or as a dictionary.

Keyword arguments

fpgen.generate(os='Windows', browser='Chrome', gpu={'vendor': 'Google Inc. (Intel)'})

Dictionary format

fpgen.generate({
    'os': 'Windows',
    'browser': 'Chrome',
    'gpu': {'vendor': 'Google Inc. (Intel)'},
})

Multiple constraints

To allow the generator to select from multiple possible values for a field, pass them as a tuple:

fpgen.generate({
    'os': ('Windows', 'MacOS'),
    'browser': ('Firefox', 'Chrome'),
})

Note: If you are passing many nested constraints, run fpgen decompress to improve performance.

Install the fpgen package using the standard Python package manager, pip.

pip install fpgen

You can generate fingerprints using the top-level fpgen.generate() function or by instantiating a fpgen.Generator object. The Generator object is useful for passing common filters downward to multiple calls.

Simple generation

import fpgen
fpgen.generate(browser='Chrome', os='Windows')

Using a Generator object for inherited filters

gen = fpgen.Generator(browser='Chrome')
gen.generate(os='Windows') # Generates Chrome + Windows fingerprints

Use fpgen.query() to retrieve a list of all possible values for a specific target node.

# List all possible browsers
fpgen.query('browser')

# Query a nested path
fpgen.query('navigator.maxTouchPoints')

Note: Because the model is trained on live data, queries may occasionally return anomalous values. Values with a probability lower than 0.001% are excluded from traces and queries.

Use fpgen.trace() to calculate the probability distribution of a target variable given specific conditions. This helps you understand what kind of data is likely to be generated under certain constraints.

Single target trace

# Returns a list of TraceResult objects
results = fpgen.trace(target='browser', os='Windows')

Multiple target trace

# Returns a dictionary mapping probabilities to target values
results = fpgen.trace(
  target=('browser', 'os'),
  gpu={'vendor': 'Google Inc. (Intel)'}
)

Reading TraceResult objects

Each item in a single-target trace is a TraceResult object:

result = fpgen.trace(target='browser', os='ChromeOS')[0]
print(result.probability) # e.g., 1.0
print(result.value)       # e.g., 'Chrome'

fpgen.trace(target=('browser', 'os'), gpu={'vendor': 'Google Inc. (Intel)'})

If you only need a subset of the fingerprint data, use the target parameter or the generate_target shortcut.

Using target

Specify a single field or a dot-separated path for nested fields:

# Generate only HTTP headers
fpgen.generate(target='headers')

# Generate a specific nested field
fpgen.generate(os='Windows', browser='Chrome', target='headers.user-agent')

Using generate_target shortcut

fpgen.generate_target('headers')

Multiple targets

You can provide multiple targets as a list:

fpgen.generate(target=['headers', 'client'])

fpgen.generate(target='headers.user-agent')

When initializing a fpgen.Generator or calling fpgen.generate(), you can use the following parameters:

• conditions (dict, optional): Conditions for the generated fingerprint.
• window_bounds (WindowBounds, optional): Constrain the output window size.
• strict (bool, optional): Whether to raise an exception if the conditions are too strict.
• flatten (bool, optional): Whether to flatten the output dictionary.
• target (Optional[Union[str, StrContainer]]): Only generate specific value(s).
• **conditions_kwargs: Additional conditions for the fingerprint passed as keyword arguments.

When strict=True (the default), the generator will raise a RestrictiveConstraints exception if the provided conditions are logically impossible or too narrow to produce a valid fingerprint. If you want the generator to attempt to find the closest possible match by relaxing constraints, set strict=False.

from fpgen.generator import Generator
from fpgen.exceptions import RestrictiveConstraints

generator = Generator(strict=True)

try:
    # This might fail if the combination is impossible
    fp = generator.generate(os='Windows', browser='Safari')
except RestrictiveConstraints:
    print("The constraints provided are impossible to satisfy.")

The fpgen CLI allows you to manage the underlying generative model files.

• fpgen fetch: Downloads the latest model from GitHub. This is also triggered automatically on the first import or every 5 weeks.
• fpgen decompress: Decompresses model files to increase generation speed by up to 10-50x. Note that this requires an additional 100MB+ of storage.
• fpgen recompress: Compresses model files after you have run decompress.
• fpgen remove: Deletes all downloaded and extracted model files.

# Example: Fetch the latest model
fpgen fetch

# Example: Decompress for faster generation
fpgen decompress