BotBrowser Profile Configuration Guide

For Fingerprint Protection and Privacy Research.

This guide explains BotBrowser’s fingerprint-customization system that prevents tracking system fingerprint collection. Configure synthetic profiles and use dynamic CLI overrides for authorized privacy testing.

⚠️ Usage Policy: This configuration system is designed for fingerprint protection, privacy research, and authorized analysis only. Use in compliance with institutional policies and applicable laws.

CLI-First Configuration: Use --bot-config-* flags for runtime fingerprint control without editing encrypted profiles. These carry the highest priority.

Smart Configuration: BotBrowser intelligently derives timezone, locale, and languages from proxy IP. Override only when your scenario requires it.

Data Privacy: Profiles use synthetic/aggregated configurations to prevent tracking. BotBrowser does not enable fingerprint collection or tracking system data linkage. Use CLI overrides to keep profiles intact while customizing behavior.

Table of Contents

• Configuration Priority System
• Important: Profile Data Integrity
• How to Apply Configuration
• Configurable Fields
• Example Profile configs Block
• Important Notes
• Best Practices

Configuration Priority System

BotBrowser uses a three-tier priority system for configuration:

Priority Order (Highest to Lowest)

1. CLI --bot-config-* flags - Highest priority, overrides everything
2. Profile configs settings - Medium priority, overrides profile defaults
3. Profile default values - Lowest priority, built-in profile data

Why CLI Flags Are Recommended

• Highest Priority: Always takes precedence over profile settings
• No Profile Editing: Avoid modifying complex encrypted profile files
• Dynamic Configuration: Perfect for testing and different environments
• Session Isolation: Different settings per browser instance without conflicts

Example:

# Use CLI flags to override profile settings dynamically (timezone/locale auto-detected)
chromium-browser \
  --bot-profile="/absolute/path/to/profile.enc" \
  --bot-config-browser-brand="edge" \  # ENT Tier2 feature
  --bot-config-brand-full-version="142.0.3595.65"  # ENT Tier2 feature

Complete CLI flags reference: CLI Flags Reference

Important: Profile Data Integrity

Profile data uses synthetic/aggregated configurations. Unless you are certain about the impact, avoid overriding fingerprint properties because defaults provide the most protected behavior.

How to Apply Configuration

All configurations are embedded in the configs field inside your profile JSON structure.

File-Based Configuration Only

Important: BotBrowser only accepts profile input as a file. Shell piping (e.g., --bot-profile=<(echo '{"x": 1}')) is not supported due to CLI argument length and file-descriptor limits.

Best Practice:

1. Build your profile JSON dynamically in your code
2. Write it to a temporary file (e.g., /tmp/myprofile.json)
3. Pass the path to --bot-profile
4. Delete the file afterward if needed

Configurable Fields

General Settings

Custom User-Agent (ENT Tier3)

Full control over User-Agent string and userAgentData for building any browser identity.

These fields work together with --user-agent CLI flag. BotBrowser auto-generates matching navigator.userAgentData (brands, fullVersionList with GREASE) and all Sec-CH-UA-* headers. Values stay consistent across main thread, workers, and HTTP requests.

Proxy Settings

Better Approach: Use CLI flags for proxy configuration:

# Embedded credentials (recommended)
--proxy-server=http://username:password@proxy.example.com:8080
# SOCKS5H for tunnel-based hostname resolution
--proxy-server=socks5h://username:password@proxy.example.com:1080

For complete CLI flags documentation, see CLI Flags Reference

⚠️ Important: When using frameworks (Puppeteer/Playwright), always use CLI flags like --proxy-server instead of framework-specific proxy options (like page.authenticate() or proxy parameter in launch()). This ensures BotBrowser can retrieve geo information from proxy IP for accurate timezone/locale configuration.

⚠️ Proxy configurations are intended for authorized networks only. They must not be used for unauthorized data collection or abuse.

UDP-over-SOCKS5: ENT Tier3 support detects when a SOCKS5 upstream offers UDP associate and natively tunnels QUIC/STUN through it. No additional flag is required; simply provide a SOCKS5 proxy that advertises UDP support.

HTTP Request Settings

Window & Screen Settings

Engine & Device Simulation

Noise Toggles

Timing & Deterministic Noise Controls

Example Profile configs Block

{
  "configs": {
    // Browser locale (auto = derived from proxy IP and language settings)
    "locale": "auto",
 
    // Accept-Language header values (auto = IP-based detection)
    "languages": "auto",
 
    // Color scheme: 'light' or 'dark'
    "colorScheme": "light",
 
    // Proxy settings: hostname:port, with optional basic auth
    "proxy": {
      "server": "1.2.3.4:8080",
      "ip": "1.2.3.4"
    },
 
    // Disable GUI scaling based on device scale factor (ignore DevicePixelRatio for UI scaling)
    "disableDeviceScaleFactorOnGUI": false,
 
    // timezone: 'auto' = based on IP; 'real' = system timezone; any other string = custom
    "timezone": "auto",
 
    // location: 'auto' = based on IP; 'real' = system (GPS) location;
    // object = custom coordinates
    "location": "auto", // or "real" or { latitude: 48.8566, longitude: 2.3522 }
 
    // window: 'profile' = use profile’s dimensions;
    // 'real' = use system window size;
    // object = custom dimensions
    "window": "profile", // or "real" or { innerWidth: 1280, innerHeight: 720, outerWidth: 1280, outerHeight: 760, screenX: 100, screenY: 50, devicePixelRatio: 1 }
 
    // screen: 'profile' = use profile’s screen metrics;
    // 'real' = use system screen metrics;
    // object = custom metrics
    "screen": "profile", // or "real" or { width: 1280, height: 720, colorDepth: 24, pixelDepth: 24 }
 
    // WebRTC: 'profile' = profile’s settings; 'real' = native; 'disabled' = no WebRTC
    "webrtc": "profile",
 
    // WebRTC ICE servers: 'google' preset or 'custom:stun:...,turn:...'
    "webrtcICE": "google",
 
    // Keep the window active even when unfocused (suppresses blur/visibilitychange)
    "alwaysActive": true,
 
    // Fonts: 'profile' = profile’s embedded list; 'expand' = fill gaps with system fonts; 'real' = system-installed fonts
    "fonts": "profile",
 
    // WebGL: 'profile' = profile’s parameters; 'real' = system implementation; 'disabled' = off
    "webgl": "profile",
 
    // WebGPU: same semantics as WebGL
    "webgpu": "profile",
 
    // Media devices: 'profile' = synthetic camera/mic devices; 'real' = actual system devices
    "mediaDevices": "profile",
 
    // Media types: 'expand' = prefer local decoders; switch to 'profile' for legacy behavior
    "mediaTypes": "expand",
 
    // Speech voices: 'profile' = profile’s synthetic voices; 'real' = system voices
    "speechVoices": "profile",
 
    // noiseCanvas: Introduce controlled variance to Canvas for fingerprint protection
    "noiseCanvas": true,
 
    // noiseWebglImage: Introduce controlled variance to WebGL for fingerprint protection
    "noiseWebglImage": true,
 
    // noiseAudioContext: Introduce controlled variance to AudioContext for fingerprint protection
    "noiseAudioContext": true,
 
    // noiseClientRects: Introduce controlled variance to client rects for fingerprint protection
    "noiseClientRects": false,
 
    // noiseTextRects: Introduce controlled variance to TextRects for fingerprint protection
    "noiseTextRects": true,
 
    // browserBrand: override for `navigator.userAgentData.brands` and related UA fields. Supports "chromium", "chrome", "edge", "brave", "opera", "webview" (ENT Tier3)
    "browserBrand": "chrome",
 
    // brandFullVersion: optional brand-specific full version string for UA-CH tuples when the vendor’s cadence diverges
    "brandFullVersion": "142.0.3595.65",
 
    // injectRandomHistory: Adds synthetic navigation history for session authenticity
    // Accepts true (random 2-7 entries), a number (e.g. 15), or false
    "injectRandomHistory": false,
 
    // enableVariationsInContext (ENT Tier2): Include X-Client-Data headers in incognito contexts for Google domains
    "enableVariationsInContext": false,
 
    // disableDebugger: Prevents unintended interruptions from JavaScript debugger statements during fingerprint protection workflows
    "disableDebugger": true,
 
    // disableConsoleMessage: Suppress console.* output forwarded through CDP logging
    "disableConsoleMessage": true,
 
    // keyboard: choose keyboard fingerprint source: "profile" (emulated from profile) or "real" (use system keyboard)
    "keyboard": "profile",
 
    // mobileForceTouch: Force touch events on/off when simulating mobile devices
    "mobileForceTouch": false,
 
    // portProtection (PRO): Protect local service ports (VNC, RDP, etc.) from being scanned
    "portProtection": false,
 
    // customHeaders (PRO): inject custom HTTP headers into all outgoing requests
    "customHeaders": {
      "X-Custom-Header": "value"
    },
 
    // timeSeed (ENT Tier2): deterministic execution timing diversity
    "timeSeed": 42,
 
    // stackSeed (ENT Tier2): "profile", "real", or positive integer seed
    "stackSeed": "profile",
 
    // networkInfoOverride: use profile-defined navigator.connection values
    "networkInfoOverride": true,
 
    // fps (ENT Tier2): frame rate control: "profile", "real", or a number (e.g., 60)
    "fps": "profile"
  }
}
 
 

⚠️ Open the .enc file and place the configs block before the key block, keeping the entire file in JSON format:

⚠️ Your modified .enc profile should have this structure:

{
  "configs": {
    // ...
  },
  "key": {
    // ...
  },
  "version": {
    // ...
  },
  "profile": {
    // ...
  }
}

Important Notes

Configuration Behavior

• Profile data uses synthetic/aggregated configurations; change only if necessary and you understand the impact.
• All string fields support multi-purpose values: string literal (auto, real, or custom), or object schema when more parameters are needed.
• If a field is omitted, BotBrowser uses profile defaults where appropriate.
• CLI --bot-config-* flags override profile configs with the highest priority
• uaFullVersion Tip: When JavaScript calls navigator.userAgentData.fullVersion, BotBrowser replaces the default value with this field. Ensure the full version matches the Chromium major version (e.g., Chromium 138 → full version starts with “138.”). See https://chromiumdash.appspot.com/releases .
• brandFullVersion Tip: Pair this with browserBrand when mimicking Edge/Opera/Brave cadences so UA-CH tuples expose the vendor’s own full-version token instead of the Chromium one.

Best Practices

Related guides: Profile Management, Browser Brand Alignment, Noise Seed Reproducibility, Proxy Configuration

Fingerprint Protection

• Screen coordination: Always adjust window size and screen size together to avoid suspicious fingerprint gaps
• Geographic alignment: Match timezone and location to your proxy’s region to avoid fingerprint vulnerabilities
• Display accuracy: Set a realistic devicePixelRatio based on the system being emulated:
  • 2 for macOS Retina displays
  • 1 for standard monitors
  • 1.5 for some high-DPI Windows displays

Connection Security

• Proxy authentication: Always define proxy credentials if using authenticated proxies to avoid connection leaks
• Protocol parity: Ensure proxy protocol matches your network requirements

File Management

• Dynamic generation: If you’re generating a profile in code, save it as a temporary file (e.g., /tmp/myprofile.json) and pass the file path via --bot-profile
• Avoid piping: Never pipe large JSON blobs via echo, as this is unsupported and unstable

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