DOCSEARCHbyAlgolia
Submit Docs

BotBrowser Documentation

repository·main·Indexed 25 days ago

https://github.com/botswin/botbrowser

An advanced privacy browser core providing unified, cross-platform fingerprint protection across Windows, macOS, and Linux. Includes BotBrowser Control (v1.2.2), a professional browser profile manager for creating isolated sessions with advanced spoofing for identity, network, and behavior. Documentation covers installation, GUI profile configuration, CLI flag mappings, Docker deployment for privacy research, and integration with Playwright and Puppeteer via CDP.

Tokens
141.3K
Snippets
286
Records
611
Agent score
80%

What's inside BotBrowser

  1. Overview of BotBrowser specialized tools

    main

    BotBrowser provides a suite of specialized utilities designed for fingerprint analysis, validation, and debugging. These tools allow developers and researchers to verify privacy protections and inspect how browsers expose signals.

    Available Tools

    • Mirror: Used for distributed privacy consistency (ENT Tier3). It allows you to verify privacy protection across multiple browser instances simultaneously.
    • CanvasLab: Used for Canvas 2D, WebGL, and WebGL2 forensics (ENT Tier4). It provides Canvas recording evidence review and profile-backed replay workflows for privacy defense.
    • AudioLab: Used for Web Audio API forensics. It enables analysis of audio fingerprint collection through graph visualization, recipe detection, and sample inspection.
    • V8Log: Used for browser runtime forensics. It allows for the review of runtime evidence regarding browser signal collection for authorized privacy validation.

  2. What is CanvasLab?

    main

    CanvasLab is a forensics tool used to record every Canvas 2D, WebGL, WebGL2, and WebGPU API call made by a webpage. It allows developers to:

    • Review graphics signals: Inspect every Canvas and WebGL API call a page makes.
    • Validate protections: Verify that BotBrowser's privacy protections produce the expected protected behavior.
    • Check consistency: Ensure privacy defenses work identically across Windows, macOS, and Linux.
    • Document privacy risk: Understand which graphics surfaces require protection.
    • Source Code Attribution: Identify which specific scripts are calling Canvas APIs using recorded source locations (URL, line, and column).

  3. What is AudioLab?

    main

    AudioLab is a web audio forensics tool designed for privacy protection. It records every Web Audio API call to help developers:

    • See what trackers collect: Monitor AudioContext creation, node instantiation, parameter changes, and data extraction.
    • Identify recipes: Automatically detect common audio fingerprinting patterns.
    • Visualize audio graphs: Use an interactive topology view to see node routing (e.g., oscillator -> compressor -> destination).
    • Inspect extracted data: Preview samples, sums, frequency data, and codec checks.
    • Test defenses: Verify that BotBrowser's audio noise protection effectively mitigates fingerprinting.

  5. Performance overhead of BotBrowser fingerprinting

    main

    BotBrowser is designed to provide fingerprint protection with minimal impact on performance:

    • JavaScript & DOM Performance: Near-zero overhead. Speedometer 3.0 benchmarks show <1% difference compared to stock Chromium in both headed and headless modes.
    • Fingerprint API Latency: Zero measurable overhead for Canvas2D, WebGL, Navigator, Screen, and Font APIs. Latency remains identical to stock Chrome.
    • Page Load Time: There is a one-time overhead of approximately 72-76ms during the first page load of a profile. This is due to the time required to read and apply the fingerprint configuration.

  6. Reference BotBrowser feature catalog

    main

    BotBrowser provides extensive features across several domains. Use the following categories to find specific capabilities:

    Network & Proxy

    Includes proxy support (HTTP/SOCKS5/SOCKS5H), regex-based routing, per-context proxies, dynamic proxy switching, UDP over SOCKS5, PAC-like request callbacks, local DNS solving, and WebRTC leak protection.

    Fingerprint & Rendering

    Includes deterministic noise for Canvas, WebGL, WebGPU, and AudioContext; text metrics/font noise; performance timing protection; video FPS control; stack depth control; and memory/storage quota management.

    Identity & Platform

    Includes cross-platform profile portability, browser brand switching (Chrome/Edge/Brave/Opera), custom User-Agent control, Client Hints alignment, and Android WebView emulation.

    Automation & Scripting

    Includes Playwright/Puppeteer integration, framework-less bot-scripts via chrome.debugger API, console message suppression, and specialized recording tools like CanvasLab and AudioLab.

    Session & Behavior

    Includes cookie and bookmark management, history injection, custom HTTP headers, window/screen dimension control, and mobile device emulation (orientation/keyboard).

  7. Review BotBrowser Fingerprint Protection Validation Results

    main

    BotBrowser provides validation results demonstrating its ability to maintain privacy and bypass fingerprinting/bot detection across various real-world services. These results are categorized into:

    1. Cross-Platform Fingerprint Protection: Performance against anti-bot services like Cloudflare, Akamai, Kasada, F5 Shape, reCAPTCHA, PerimeterX, DataDome, hCaptcha, and more.
    2. Tracking Systems: Effectiveness against fingerprinting and automation detection tools such as FingerprintJS, CreepJS, BrowserScan, Pixelscan, and Iphey.
    3. E-commerce and Popular Websites: Real-world compatibility testing on platforms like Temu, Shopee, Naver, Walmart, Nike, Ticketmaster, Instagram, and TikTok.
    4. Internal Protection Verification: Tests ensuring isolation of framework artifacts, DevTools detection prevention, and cross-context protection (iframes, canvas, workers).

    Detailed video demonstrations for specific service tests are available via the links provided in the validation documentation.

  8. Performance characteristics of BotBrowser

    main

    BotBrowser is optimized for production workloads with minimal impact on browser performance and high efficiency when scaling concurrent profiles:

    Speed and Latency

    • Zero measurable overhead on Speedometer 3.0 benchmarks (headless and headed modes).
    • Zero fingerprint API overhead: Latency for Canvas, WebGL, Navigator, Screen, and Font APIs remains identical to standard browsers across macOS, Linux, and Windows.

    Scaling with Per-Context Fingerprint (ENT Tier 3)

    When using the Per-Context Fingerprint feature, users can achieve significant resource savings while maintaining full isolation:

    • Memory Efficiency: ~29% less memory usage at 50 concurrent profiles.
    • Speed: 2x faster profile creation.
    • Process Management: 57% fewer OS processes.
    • Isolation: 100% canvas fingerprint isolation (each context produces a unique hash).

    Platform Consistency

    Performance is consistent across macOS arm64, Linux x64, and Windows x64.

  9. Access browser storage data directly from disk

    main
    ENT Tier1 profiles in BotBrowser enable plaintext storage mode. This allows you to programmatically read browser data (cookies, passwords, credit cards, and LocalStorage) directly from the disk after a session without needing decryption. This is useful for session extraction, credential migration, and debugging authentication flows.

  10. Understand the BotBrowser Patch Repository

    main

    This repository contains selected, non-proprietary patches from the BotBrowser engine. These patches are provided for educational purposes, fingerprint protection research, and privacy analysis.

    Key distinctions:

    • The Engine: The full BotBrowser engine is proprietary and built in-house on top of Chromium without external forks.
    • The Launcher: Only the GUI (BotBrowserLauncher) is open source.
    • The Patches: This specific repository contains only select examples of Chromium source modifications used for fingerprint protection and V8-level tracking mitigation.

  11. What is Mirror and how does it work?

    main

    Mirror is a distributed privacy consistency tool (ENT Tier3) used to verify that browser profiles maintain identical privacy protections across different platforms (Windows, macOS, Linux) and geographies.

    It uses a controller-client model:

    1. Controller: A primary browser instance that captures user input (mouse, keyboard, scroll).
    2. Network: Transmits these events as JSON lines over TCP.
    3. Clients: Remote browser instances that receive and replay the events.

    Because all coordinates are window-relative (measured from the top-left corner of the browser window), Mirror works correctly across different monitor setups and screen resolutions without needing coordinate translation.

  12. What is V8Log Forensics

    main

    V8Log is a gated, privacy-focused browser-runtime forensics mode designed for authorized privacy validation sessions. It records runtime call sequences, arguments, return previews, frame context, and event order into local JSONL files.

    It is specifically intended for scenarios where source code review is difficult due to packed JavaScript, VM-style bundles, or WebAssembly, allowing teams to review exactly how page scripts collect browser signals.