BotBrowser Advanced Features

Technical architecture and implementation details behind BotBrowser’s fingerprint protection. This document covers the design and capabilities of each subsystem. For configuration syntax and usage examples, see the CLI Flags Reference.

License tiers: Some capabilities show tier hints in parentheses (PRO, ENT Tier1/Tier2/Tier3); those options are subscription-gated.

Capabilities Index

navigator.webdriver removal, main-world isolation, JS hook isolation, Canvas noise, WebGL/WebGPU param control, Skia anti-alias, HarfBuzz shaping, MediaDevices protection, font list authenticity, UA congruence, custom User-Agent (ENT Tier3), per-context proxy (ENT Tier1) geo, DNS-through-proxy, active window emulation, HTTP headers/HTTP2/HTTP3, headless parity, WebRTC SDP/ICE control, TLS fingerprint (JA3/JARM), port protection (PRO), dynamic proxy switching (ENT Tier3), distributed privacy consistency, CDP quick reference

Configuration

BotBrowser offers three configuration interfaces with a clear priority order:

1. CLI --bot-config-* flags (highest priority): CLI Flags Reference
2. Profile configs JSON (medium priority): Profile Configuration Guide
3. CDP commands (runtime, per-context): Per-Context Fingerprint | CDP Quick Reference

Smart auto-configuration: timezone, locale, and languages derive from your proxy IP. Override only when your scenario requires it.

Network Fingerprint Control

Scope: Network-layer traits that tracking systems often score.

• HTTP Headers & Protocol: Chrome-like request headers; authentic HTTP/2 and HTTP/3 behavior (see Chrome Behavior Emulation).
• DNS Routing: SOCKS5 proxies route all lookups through the proxy tunnel, preventing local DNS leakage.
• UDP over SOCKS5 (ENT Tier3): Automatic UDP associate when supported to tunnel QUIC and STUN; ICE presets often unnecessary if UDP is available.
• WebRTC: SDP/ICE manipulation and candidate filtering to prevent local IP disclosure (see WebRTC Leak Protection).
• TLS Fingerprints (JA3/JARM/ALPN): Roadmap: cipher/extension ordering and ALPN tuning under evaluation.

Stack differentiators:

• Per-context proxies with proxy-based geo detection (timezone/locale/language) across contexts and sessions
• DNS-through-proxy plus credentialed proxy URLs keep browser-level geo signals protected
• UDP-over-SOCKS5 tunnel (ENT Tier3) for QUIC/STUN so ICE presets are only needed when UDP is unavailable
• Optional ICE control via --bot-webrtc-ice (ENT Tier1) when the proxy lacks UDP support
• Chromium-level implementation: tunneling lives inside the network stack, no external proxy-chain hijacking

Note: Many privacy-oriented browsers disable QUIC or skip UDP entirely. BotBrowser implements UDP-over-SOCKS5 directly inside Chromium’s network stack so QUIC/STUN stay proxied and consistent with TCP traffic.

For proxy configuration syntax and examples, see CLI Flags: Enhanced Proxy Configuration.

Related guides: Proxy Configuration · DNS Leak Prevention · UDP over SOCKS5 · WebRTC Leak Prevention · Port Protection · Dynamic Proxy Switching

Port Protection (PRO)

Protect local service ports (VNC, RDP, development servers, etc.) from being scanned by remote pages. Prevents detection of which services are running on localhost.

Covers 30 commonly-probed ports across:

• IPv4 loopback (127.0.0.0/8)
• IPv6 loopback (::1)
• localhost hostname

Enable via CLI (--bot-port-protection) or profile JSON (configs.portProtection). See CLI Flags for details.

Dynamic Per-Context Proxy Switching (ENT Tier3)

Switch proxy servers for a specific BrowserContext at runtime without restarting the context. Use the CDP command BotBrowser.setBrowserContextProxy to change proxies on the fly. Supports multiple switches per context, with automatic timezone and language adaptation after each switch.

const ctx = await browser.createBrowserContext();
const page = await ctx.newPage();
const client = await browser.target().createCDPSession(); // must use browser-level session
 
// Set initial proxy - US endpoint
await client.send('BotBrowser.setBrowserContextProxy', {
  browserContextId: ctx._contextId,
  proxyServer: 'socks5://user:pass@us-proxy.example.com:1080',
  proxyIp: '203.0.113.1'  // optional: skip IP lookup for faster geo detection
});
await page.goto('https://example.com');
 
// Switch to UK proxy with bypass rules
await client.send('BotBrowser.setBrowserContextProxy', {
  browserContextId: ctx._contextId,
  proxyServer: 'socks5h://user:pass@uk-proxy.example.com:1080',
  proxyBypassList: 'localhost;127.0.0.1',                  // standard bypass list
  proxyBypassRgx: 'cdn\\.example\\.com|/static/'          // regex bypass (RE2 syntax)
});
await page.goto('https://example.co.uk');

Supported protocols: socks5://, socks5h://, http://, https://, all with embedded authentication (user:pass@host:port).

Optional parameters:

• proxyIp: provides the proxy’s exit IP to skip automatic IP detection, resulting in faster geo-based timezone and language adaptation.
• proxyBypassList: semicolon-separated list of hosts/patterns that should bypass the proxy (e.g., localhost;*.internal.com).
• proxyBypassRgx: regex pattern (RE2 syntax) for URLs that should bypass the proxy. Supports | for multiple patterns (e.g., cdn\.example\.com|/api/health).

Privacy Protection & Fingerprint Consistency

Multi-Layer Fingerprint Noise

Deterministic noise generation prevents fingerprint collection while maintaining session consistency.

• Canvas: Controlled variance applied to Canvas 2D rendering
• WebGL image: Controlled variance applied to WebGL readback
• WebGPU: Deterministic noise applied to WebGPU canvases by default so GPU-only probes inherit the same reproducible noise characteristics
• AudioContext: Inaudible noise calibration (Chromium 141+) with cross-worker consistency
• ClientRects/TextRects: Realistic font measurement variance with cross-worker consistency
• Deterministic noise seeds (ENT Tier2): Reproducible yet distinct noise fields per tenant; each seed shapes Canvas 2D, WebGL, WebGPU imagery, text metrics, HarfBuzz layout, ClientRects, and offline audio hashes. See --bot-noise-seed

Protection model:

• Stable noise algorithms maintain session consistency while varying across different sessions
• GPU tuning preserves authentic WebGL and WebGPU behavior (1.0 and 2.0 contexts)
• Text metrics and ClientRects noise sustains realistic font measurements with cross-worker consistency

For noise configuration flags, see CLI Flags: Rendering, Noise & Media/RTC.

Related guides: Canvas · WebGL · Audio · Noise Seed Reproducibility · Font

Active Window Emulation

Maintains protected window state to prevent focus-based tracking even when the host window is unfocused.

• --bot-always-active (PRO, default true) maintains protected blur and visibilitychange event patterns, keeping document.hidden=false
• Protects against window-focus-based tracking heuristics that monitor caret blinking, FocusManager events, or inactive viewport throttling

Headless & Incognito Compatibility

Consistent behavior across execution modes.

GPU Simulation in Headless Mode (ENT Tier2):

• Full GPU context simulation without physical GPU
• WebGL and WebGPU rendering consistency
• Hardware-accelerated video decoding simulation
• Automatic GPU rendering backend selection on Linux via --bot-gpu-emulation. Detects and prefers system GPU/GL drivers when available, with shader caching enabled by default

Incognito-Mode Consistency:

• Fingerprint protection maintained in incognito mode
• Consistent fingerprint between normal and incognito modes
• X-Client-Data header consistency in incognito contexts via --bot-enable-variations-in-context (ENT Tier2)

WebRTC Leak Protection

Complete WebRTC fingerprint protection and network privacy.

SDP Control:

• IPv4 and IPv6 Session Description Protocol (SDP) standardization across platforms
• ICE candidate filtering and protection management
• STUN and TURN server response standardization

Real-Time Communication Privacy:

• MediaStream API protection across execution contexts
• RTCPeerConnection behavior standardization
• Network topology protection through controlled signal patterns
• ICE server presets and custom lists via --bot-webrtc-ice (ENT Tier1) to standardize STUN and TURN endpoints observed by page JavaScript
• Combined with UDP-over-SOCKS5 (ENT Tier3) for Chromium-level QUIC and STUN tunneling

Related guides: WebRTC Leak Prevention · Incognito Fingerprinting

Chrome Behavior Emulation

Consistent Chrome-compatible behaviors and standardized API responses.

Protocol Headers:

• Standard HTTP headers matching Chrome specifications
• Consistent HTTP/2 and HTTP/3 behavior across platforms
• Standardized request timing and protocol patterns

API Standardization:

• Chrome-compatible API implementations
• Standardized JavaScript API responses matching Chrome specifications

Widevine CDM Integration (ENT Tier2):

Note: BotBrowser does not distribute proprietary modules (e.g., Widevine). End users must obtain playback components via official channels.

Device & Platform Emulation

Deep System Integration

Performance Timing Protection (ENT Tier2): Every device has a unique “speed signature”: how fast it renders a Canvas path, compiles a WebGL shader, or measures a font. Tracking systems collect these execution times to build a hardware-level fingerprint. When multiple browser instances share the same hardware, their timing profiles are identical, making them vulnerable to correlation. --bot-time-seed=<integer> (valid range: 1–UINT32_MAX, 0 = disabled) protects each instance with its own stable performance profile across 27 browser operations. This also covers performance.getEntries(), performance.getEntriesByType("navigation"), and performance.timing with authentic per-session redistribution of resource and navigation timing values.

--bot-time-seed varies actual operation execution speeds (the workload). --bot-time-scale compresses performance.now() intervals globally (the clock). They protect against different tracking vectors and can be used together.

Stack Depth Fingerprint Control (ENT Tier2): JavaScript engines expose a measurable recursive call stack depth that varies by browser build, platform, and architecture. Tracking systems use this as a stable fingerprint signal. --bot-stack-seed controls stack depth across main thread, Worker, and WASM contexts. Accepts profile (match profile’s exact depth), real (use native depth), or a positive integer seed (1–UINT32_MAX) for per-session depth variation.

Network Information Privacy: navigator.connection properties (rtt, downlink, effectiveType, saveData) and corresponding Client Hints headers can reveal server-side network characteristics that contradict the profile’s geographic identity. Enable --bot-network-info-override or configs.networkInfoOverride to return profile-defined values.

CPU Core Scaling Protection: When navigator.hardwareConcurrency is set by the profile, Worker threads are automatically constrained to match the claimed core count via CPU affinity on Linux and Windows. This ensures parallel computation scaling curves align with the claimed value.

Related guides: Performance · Stack Depth · FPS Control · Navigator Properties

Complete Fingerprint Control

Integration with Automation Frameworks

Framework-Less Automation (--bot-script)

Execute JavaScript with privileged chrome.debugger access, with no framework dependencies.

• Earlier intervention. Execute before page navigation.
• Privileged context. Full chrome.debugger API access.
• Isolated execution. Framework artifacts do not appear in page context.

Documentation: Bot Script Examples  · Guide

Playwright/Puppeteer Integration

Privacy-preserving integration with popular frameworks.

• Prevents CDP artifacts from appearing in page context
• Maintains authentic browser behavior in all contexts
• Eliminates framework-specific fingerprint signatures
• ChromeDriver compatibility and Selenium Grid integration support

Related guides: Playwright · Puppeteer · Automation Consistency

Mirror: Distributed Privacy Consistency (ENT Tier3)

Verify that privacy protection works consistently across platforms and networks. Run a controller instance and multiple clients to ensure all instances maintain identical privacy defenses.

Complete Mirror documentation  including setup, CLI flags, CDP examples, and troubleshooting. See also the deployment guide.

Per-Context Fingerprint (ENT Tier3)

Assign independent fingerprint bundles per BrowserContext without spawning new browser processes. Each context can have its own profile, timezone, locale, noise seeds, and all other fingerprint parameters. Workers automatically inherit the parent context fingerprint.

Complete Per-Context Fingerprint documentation including CDP examples, supported flags, and use cases.

CDP Quick Reference

All commands live under the BotBrowser CDP domain. Send them through a browser-level CDP session (browser.target().createCDPSession() in Puppeteer, browser.newBrowserCDPSession() in Playwright). Page-level sessions (page.createCDPSession()) do not have access to this domain.

All BotBrowser CDP commands are browser-level only. Use browser.target().createCDPSession() (Puppeteer) or browser.newBrowserCDPSession() (Playwright).

Related Documentation

• CLI Flags Reference - Complete command-line options and usage examples
• Profile Configuration - Profile JSON field reference
• Installation Guide - Platform-specific setup
• Guides  - Step-by-step guides for proxy, fingerprint, identity, platform emulation, and deployment
• Per-Context Fingerprint - Independent fingerprint per BrowserContext
• Validation Results - Research and testing data
• Mirror  - Distributed privacy consistency verification
• CanvasLab  - Canvas 2D / WebGL / WebGL2 forensics and tracking analysis tool
• AudioLab  - Web Audio API forensics and audio fingerprint collection analysis tool
• Examples  - Playwright, Puppeteer, bot-script integration
• Main README  - Project overview and quick start

Legal Disclaimer & Terms of Use  • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.