fingerprint-coherence 0.2.0

Contradictory UA and screen signals get profiles flagged — lint fingerprints before create.

fingerprint-coherence

Python 3.10+ | MLX optional · Compatibility

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.

pip 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

Production

Partner offers, eligibility, and disclosure: docs/AFFILIATE.md.

At production scale, lint YAML profiles with fp-coherence before profile-factory mlx-create, then validate live sessions with playwright-cdp-probe on Launcher CDP ports.

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.

Guides

Monorepo playbooks (copy-paste commands, sample output, diagrams):

Guide	Flow
Detection fail → MLX farm	cdp-probe → cdp-connect → farm-runner mlx-pool
Competitor migration	antidetect-import → profile-factory mlx-create
Proxy lane → profile pool	proxy-lane → profile-factory → farm-runner mlx-pool

FAQ: docs/FAQ.md — fingerprint consistency, Client Hints, WebGL/UA alignment.

Related tools

Tool	Use with
playwright-cdp-probe — Score CDP/WebDriver exposure and fingerprint leaks	→ cdp-connect-kit when probe fails
cookie-jar-bridge — Convert, validate, and merge cookies across formats	→ session-bundle-kit for full session
proxy-lane-checker — Batch-check proxies for connectivity, geo, and DNSBL	→ profile-yaml-factory
fingerprint-coherence — Lint fingerprints for cross-signal contradictions	→ profile-yaml-factory before create
human-input-kit — Human-like mouse, scroll, and warmup replay	→ automation-farm-runner
cdp-connect-kit — Playwright CDP connect; MLX start/stop helpers	→ all packages needing CDP
session-bundle-kit — Export/import cookies and storage as portable bundles	→ cookie-jar-bridge
profile-yaml-factory — YAML blueprints → MLX profile/create payloads	→ antidetect-importer after migration
antidetect-importer — Parse competitor exports and push to MLX	→ profile-yaml-factory
automation-farm-runner — YAML job queue and MLX profile-pool runner	→ cdp-connect-kit [mlx]

License

MIT

---

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