BotBrowser is a cross-platform browser designed to evaluate and minimize automation artifacts compared to CDP-based tools, supporting authorized testing and compatibility analysis.
- 🎭 High-fidelity Profile Simulation - Synthetic/aggregated profiles for realistic, policy-compliant testing
- 🔄 Latest Chromium Base - Always synced to newest stable Chrome for zero fingerprint drift
- ⚡ Zero-Config Intelligence - Auto-detects timezone/locale/language from IP
- 🤖 Advanced Programmatic Control - Playwright/Puppeteer integration with CDP leak blocking
Research capability: Profile compatibility across different host systems (Windows, macOS, Android) for comparative studies.
Automatic touch simulation, device metrics, and consistent fingerprint rendering - minimal artifacts in headless mode.
Desktop → Android Test Results:
▶️ CreepJS Test - Desktop simulation of Android fingerprint▶️ Iphey Test - Complete mobile device simulation▶️ Pixelscan Test - Cross-platform compatibility demonstration
BotBrowser provides sophisticated browser fingerprint consistency testing through multiple layers of emulation and control:
🔧 Configuration & Control
- 21+
--bot-config-*flags - Override browser brand, WebGL, timezone, etc. - Session Management - Custom titles, cookies, bookmarks with
--bot-title - Advanced Proxy Auth - Direct credentials:
--proxy-server="http://user:pass@proxy.com:8080"
🎭 Automation Research
- Multi-Layer Noise Injection - Canvas, WebGL, Audio with per-session consistency
- CDP Leak Blocking - Complete Chrome DevTools Protocol artifact elimination
- Chrome Behavior Emulation - Google
X-Browser-*headers, Widevine CDM support
📱 Cross-Platform Emulation
- Built-in Font Engines - Windows/macOS/Android fonts with HarfBuzz text shaping
- Perfect Consistency - macOS profile works on Ubuntu, Android emulation on desktop
- Hardware Control - CPU architecture, screen metrics, authentic device behavior
⚡ Deep System Integration
- Precise FPS Simulation - Emulate 120 FPS macOS behavior on Ubuntu hosts
- Performance Controls - Memory allocation timing, IndexedDB latency tuning
- GPU Micro-Benchmarks - Vendor-specific behavior patterns, computation curves
| Category | Sample Capabilities |
|---|---|
| Graphics | Canvas/WebGL noise, GPU micro-benchmarks, texture hash spoofing |
| Network | WebRTC SDP manipulation, proxy auth, connection spoofing |
| Platform | Font fallback chains, cross-worker consistency, OS-specific features |
| Performance | FPS simulation, memory timing, animation frame delays |
📖 Complete Advanced Features Documentation →
Step 1: Download from Releases and a profile from profiles directory.
Step 2: Launch BotBrowser with your profile (
Windows (CMD):
chrome.exe --no-sandbox --bot-profile="C:\\absolute\\path\\to\\chrome139_win11_x64.enc" --user-data-dir="%TEMP%\\botprofile_%RANDOM%"macOS:
/Applications/Chromium.app/Contents/MacOS/Chromium \
--no-sandbox \
--user-data-dir="$(mktemp -d)" \
--bot-profile="/absolute/path/to/chrome139_win11_x64.enc"Ubuntu:
chromium-browser \
--no-sandbox \
--user-data-dir="$(mktemp -d)" \
--bot-profile="/absolute/path/to/chrome139_win11_x64.enc"Step 3: Browse normally - timezone, locale, and languages are automatically configured!
📖 Complete Installation Guide → - Detailed setup, Docker deployment, troubleshooting
Playwright / Puppeteer Automation
Available Examples:
- Node.js: Playwright | Puppeteer
- Python: Playwright
- .NET: Playwright
- Java: Playwright
const browser = await chromium.launch({
headless: true,
executablePath: BOTBROWSER_EXEC_PATH, // Absolute path to the BotBrowser executable
args: [
`--bot-profile=${BOT_PROFILE_PATH}`, // Absolute path to the bot profile
'--proxy-server="socks5://usr:pwd@127.0.0.1:8989"', // or: "http://usr:pwd@127.0.0.1:8989"
],
});
const page = await browser.newPage();
// Remove Playwright's bindings to avoid detection.
await page.addInitScript(() => {
delete window.__playwright__binding__;
delete window.__pwInitScripts;
});
await page.goto("https://abrahamjuliot.github.io/creepjs/");Important Notes:
- Use
--user-data-dirwith a unique temporary folder to avoid conflicts with running Chromium instances - Use
--proxy-serverto connect to proxy servers, supported protocols: HTTP, HTTPS, SOCKS5 ⚠️ Proxy Configuration: When using automation frameworks, always use--proxy-serverflag instead of framework-specific proxy options (likepage.authenticate()orproxyparameter inlaunch()). This ensures BotBrowser can retrieve geo information for accurate timezone/locale auto-configuration
📖 For a complete list of BotBrowser-specific CLI flags, see ⚙️ CLI Flags Reference
Native BotBrowser automation using privileged JavaScript context with chrome.debugger API access:
chrome.exe --no-sandbox --bot-profile="/absolute/path/to/profile.enc" --bot-script="automation.js"Key advantages:
- No framework dependencies - Pure Chrome DevTools Protocol
- Earlier intervention - Execute before page navigation
- Privileged context - Full
chrome.debuggerAPI access - Reduced detection surface - No Playwright/Puppeteer artifacts
📖 Examples: Bot Script Automation
For containerized deployment, see docker/README.md for complete setup guide.
📢 BotBrowser combines synthetic/aggregated profiles with flexible configuration for authorized research. Profile consistency and CLI settings enable comparative analysis.
- Profile Foundation: Synthetic/aggregated profiles provide realistic fingerprint data for authorized testing
- CLI Flexibility: Override profile settings at runtime without modifying encrypted files
- Cross-Platform Compatibility: 🔥 A macOS profile works on Ubuntu; a Windows profile works on macOS; an Android profile can be fully emulated on any OS
- Auto-Configuration: Timezone, locale, and languages automatically detected from IP/proxy
- CLI Flags: See the ⚙️ CLI flags reference - Recommended for most users
- Profile Settings: See the 📚 profile-configs guide - Advanced configuration
# Keep profile integrity, override only what you need (use absolute path)
chrome.exe --bot-profile="C:\\absolute\\path\\to\\authentic_user.enc" \
--proxy-server="http://user:pass@proxy.com:8080" \
--bot-title="Session-A"
# Same profile, different runtime settings
chrome.exe --bot-profile="C:\\absolute\\path\\to\\authentic_user.enc" \
--proxy-server="socks5://user:pass@proxy2.com:1080" \
--bot-title="Session-B"
⚠️ Note: This project must only be used in environments you own or where you have explicit authorization. Use against third-party services without permission is strictly prohibited.
For users who prefer a graphical interface, BotBrowserConsole provides a user-friendly way to manage BotBrowser:
Features:
- ✅ Select profiles and start browsing without command line
- ✅ Launch multiple browser instances easily
- ✅ Manage different environments and accounts
- ✅ Perfect for non-technical users
| Issue | Platform | Solution |
|---|---|---|
| STATUS_ACCESS_VIOLATION | Windows | Add --no-sandbox flag when launching |
| "Chromium" is damaged | macOS | Run xattr -rd com.apple.quarantine /Applications/Chromium.app |
| Missing dependencies | Ubuntu | Run sudo apt-get install -f |
| Profile file permission errors | All | Ensure .enc file has read permissions (chmod 644) |
| BotBrowser won't start or crashes | All | Check that your OS and Chromium version match the build; update BotBrowser to the latest release |
Our compatibility research examines browser fingerprinting techniques across different client configurations to improve web compatibility and understand fingerprint consistency.
Performance Metrics:
- ✅ Overall Consistency Rate: 99.7% (50,000+ test sessions)
- ✅ Detection Resistance: 96.8% across automated systems
Anti-Bot Systems:
| Service | Technology | Results |
|---|---|---|
| Cloudflare | Turnstile, Bot Management | |
| DataDome | ML-based detection | |
| PerimeterX | Behavioral analysis |
Fingerprinting Systems:
| Service | Focus | Results |
|---|---|---|
| CreepJS | Comprehensive fingerprinting | |
| FingerprintJS Pro | Commercial fingerprinting | |
| Pixelscan | Detection suite |
- Windows Profile on macOS: ✅ Perfect fingerprint consistency
- Android Emulation on Desktop: ✅ Complete mobile API simulation
- Headless vs GUI Mode: ✅ Identical fingerprint stability
📖 Complete Validation Results & Research Data → - 25+ anti-bot systems, 15+ fingerprinting tools, statistical analysis
⚠️ Ethical Use Policy: Use only in authorized research environments, educational institutions, or systems you own. Unauthorized use against third-party services is prohibited.
| Document | Description | Content Preview |
|---|---|---|
| Installation Guide | Platform-specific setup | Windows/macOS/Ubuntu guides, Docker deployment, troubleshooting |
| Advanced Features | Technical capabilities | 21+ CLI flags, noise injection, GPU micro-benchmarks |
| Validation Results | Research data | 25+ anti-bot systems, 50,000+ test sessions, statistical analysis |
| CLI Flags Reference | Command-line options | --bot-config-* flags, proxy auth, session management |
| Profile Configuration | Profile customization | Fingerprint control, cross-platform compatibility |
| Examples | Code samples | Playwright, Puppeteer, bot-script automation |
Framework Integration:
- Playwright Examples - TypeScript/Python integration
- Puppeteer Examples - JavaScript automation
- Bot-Script Examples - Framework-less
chrome.debuggerAPI
Profile Management:
- Demo profiles available in profiles/ directory
- Premium profiles: Contact botbrowser@bk.ru
| Contact Method | Best For | Link |
|---|---|---|
| Technical questions, source code access | botbrowser@bk.ru | |
| 📱 Telegram | Quick support, community | @botbrowser_support |
For advanced users who want to build BotBrowser from source:
- Requirements: Linux build environment, Chromium build tools
- Source Access: Available to qualified researchers and institutions
Contact botbrowser@bk.ru for source code access and compilation instructions.
BotBrowser is designed for academic research, security analysis, and authorized testing environments that comply with all applicable laws, regulations, and institutional ethics guidelines.
Authorized Use Cases:
- University and institutional research projects
- Security research in controlled environments
- Browser compatibility studies
- Fingerprint consistency analysis
- Authorized penetration testing
Prohibited Uses:
- Misuse to violate terms of service of third-party websites
- Unauthorized access to systems you do not own
- Commercial exploitation without proper licensing
- Any illegal activities or policy violations
Research Ethics: All users must obtain proper institutional approval and follow ethical research guidelines when conducting studies involving web services or user data.
GitHub Policy Compliance: This repository is not intended for production use against third-party services. Any misuse will result in violation of GitHub's Acceptable Use Policies.
