fingerprint camouflage

[3-Tokisaki-Kurumi]

🔐 Browser Fingerprint Spoofing Feature / 浏览器指纹伪造功能

📋 Summary

This PR introduces a comprehensive browser fingerprint spoofing system that prevents browser fingerprint tracking by generating random but realistic browser fingerprints and injecting them into the browser runtime. The implementation has been updated to use the new centralized options configuration pattern.

🎯 Key Features

Core Components

• FingerprintGenerator: Generates random but realistic browser fingerprints
• FingerprintInjector: Injects fingerprints into browsers via JavaScript
• FingerprintManager: Manages fingerprint generation, storage, and application
• Fingerprint: Complete data model containing all fingerprint properties
• FingerprintConfig: Configuration class for customizing fingerprint generation

Browser Support

• ✅ Chrome/Chromium browsers
• ✅ Microsoft Edge
• ✅ Cross-platform compatibility (Windows, macOS, Linux)

Fingerprint Properties

• 🌐 Navigator Properties: User agent, platform, language, hardware concurrency
• 🖥️ Screen Properties: Resolution, color depth, viewport dimensions
• 🎨 WebGL Properties: Vendor, renderer, version, extensions
• 🎨 Canvas Fingerprinting: Unique canvas rendering signatures
• 🔊 Audio Context: Sample rate, state, channel count
• 🌍 Timezone & Locale: Timezone offset, language preferences
• 🔌 Plugin Information: Browser plugin data
• 📱 Device Properties: Memory, connection type, touch support

Advanced Features

• 💾 Persistent Storage: Save and reuse fingerprints
• 🎲 Entropy Sources: Multiple entropy sources for unique generation
• ⚙️ Customizable: Extensive configuration options
• 🔄 Consistent: Generates stable fingerprints across sessions
• 🎯 Realistic: Uses authentic browser data distributions

🚀 Usage Examples

Basic Usage (New API)

from pydoll.browser.chromium.chrome import Chrome
from pydoll.browser.options import ChromiumOptions

 New centralized options configuration
options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode()
browser = Chrome(options=options)

async with browser:
    tab = await browser.start()
    await tab.go_to("https://fingerprintjs.github.io/fingerprintjs/")

Advanced Configuration

from pydoll.browser.chromium.chrome import Chrome
from pydoll.browser.options import ChromiumOptions
from pydoll.fingerprint import FingerprintConfig

 Create fingerprint configuration
config = FingerprintConfig(
    browser_type="chrome",
    preferred_os="windows",
    enable_webgl_spoofing=True,
    enable_canvas_spoofing=True,
    preferred_languages=["en-US", "en"],
    min_screen_width=1920,
    max_screen_width=2560
)

 Configure browser options
options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode(config)
browser = Chrome(options=options)

Persistent Fingerprints

from pydoll.fingerprint import FingerprintManager

manager = FingerprintManager()
fingerprint = manager.generate_new_fingerprint("chrome")
manager.save_fingerprint("my_identity")

 Later reuse
manager.load_fingerprint("my_identity")

Edge Browser Support

from pydoll.browser.chromium.edge import Edge
from pydoll.browser.options import ChromiumOptions

options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode()
browser = Edge(options=options)

🛡️ Security Benefits

1. Anti-Detection: Prevents browser fingerprint tracking
2. Privacy Protection: Masks real browser characteristics
3. Consistent Identity: Maintains stable fingerprints across sessions
4. Realistic Spoofing: Uses authentic browser data patterns
5. Multiple Entropy: Ensures unique fingerprints every time

🔧 Recent Technical Updates

API Migration

• New Options Pattern: Migrated from direct constructor parameters to centralized ChromiumOptions configuration
• Improved Modularity: Better separation between browser initialization and feature configuration
• Consistent Interface: Unified API across Chrome and Edge browsers

Bug Fixes Applied

• ✅ Fixed string formatting errors in constants.py
• ✅ Resolved overly broad argument checking in tab.py
• ✅ Updated all example files to use new API
• ✅ Standardized test website to https://fingerprintjs.github.io/fingerprintjs/

Enhanced Testing

• ✅ Updated all test files for new API compatibility
• ✅ Fixed exception handling in fingerprint injection tests
• ✅ Improved mock object management in integration tests
• ✅ Enhanced coverage for edge cases

🧪 Testing & Quality Assurance

• ✅ Unit Tests: Comprehensive tests for all components
• ✅ Integration Tests: Real browser testing with Chrome and Edge
• ✅ API Migration Tests: Validation of new options pattern
• ✅ Coverage Tests: Targeting specific uncovered code lines
• ✅ Exception Handling: Robust error handling validation
• ✅ Cross-Platform: Windows, macOS, Linux compatibility

📁 File Structure

pydoll/fingerprint/
├── __init__.py               Module exports
├── generator.py              Fingerprint generation logic  
├── injector.py               JavaScript injection system
├── manager.py                Fingerprint management
└── models.py                 Data models and configurations

pydoll/browser/
├── options.py                ChromiumOptions with fingerprint support
└── managers/
    └── browser_options_manager.py   Options management

examples/
└── fingerprint_example.py    Updated usage examples

tests/
├── test_fingerprint.py       Core functionality tests
├── test_fingerprint_integration.py   Browser integration tests
├── test_fingerprint_coverage.py      Coverage-specific tests
└── test_exact_coverage.py    Precise line coverage tests

🔧 Technical Implementation Details

1. Centralized Configuration: New ChromiumOptions.enable_fingerprint_spoofing_mode() API
2. Options Manager Integration: Seamless integration with ChromiumOptionsManager
3. JavaScript Injection: Enhanced CDP-based API override system
4. Realistic Data Generation: Based on authentic browser usage statistics
5. Robust Error Handling: Graceful degradation when injection fails
6. Persistent Storage: Improved JSON-based fingerprint storage

🎯 Migration Guide

From Old API to New API:

 OLD (deprecated)
browser = Chrome(enable_fingerprint_spoofing=True)

 NEW (recommended)
options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode()
browser = Chrome(options=options)

---

📋 概述

此PR引入了一个全面的浏览器指纹伪造系统，通过生成随机但真实的浏览器指纹并将其注入到浏览器运行时来防止浏览器指纹跟踪。实现已更新为使用新的集中式选项配置模式。

🎯 核心功能

核心组件

• FingerprintGenerator: 生成随机但真实的浏览器指纹
• FingerprintInjector: 通过JavaScript将指纹注入浏览器
• FingerprintManager: 管理指纹的生成、存储和应用
• Fingerprint: 包含所有指纹属性的完整数据模型
• FingerprintConfig: 用于自定义指纹生成的配置类

🚀 使用示例

基础用法（新API）

from pydoll.browser.chromium.chrome import Chrome
from pydoll.browser.options import ChromiumOptions

 新的集中式选项配置
options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode()
browser = Chrome(options=options)

async with browser:
    tab = await browser.start()
    await tab.go_to("https://fingerprintjs.github.io/fingerprintjs/")

高级配置

from pydoll.fingerprint import FingerprintConfig

config = FingerprintConfig(
    browser_type="chrome",
    preferred_os="windows",
    enable_webgl_spoofing=True,
    enable_canvas_spoofing=True,
    preferred_languages=["zh-CN", "zh", "en-US"],
    min_screen_width=1920,
    max_screen_width=2560
)

options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode(config)
browser = Chrome(options=options)

🔧 最新技术更新

API迁移

• 新选项模式: 从直接构造函数参数迁移到集中式ChromiumOptions配置
• 改进的模块化: 更好地分离浏览器初始化和功能配置
• 统一接口: Chrome和Edge浏览器的统一API

应用的错误修复

• ✅ 修复了constants.py中的字符串格式错误
• ✅ 解决了tab.py中过于宽泛的参数检查
• ✅ 更新所有示例文件使用新API
• ✅ 标准化测试网站为https://fingerprintjs.github.io/fingerprintjs/

🎯 迁移指南

从旧API到新API：

 旧方式（已弃用）
browser = Chrome(enable_fingerprint_spoofing=True)

 新方式（推荐）
options = ChromiumOptions()
options.enable_fingerprint_spoofing_mode()
browser = Chrome(options=options)

---

🏷️ Labels

• feature - New feature
• security - Security enhancement
• privacy - Privacy protection
• browser - Browser automation
• fingerprint - Fingerprint spoofing
• api-migration - API modernization

📊 Metrics

• Lines of Code: ~2000+ lines
• Test Coverage: 95%+
• Supported Browsers: Chrome, Edge
• Configuration Options: 15+
• Fingerprint Properties: 25+
• Test Files Updated: 4 files
• Bug Fixes Applied: 5 major fixes

🎉 Summary

This feature adds comprehensive browser fingerprint protection capabilities to pydoll, enabling users to easily prevent fingerprint tracking while maintaining natural and consistent browser behavior. The updated API provides better modularity and easier integration, supporting both simple one-click enabling and complex custom configurations to meet different user needs.

[codecov]

Codecov Report

❌ Patch coverage is 99.44751% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pydoll/browser/chromium/base.py	97.05%	1 Missing ⚠️
pydoll/browser/managers/browser_options_manager.py	96.87%	1 Missing ⚠️
pydoll/browser/options.py	94.44%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[3-Tokisaki-Kurumi]

这些代码风格问题（空行空格、文件末尾换行等）不影响功能实现。考虑到当前 PR 的主要目的是添加指纹伪装功能，建议先审查功能有效性，这些微小的格式问题可以在后续优化。

[3-Tokisaki-Kurumi]

只是测试分支没有测试到，但是不影响使用

[thalissonvs]

Hi @3-Tokisaki-Kurumi , thank you so much for you contribution!

To maintain consistency with the rest of the code, we only need to translate what's necessary into English

[3-Tokisaki-Kurumi]

你好@3-Tokisaki-Kurumi，非常感谢您的贡献！

为了与其余代码保持一致，我们只需要将必要的内容翻译成英语

Thank you for your attention. I will translate the necessary content into English

[3-Tokisaki-Kurumi]

你好@3-Tokisaki-Kurumi，非常感谢您的贡献！

为了与其余代码保持一致，我们只需要将必要的内容翻译成英语

现在我已经将必要的内容和注释翻译成英语，您可以审阅一下，之后我会继续贡献更优化的代码

Now I have translated the necessary content and comments into English, you can review them, and I will continue to contribute more optimized code afterwards

[thalissonvs]

Hi @3-Tokisaki-Kurumi,

Sorry for the delay. I'm currently finalizing version 2 of Pydoll, which will introduce breaking changes. Once it's done, we can move forward with your contribution, as a few more adjustments will be needed. I appreciate your understanding

[3-Tokisaki-Kurumi]

你好@3-Tokisaki-Kurumi，

抱歉耽搁了。我目前正在最终完成 Pydoll 的 2.0 版本，这将引入一些重大更改。完成后，我们就可以继续处理您的贡献，因为还需要进行一些调整。感谢您的理解。

OK，期待你的Pydoll v2，感谢您带来了一个强大的自动化工具，等待你的更改之后我们可以继续处理此贡献

OK， Looking forward to your Pydoll v2. Thank you for bringing us a powerful automation tool. We are waiting for your changes before we can proceed with this contribution

[3-Tokisaki-Kurumi]

占位，准备继续完成该贡献

Position occupied, ready to continue completing the contribution

[3-Tokisaki-Kurumi]

你好@3-Tokisaki-Kurumi，

抱歉耽搁了。我目前正在最终完成 Pydoll 的 2.0 版本，这将引入一些重大更改。完成后，我们就可以继续处理您的贡献，因为还需要进行一些调整。感谢您的理解。

现在是最新的指纹伪装功能，你可以查看一下代码，如果需要，之后我会继续贡献

Now it's the latest fingerprint camouflage feature. You can review the code and if needed, I will continue to contribute in the future

[thalissonvs]

Hello! Once again, thank you very much for your efforts, I truly appreciate your contribution. However, I just noticed one thing: you didn't follow the Commitizen convention, which is required for release generation.

Before I can review your PR, could you please update your commit history to follow the guidelines described in this link?

You can do that by running the following commands:

git rebase -i HEAD~<number_of_commits_to_edit>
# Replace 'pick' with 'reword' for each commit
# Then rewrite each commit message using the Commitizen format

After that, force-push your changes. Also, everything must be in english. Thank you!

[3-Tokisaki-Kurumi]

@thalissonvs
Hello, thank you for your correction. I have updated my submission history to follow this [link]（ https://github.com/autoscrape-labs/pydoll/blob/main/CONTRIBUTING.md ）The guidelines described in the document have been forcibly pushed, and now you can review my PR. Thank you for your review

您好，感谢您的纠正，我已经更新了我的的提交历史记录以遵循此链接中描述的指南并且进行了强制推送，接下来您可以审查我的PR，感谢您的审查

[thalissonvs]

Hi @3-Tokisaki-Kurumi, I left some RC's that need to be resolved.

Also, it seems that your PR doesn’t reflect the new file structure introduced in the second version. If you need any help, I can implement some of the changes for you.

[3-Tokisaki-Kurumi]

您好，感谢您的指正，我会根据您的建议修改，如果您能提供一些帮助，我将感激不尽，麻烦您了

Hello, thank you for your correction. If you could provide some help, I would be extremely grateful. Thank you very much

[3-Tokisaki-Kurumi]

There may have been some ambiguity in the translation of the conversation, so I have roughly revised it once. If possible, please help me. Thank you very much @thalissonvs @thalissonvs

[3-Tokisaki-Kurumi]

@thalissonvs

[thalissonvs]

Hi @3-Tokisaki-Kurumi, can you give me your email? I'd like to talk to you about this feature and some ideas I have.

[3-Tokisaki-Kurumi]

Hi @3-Tokisaki-Kurumi, can you give me your email? I'd like to talk to you about this feature and some ideas I have.

hello，yes，This is my frequently used email address： zaphkiel_nightmare@qq.com ,Coincidentally, I am currently developing and compiling a fingerprint browser based on the Chromium kernel,We can talk about this feature and ask for your advice on pydoll related content

[3-Tokisaki-Kurumi]

你好@3-Tokisaki-Kurumi你能给我你的邮箱吗？我想跟你聊聊这个功能以及我的一些想法。

Hello, have you sent me a message? I haven't received any information @thalissonvs

[niv-iceweb]

This is amazing!, when will this be merged @3-Tokisaki-Kurumi

[3-Tokisaki-Kurumi]

This is amazing!, when will this be merged @3-Tokisaki-Kurumi

I am currently researching fingerprint browsers, and my current idea is to use automation frameworks such as Pydoll to operate my own fingerprint browser in the future. This will be more comprehensive than directly forging fingerprints, because methods such as JS injection can only achieve limited results. If you want to, you can also take a look at my repository's previous Pydoll enhancement, but it is a previous version and I have no time to worry about it recently

[thalissonvs]

Hey @3-Tokisaki-Kurumi , do you need any help with the conflicts?

[3-Tokisaki-Kurumi]

嘿@3-Tokisaki-Kurumi，您需要任何帮助来解决冲突吗？

Yes, I need your help

[3-Tokisaki-Kurumi]

yes，I need any help with the conflicts。I am wondering if it is possible for pydoll to control concurrent multiple browsers, allowing pydoll to control the browsers to complete cloudflare, and then playwright to take over the next tasks and implement integration with pydoll 

…

---Original--- From: "Thalison ***@***.***> Date: Sun, Sep 21, 2025 10:05 AM To: ***@***.***>; Cc: "Tokisaki ***@***.******@***.***>; Subject: Re: [autoscrape-labs/pydoll] fingerprint camouflage (PR #129) thalissonvs left a comment (autoscrape-labs/pydoll#129) Hey @3-Tokisaki-Kurumi , do you need any help with the conflicts? — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>