BotBrowser

<h1 align="center"><img src="docs/assets/logo-32.svg" alt="BotBrowser logo" width="32" height="32" /> BotBrowser</h1> <h4 align="center">Advanced Privacy Browser Core with Unified Fingerprint Defense 🚀</h4> <p align="center"> Identical privacy posture on any OS • Cross-platform & WebView simulation • Fingerprint protection validated across 31+ tracking scenarios </p> <p align="center"> <a href="https://github.com/botswin/BotBrowser/releases"> <img src="https://img.shields.io/github/v/release/botswin/BotBrowser?style=flat-square" alt="Latest Release"> </a> <a href="https://github.com/botswin/BotBrowser/commits/main/"> <img src="https://img.shields.io/github/commit-activity/m/botswin/BotBrowser?style=flat-square" alt="Commit Activity"> </a> <a href="https://github.com/botswin/BotBrowser/issues"> <img src="https://img.shields.io/github/issues/botswin/BotBrowser?style=flat-square" alt="Issues"> </a> <a href="https://github.com/botswin/BotBrowser/fork"> <img src="https://img.shields.io/github/forks/botswin/BotBrowser?style=flat-square" alt="GitHub Forks"> </a> <a href="https://github.com/botswin/BotBrowser"> <img src="https://img.shields.io/github/stars/botswin/BotBrowser" alt="GitHub Stars"> </a> <a href="https://botbrowser.io"> <img src="https://img.shields.io/badge/Website-botbrowser.io-blue?style=flat-square" alt="Website"> </a> </p> <div align="center"> <img width="600" alt="BotBrowser GUI - Your Command Center" src="https://github.com/user-attachments/assets/0f003494-ec92-4c3a-b879-b08d3521a0fb"> </div>

---

What Is BotBrowser?

BotBrowser is a privacy-first browser core designed to protect users from browser fingerprinting, a technique recognized as a privacy threat by W3C, major browser vendors, privacy regulators, and academic research (see references). It keeps fingerprint signals uniform across every platform, preventing tracking systems from collecting and correlating data to identify users. Run the same profile on Windows, macOS, or Linux and the fingerprint posture stays identical each time.

All engineering focuses on privacy research, cross-platform tracking-resistance validation, and maintaining protected environments for authorized defensive benchmarking. Review the project Legal Disclaimer and Responsible Use Guidelines before using the software.

---

Why BotBrowser

What makes BotBrowser different: Cross-platform privacy browser core with unified fingerprint technology that prevents tracking data collection and device linkage.

<table cellspacing="0" cellpadding="8"> <tr> <td width="50%"><strong>High-Fidelity, Always-Current Profiles</strong> including Android WebView, built on the latest stable Chromium so fingerprints always match current browser behavior and trackers cannot key on stale engines</td> <td width="50%"><strong>Network Stack Parity</strong> with <a href="ADVANCED_FEATURES.md#network-fingerprint-control">Full-Proxy QUIC/STUN</a> (UDP over SOCKS5) delivers Chromium-level tunneling so geo metadata does not leak and privacy labs maintain clean transport parity</td> </tr> <tr> <td width="50%"><strong>Advanced Programmatic Control</strong> offers <a href="examples/">Playwright/Puppeteer integration</a> with CDP leak blocking so privacy tooling leaves no telemetry residue</td> <td width="50%"><strong>Distributed Privacy Consistency</strong> lets you verify privacy protection across multiple browser instances simultaneously <a href="tools/mirror/">with Mirror</a>, synchronizing input and validating privacy posture in parallel</td> </tr> <tr> <td width="50%"><strong>Per-Context Fingerprint</strong> enables <a href="PER_CONTEXT_FINGERPRINT.md">independent fingerprint bundles per BrowserContext</a> without spawning new processes, with millisecond-level switching and reduced memory overhead</td> <td width="50%"><strong>Zero-Overhead Performance</strong> adds <a href="BENCHMARK.md">no measurable latency</a>: Speedometer 3.0 within &lt;1% of stock Chrome, zero fingerprint API overhead across macOS/Linux/Windows, and 29% memory savings at scale with Per-Context Fingerprint</td> </tr> </table>

Cross-Platform Fingerprint Protection

• Single profile, every host OS: identical UA, screen metrics, touch surfaces, fonts, and device APIs on Windows, macOS, Linux (ENT Tier1), Android (PRO), and WebView (ENT Tier3) so trackers see the same fingerprint everywhere.
• Built-in configuration handles touch simulation, device metrics, and locale/timezone detection from the proxy IP while still allowing CLI overrides when privacy experiments require them.
• Quick demos: ▶️ CreepJS Android • ▶️ Iphey • ▶️ Pixelscan

---

Getting Started

Quick Start

Step 1: Download

• Latest release for your OS
• Demo profile (any .enc file)

Step 2: Launch

• GUI: Use BotBrowserLauncher for one-click profile selection and multi-instance management
• CLI (use absolute paths):

  chrome.exe --bot-profile="C:\absolute\path\to\profile.enc" --user-data-dir="%TEMP%\botprofile_%RANDOM%"
  

• macOS/Linux commands follow the same pattern; see INSTALLATION.md for full instructions.

Step 3: Verify

• Visit CreepJS or your preferred tracking observatory to confirm identical privacy posture.
• Timezone/locale/language auto-derive from your proxy/IP; override via CLI only when needed.

Complete Installation Guide →

Minimal Playwright Example

const browser = await chromium.launch({
  headless: true,
  executablePath: BOTBROWSER_EXEC_PATH,
  args: [`--bot-profile=${BOT_PROFILE_PATH}`,
  '--proxy-server=socks5://usr:pwd@127.0.0.1:8989']  // or: http://usr:pwd@127.0.0.1:8989
});
const page = await browser.newPage();
await page.addInitScript(() => { delete window.__playwright__binding__; delete window.__pwInitScripts; });
await page.goto('https://abrahamjuliot.github.io/creepjs/');

Notes:

• Use --user-data-dir with a unique temporary folder to avoid conflicts with running Chromium instances
• Prefer --proxy-server or per-context proxies (ENT Tier1); auto timezone/locale detection applies in both cases
• Avoid framework-specific proxy/auth options (e.g., page.authenticate()), which disable BotBrowser's geo-detection and may leak location information

Examples: Playwright • Puppeteer

More options:

• Framework-less approach: --bot-script + CDP (privileged context, earlier hook, fewer artifacts)
• Docker: docker/README.md
• Full flags: CLI_FLAGS.md

Feature Reference

Configuration priority: CLI flags (highest) > Profile configs > defaults. Timezone, locale, and language auto-derive from your proxy IP.

Network & Proxy

| Feature | Reference | Guide | |---------|-----------|-------| | Proxy with embedded credentials (HTTP/SOCKS5/SOCKS5H) | Proxy Configuration | Guide | | Regex-based proxy routing rules | --proxy-bypass-rgx | Guide | | Per-context proxy with auto geo-detection | Per-Context Fingerprint | Guide | | Dynamic proxy switching at runtime | Dynamic Proxy Switching | Guide | | UDP over SOCKS5 (QUIC/STUN tunneling) | UDP over SOCKS5 | Guide | | Local DNS solver | --bot-local-dns | Guide | | Port protection for local services | --bot-port-protection | Guide | | WebRTC leak protection (SDP/ICE control) | WebRTC Leak Protection | Guide |

Fingerprint & Rendering

| Feature | Reference | Guide | |---------|-----------|-------| | Canvas / WebGL / WebGPU deterministic noise | Multi-Layer Noise | Canvas · WebGL | | AudioContext noise calibration | Multi-Layer Noise | Guide | | Text metrics & ClientRects noise | Multi-Layer Noise | Guide | | Deterministic noise seeds (reproducible per-tenant) | --bot-noise-seed | Guide | | Performance timing protection (27 browser operations) | Performance Timing Protection | Guide | | Stack depth fingerprint control (main/Worker/WASM) | Stack Depth Control | Guide | | Network information privacy (rtt/downlink/effectiveType) | [Network Info