Skip to main content

phasmid-profile-gen

Test License: BSD-3-Clause Python 3.12+

Generates device profiles for Phasmid, the Chromium fork that reports the device described by one JSON profile instead of the machine it runs on.

Every device field of a profile comes from one capture of a real device: no population model is sampled and no GPU identity is derived. The captures, the schema and the locale tables are bundled in compressed form, so it runs without a Phasmid checkout.

Install

pip install phasmid-profile-gen                # profiles with a given time zone
pip install 'phasmid-profile-gen[location]'    # also place profiles at a proxy exit IP

Python 3.12 or newer. The location extra adds timezonefinder (with its boundary data, about 33 MB) and maxminddb, pinned exactly because they decide which zone and position a seed gets.

Use

from phasmid_profile_gen import dumps, generate_profile

# Placed where the proxy comes out: zone, geolocation, WebRTC address, languages.
profile = generate_profile("windows", exit_ip=proxy_exit_ip)

# Or with an explicit locale, reproducibly.
profile = generate_profile(
    "linux",
    seed="0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    timezone="Europe/Berlin",
    languages=["de-DE", "de", "en-US", "en"],
)
open("profile.json", "w").write(dumps(profile))
phasmid-profile-gen generate --os windows --exit-ip <proxy exit IP> -o profile.json
phasmid-profile-gen generate --os linux --seed 0a1b2c3d4e5f60718293a4b5c6d7e8f9 \
    --timezone Europe/Berlin --languages de-DE,de,en-US,en -o profile.json
phasmid-profile-gen gpus          # GPUs the bundled captures back (for --gpu)
phasmid-profile-gen captures      # the bundled captures
phasmid-profile-gen locate <proxy exit IP> --seed <seed>
phasmid-profile-gen validate profile.json

Give exactly one of an exit IP and a time zone. Generate Windows profiles with an exit IP. Windows Chrome answers geolocation from the system location provider, so a Windows profile with no position is a stronger tell than a Linux one. The seed is 32 lowercase hex characters. When omitted, a new one is drawn; read it back from profile["seed"]. The same seed and inputs always give the same bytes (dumps).

Choosing the capture

Which capture backs a profile is a ProfileGenerator's choice: any object with generate(request: Request) -> dict. The default, RandomCapture(), draws one of the OS's captures (those with the requested GPU, when gpu= is given) uniformly from the seed. Pass another strategy as generator=; from_capture(capture, request) builds the profile once a capture is chosen:

from phasmid_profile_gen import Request, catalog, from_capture, generate_profile

class Newest:
    def generate(self, request: Request) -> dict:
        captures = [c for c in catalog() if c.family == request.family]
        newest = max(captures, key=lambda c: c.date)
        return from_capture(newest, request, how="the newest capture")

profile = generate_profile("windows", timezone="UTC", generator=Newest())

A generator draws only from request.seed (_rng.decision_rng(seed, decision)), so a seed keeps giving the same profile. generate_profile validates whatever it returns.

Other functions: locate(ip, seed), list_gpus(), list_captures(), validate(profile) (against the bundled Phasmid schema) and new_seed(). Errors are GenerationError, LocationError and geoip.GeoipError.

What a profile is made of

Part From
OS identity and version, CPU threads, memory, touch points, screen and window geometry, GPU with its WebGL and WebGPU surface, fonts, voices, audio, codecs, system colours, pointer, preferences, RAM, disk, media devices, battery, connection One capture of a real device, taken whole.
Time zone, geolocation, WebRTC public IP, languages The exit IP: DB-IP City Lite, timezonefinder, CLDR, and Chrome's default accept-languages for the country's UI locale. Otherwise the time zone and languages you pass.

No user-agent or version string is written. Phasmid builds those from its own version. Nothing is invented: a field only a capture can supply is never filled in by guessing, and an OS without a capture fails with MissingCaptures. captured.note records where every part came from.

Bundled captures

Run phasmid-profile-gen captures for the current list. It is also in data/manifest.json, which lists the dumps refused and why.

Each is named by its OS family and PCI ids (windows-0x8086-0x0412). Where a capture has no media device labels (a page visit grants no media permission), profiles built from it claim no microphone, speaker or camera.

A profile's OS version is its capture's, so a Windows 11 capture gives Windows 11 profiles with Windows 11 fonts and colours.

The location database

The exit IP is looked up in DB-IP IP to City Lite (CC BY 4.0, "IP Geolocation by DB-IP"). It is about 127 MB, so it is not bundled. The build pinned in data/dbip-city-lite.json is downloaded on first use, checked against the pin, and kept in $XDG_CACHE_HOME/phasmid/geoip/. That is the cache Phasmid's tools use, so an existing download is reused.

phasmid-profile-gen geoip                     # download and verify now
phasmid-profile-gen geoip --archive dbip-city-lite-2026-10.mmdb.gz

DB-IP serves only the last two monthly builds. Once the pinned one is gone, either install a saved copy with --archive, or use any other DB-IP City Lite build with PHASMID_GEOIP_MMDB=/path/to/dbip-city-lite.mmdb, --geoip-db or geoip_db=. Another build is not checked against the pin; the profile's note names its build date and sha256 instead.

Rebuilding the data

src/phasmid_profile_gen/data/ is generated, compressed and committed. It is rebuilt from a Phasmid checkout and further harness dumps by scripts/build_data.py:

uv run python scripts/build_data.py \
    --phasmid ../phasmid \
    --dumps /path/to/dumps

The build:

  • maps every dump with the checkout's own tests/consistency/capture.py (the code consistency capture runs), and checks Phasmid's captures against their records as tools/genprofile does;
  • keeps a dump only if it is stock desktop Google Chrome on Windows or Linux, with a hardware GPU, a consistent UA and UA-CH, and a window inside its screen, and only if it maps to a valid profile. Each refusal is listed with its reason in manifest.json;
  • takes the nearest whole-MB RAM when a dump's heap limit sits within 1 MiB of one but matches none exactly (a fraction of a MB of RAM), sets the heap limit to the one the browser computes for it, and lists both as assumed in manifest.json; a limit further off is refused;
  • stores only what generation reads, under a neutral name (OS family and PCI ids). Raw dumps, file names, notes and the device's locale are never written, and a refused dump is listed by hash only.

The output is deterministic, so a rebuild from the same sources gives the same bytes. A Linux dump also needs the operator's OS version (operator.os_version), which a page cannot read.

Develop

uv sync --all-extras
uv run pytest
uv run pre-commit run --all-files
PHASMID_GEOIP_NETWORK=1 uv run pytest -m network   # reads the real DB-IP build

Releases are published to PyPI by .github/workflows/publish-pypi.yaml when a GitHub release is published. The version comes from the release tag (uv-dynamic-versioning, e.g. v0.1.0). Publishing uses PyPI trusted publishing: register the repository and that workflow as a trusted publisher of phasmid-profile-gen on PyPI once.

Licence

The code is BSD 3-Clause, as Phasmid is (LICENSE). The bundled data keeps its sources' licences:

  • Unicode CLDR: Unicode License v3.
  • Chromium's locale table: BSD-style.

DB-IP (CC BY 4.0) and timezone-boundary-builder (ODbL 1.0) are used at runtime but not bundled. See data/LICENSES.md.

Metadata

Release files for phasmid-profile-gen 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phasmid-profile-gen 0.1.1
File Size Uploaded Provenance Actions
phasmid_profile_gen-0.1.1.tar.gz 111.3 kB Without provenance Details for phasmid_profile_gen-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phasmid-profile-gen 0.1.1
File Interpreter ABI Platform Actions
phasmid_profile_gen-0.1.1-py3-none-any.whl Python 3 none any Details for phasmid_profile_gen-0.1.1-py3-none-any.whl

Total release size: 168.8 kB

Release files / phasmid_profile_gen-0.1.1.tar.gz

Download URL phasmid_profile_gen-0.1.1.tar.gz
Size 111.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0c94d1d2d474e61bafd4e8c76ff8fd7c0d5082e1fc81666db6284ccc8fde0bc8
BLAKE2b-256 checksum
How to use checksums
8f06a26b54fb8267a5aa5a239a66e26584c08a2a24d74f976468d5caa0bd14f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / phasmid_profile_gen-0.1.1-py3-none-any.whl

Download URL phasmid_profile_gen-0.1.1-py3-none-any.whl
Size 57.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4dfcbb7f5d2c82330d5b587903d1bbc9584882414769135ab565208c778c5a8f
BLAKE2b-256 checksum
How to use checksums
425a1ccd543990d8b30a43d4758e1825d39e97a1701035b66102fc7597eeac88
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for phasmid-profile-gen 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page