fingerprint-coherence 0.2.2

Browser fingerprint consistency checker — UA, Client Hints, WebGL, timezone lint. CLI: fp-coherence.

fingerprint-coherence

Browser fingerprint consistency checker — lint UA, Client Hints, WebGL, and timezone contradictions before deploy.

pip install fingerprint-coherence
fp-coherence audit profile.yaml --strict

CLI: fp-coherence · Python 3.10+ · optional [mlx] for Launcher helpers

Audit browser fingerprint configurations for internal coherence — do UA, navigator.platform, screen size, timezone, languages, WebGL, and Client Hints tell the same story?

Returns a 0–100 coherence score and human-readable violations. No antidetect browser required for audit and score; optional live collection via Playwright.

Problem

JS-level fingerprint spoofing often creates contradictions:

• iPhone UA with Win32 platform and 1920×1080 screen
• America/New_York timezone with ja-JP as the primary language
• sec-ch-ua-platform: "Windows" on a macOS user agent
• Apple WebGL renderer on a Windows UA string

Bot-detection stacks hunt these mismatches. fp-coherence gives developers a fast lint for stealth configs before they hit production traffic.

Install

pip install fingerprint-coherence
playwright install chromium   # only for from-playwright

Development:

pip install fingerprint-coherence[mlx]

# Audit MLX Cloud profile before production
export MLX_TOKEN=your_bearer_token
fp-coherence mlx-profile --profile-id PROFILE_UUID --strict

pip install fingerprint-coherence[dev]

Quick start

# Audit a YAML config with a platform ruleset
fp-coherence audit --ruleset windows-chrome --config my-profile.yaml

# Or pass the config as a positional argument
fp-coherence audit my-profile.yaml --ruleset windows-chrome --json --strict

# Lint explicit fields (no config file)
fp-coherence audit \
  --ua "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." \
  --screen 1920x1080 \
  --timezone America/New_York \
  --platform Win32 \
  --lang en-US

# Export JSON Schema for CI validation
fp-coherence export-schema -o schema.json

# Collect from a real Playwright launch
fp-coherence from-playwright --url about:blank --ruleset windows-chrome

CLI

Command	Description
fp-coherence audit --config my.yaml --ruleset windows-chrome	Audit YAML config with platform ruleset
fp-coherence audit --ua ... --screen WxH	Audit CLI-provided fields
fp-coherence from-playwright --url URL	Collect live signals + audit
fp-coherence score config.yaml --ruleset mac-safari	Score config against ruleset
fp-coherence export-schema -o schema.json	Export JSON Schema bundle
fp-coherence mlx-profile --profile-id UUID	Fetch MLX fingerprint via API + audit ([mlx])

Options

• --ruleset NAME\|PATH — built-in (windows-chrome, mac-safari, android-chrome) or custom YAML path
• --json — machine-readable output (includes violation code fields)
• --strict — exit 1 when violations exist

Built-in rulesets

Ruleset	Use when
windows-chrome	Desktop Windows + Chromium / Chrome
mac-safari	macOS Safari (Client Hints checks disabled)
android-chrome	Mobile Android + Chrome

Shipped under fingerprint_coherence/rulesets/. Custom rulesets use the same YAML shape as default.yaml.

Violation codes

Code	Name	Check
E001	UA_OS_MISMATCH	platform_matches_ua
E002	SCREEN_IMPOSSIBLE	mobile_screen_alignment
E003	TIMEZONE_LANG_MISMATCH	timezone_language
E004	CH_PLATFORM_MISMATCH	client_hints_platform
E005	CH_MOBILE_MISMATCH	client_hints_mobile
E006	CHROME_VERSION_MISMATCH	chrome_version_hints
E007	WEBGL_OS_MISMATCH	webgl_os_alignment
E008	SCREEN_AVAIL_OVERFLOW	screen_avail_bounds
E009	TOUCH_POINTS_MISMATCH	touch_points_mobile
E010	DPR_IMPLAUSIBLE	dpr_screen_sanity
E011	UA_INVALID	ua_required (empty or HeadlessChrome)

Filter in CI: jq '.violations[] | select(.code == "E001")' audit.json

Exit codes

Code	Meaning
0	No violations (or non-strict mode)
1	Violations found with --strict
2	Runtime error

YAML config format

user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
platform: "Win32"
screen: 1920x1080
timezone: America/New_York
languages:
  - en-US
webgl_vendor: "Google Inc. (NVIDIA)"
webgl_renderer: "ANGLE (NVIDIA, ...)"
client_hints:
  sec_ch_ua: '"Chromium";v="120", "Google Chrome";v="120"'
  sec_ch_ua_platform: '"Windows"'
  sec_ch_ua_mobile: "?0"

Rule engine

Bundled ruleset (fingerprint_coherence/rules/default.yaml) checks:

Rule	What it validates
platform_matches_ua	navigator.platform vs UA OS family
mobile_screen_alignment	Mobile UA vs desktop screen widths
timezone_language	IANA timezone vs primary language
client_hints_platform	sec-ch-ua-platform vs UA
client_hints_mobile	sec-ch-ua-mobile vs form factor
chrome_version_hints	Chromium version in UA vs Client Hints
webgl_os_alignment	WebGL vendor/renderer vs claimed OS
screen_avail_bounds	availWidth/Height ≤ screen size
touch_points_mobile	maxTouchPoints vs mobile/desktop UA
dpr_screen_sanity	devicePixelRatio plausibility

Custom rulesets reference built-in check names:

rules:
  - id: my_rule
    severity: high
    check: platform_matches_ua
    enabled: true

Scoring

Start at 100, deduct by severity: high −18, medium −10, low −5.

Grade	Score
coherent	≥ 85
minor-drift	65–84
inconsistent	40–64
contradictory	< 40

API

from fingerprint_coherence import CoherenceEngine, FingerprintProfile

profile = FingerprintProfile(
    user_agent="Mozilla/5.0 (iPhone; ...) ...",
    platform="Win32",
    screen_width=1920,
    screen_height=1080,
    timezone="America/New_York",
    languages=["en-US"],
)
result = CoherenceEngine().audit(profile)
print(result.score, result.grade)
for v in result.violations:
    print(v.code, v.rule_id, v.message)

Common violations when using playwright-stealth

Libraries like playwright-stealth patch individual APIs at runtime. That often fixes navigator.webdriver but leaves cross-signal drift that fp-coherence catches:

Symptom	Typical cause	Code
HeadlessChrome still in UA	Stealth plugin not applied before first navigation	E011
iPhone UA + Win32 platform	UA overridden, navigator.platform left default	E001
Mobile UA + 1920×1080 viewport	Desktop viewport with mobile UA string	E002
Windows UA + sec-ch-ua-platform: "Linux"	Client Hints not patched to match UA	E004
Desktop UA + sec-ch-ua-mobile: ?1	Mobile hint left at Chromium default	E005
Chrome 120 UA + v="119" in sec-ch-ua	Version bump in UA only, hints stale	E006
Windows UA + Apple WebGL renderer	WebGL override from wrong OS template	E007
availWidth > screen.width	Taskbar/chrome UI math wrong in screen spoof	E008
Android UA + maxTouchPoints: 0	Touch API not patched for mobile profile	E009
Pixel 7 viewport + devicePixelRatio: 1	DPR not aligned with mobile screen	E010

Workflow: export your intended YAML profile, run fp-coherence from-playwright --ruleset android-chrome, compare violations against the target config, then fix the highest-severity codes first (E001, E002, E004, E007).

JS spoofing vs profile-level fingerprints

This tool measures logical consistency, not whether spoofing evades detection.

Patching individual JS APIs (navigator.webdriver, canvas noise, WebGL overrides) frequently leaves cross-signal contradictions — one property updated, another forgotten. That is exactly what fp-coherence surfaces.

Antidetect browsers (e.g. Multilogin X, GoLogin) manage fingerprints at the profile level — OS, screen, timezone, WebGL, and Client Hints are provisioned together, which reduces internal drift compared to ad-hoc Playwright patches.

Use fp-coherence to:

1. Lint YAML configs before loading them into automation
2. Compare a patched Playwright launch (from-playwright) against your intended profile
3. Regression-test rule changes in CI with --strict

When coherence score stays low (playbook)

High exposure from cdp-probe with high coherence here means different problems — fix both.

Score band	Grade	Likely issue	Next step
< 40	contradictory	Multiple E001/E004/E007	Rebuild profile template; avoid patchwork stealth
40–64	inconsistent	Client Hints or WebGL drift	Fix E004–E007 before traffic
65–84	minor-drift	Timezone/lang or DPR	Tune E003, E010; re-audit
≥ 85	coherent	Internal signals align	Run cdp-probe for CDP leaks

Pre-production pipeline:

proxy-lane check proxies.txt -o lanes.json
fp-coherence audit profile.yaml --ruleset windows-chrome --strict --json -o audit.json
profile-factory render profile.yaml --vars ... -o payload.json
fp-coherence mlx-profile --profile-id UUID --strict    # optional MLX API audit
cdp-probe mlx --profile-id UUID --url https://example.com

Coherence measures logical consistency — not whether a site accepts you.

Limitations

• Heuristic rules — timezone/language mapping is simplified, not exhaustive.
• Client Hints — only available in Chromium; from-playwright may return null hints in some builds.
• Not a bypass tool — high coherence ≠ undetectable; low coherence ≠ instant block.
• No canvas/font audit — focuses on UA, screen, timezone, WebGL, and Client Hints alignment.

Production

Lint YAML with fp-coherence before profile-yaml-factory mlx-create, then validate live Launcher sessions with playwright-cdp-probe.

Partner note (affiliate): Profile-level antidetect (e.g. Multilogin X) provisions OS, screen, WebGL, and Client Hints together — often fewer E001–E007 violations than ad-hoc Playwright patches. If you outgrow JS spoofing, eligible new browser purchases may accept code SAAS50 at multilogin.com — verify terms before checkout. audit/score need no MLX account. Full disclosure: docs/AFFILIATE.md. Coupon details only via fp-coherence --show-deal (never printed by default).

FAQ: docs/FAQ.md — browser fingerprint consistency, Client Hints mismatch, playwright-stealth vs profile.

Related tools (on PyPI)

Package	CLI	Role
playwright-cdp-probe	cdp-probe	CDP / WebDriver exposure score
cookie-jar-bridge	cookie-bridge	Netscape ↔ Playwright cookies
proxy-lane-checker	proxy-lane	Proxy TCP / HTTP / geo / DNSBL
fingerprint-coherence	fp-coherence	UA / screen / timezone lint

Toolkit pipeline: proxy-lane check → fp-coherence audit → automate → cdp-probe run → cookie-bridge validate

License

MIT

---

Production antidetect: Multilogin X · Code SAAS50 (-50% browser) · MIN50 (-50% cloud phone)
More scripts: @Multilogin_Scripts_Bot · Coupons