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
- Advanced CLI Configuration -
20+ --bot-config-*flags override key fingerprint properties at startup - Session Management - Custom
--bot-title,--bot-cookies,--bot-bookmarkswith toolbar labels - Advanced Proxy Authentication - Embed username:password directly in proxy URLs (http://user:pass@proxy.com:8080)
- Multi-Layer Noise Injection - Canvas, WebGL, Audio, TextMetrics with stabilized algorithms to ensure consistency
- Headless & Incognito Compatibility - Consistent behavior across browser modes with GPU simulation
- WebRTC Leak Protection - Complete IPv4/IPv6 SDP spoofing, candidate manipulation
- Chrome Behavior Emulation - Google
X-Browser-*headers, Widevine CDM, Chrome-specific APIs
This project does not distribute proprietary modules (e.g., Widevine). Any playback components must be obtained via official channels by the end user.
- Cross-Platform Font Engine - Built-in Windows/macOS/Android fonts and emojis, authentic rendering on any host system
- Cross-Platform Consistency - Eliminates platform-specific rendering differences, perfect emulation across Windows/macOS/Linux hosts
- Hardware Fingerprint Control - CPU architecture, screen metrics, device pixel ratios, authentic device behavior
- GPU Driver Micro-Benchmarks - Precision timing emulation, vendor-specific behavior patterns, authentic computation curves
- Advanced Text Rendering - HarfBuzz text shaping, Skia anti-aliasing integration, multi-language support (CJK/RTL/emoji)
- Dynamic Blink Features - Runtime OS-based feature loading (Windows/macOS/Android)
| Category | Capabilities |
|---|---|
| Browser & OS | Version, userAgentData, brands, full version override, debugger disabling, CDP leak blocking, Windows/macOS/Android emulation, built-in cross-platform fonts, Blink features |
| Location & Time | Timezone, geolocation |
| Display & UI | Screen properties, window dimensions, matchMedia, UI/system colors |
| Input & Navigation | Keyboard layouts (profile/real), touch simulation, mouse patterns, languages, plugins, permissions, battery, MimeTypes |
| Graphics & Rendering | Canvas/WebGL/WebGPU noise, precision GPU micro-benchmarks, driver-specific behavior emulation, HarfBuzz text shaping, cross-platform fonts/emojis, TextMetrics noise, client/text rects, emoji rendering, Unicode |
| Network & Media | Proxy auth, WebRTC SDP manipulation, Google headers, connection spoofing, MediaDevices, AudioContext, speech voices, speech synthesis, codec emulation |
Get the BotBrowser installer for your OS from the Releases page.
- Extract the downloaded
.7zarchive - Run
chrome.exefrom the extracted folder - If you encounter
STATUS_ACCESS_VIOLATION, launch with --no-sandbox
- Open the downloaded
.dmgfile - Drag
Chromium.appinto your Applications folder or any desired location - If you see the error:
Run:
"Chromium" is damaged and can't be openedxattr -rd com.apple.quarantine /Applications/Chromium.app
- Install via
dpkg:sudo dpkg -i botbrowser_<version>_amd64.deb
- If dependencies are missing, run:
sudo apt-get install -f
Get started in 3 simple steps:
Step 1: Download a profile from the profiles directory.
Step 2: Launch BotBrowser with your profile:
Windows (CMD):
chrome.exe --no-sandbox --bot-profile="C:\\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="/path/to/chrome139_win11_x64.enc"Ubuntu:
chromium-browser \
--no-sandbox \
--user-data-dir="$(mktemp -d)" \
--bot-profile="/path/to/chrome139_win11_x64.enc"Step 3: Browse normally - timezone, locale, and languages are automatically configured!
2. 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 or relative 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
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
chrome.exe --bot-profile="authentic_user.enc" \
--proxy-server="http://user:pass@proxy.com:8080" \
--bot-title="Session-A"
# Same profile, different runtime settings
chrome.exe --bot-profile="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 | Solution |
|---|---|
| "Chromium" is damaged (macOS) | Run xattr -rd com.apple.quarantine /Applications/Chromium.app |
| STATUS_ACCESS_VIOLATION (Windows) | Add --no-sandbox flag when launching |
| Profile file permission errors | Ensure .enc file has read permissions (chmod 644) |
| BotBrowser won't start or crashes | Check that your OS and Chromium version match the build; update BotBrowser to the latest release |
These demonstrations are provided for security research, academic analysis, and compatibility testing in authorized environments only. Any use outside of authorized research is strictly prohibited.
Our compatibility research examines browser fingerprinting techniques across different client configurations to improve web compatibility and understand fingerprint consistency.
The following studies examine browser compatibility across different web platforms for academic analysis:
| Research Target | Compatibility Study | Analysis Results |
|---|---|---|
| Nike | F5 Shape Security | ✔️ Consistent behavior observed |
| Generic Antibot | ✔️ Consistent behavior observed |
|
| TikTok | TiktokVM | ✔️ Consistent behavior observed |
| Walmart | PerimeterX | ✔️ Consistent behavior observed |
| Temu | F5 Shape Security | ✔️ Consistent behavior observed |
| Generic Antibot | ✔️ Consistent behavior observed | |
| TicketMaster | PerimeterX, FingerprintJS, reCAPTCHA | ✔️ Consistent behavior observed |
| Shein | F5 Shape Security, FingerprintJS, Forter | ✔️ Consistent behavior observed |
| FunCaptcha, reCAPTCHA | ✔️ Consistent behavior observed | |
| Bet365 | Generic Antibot | ✔️ Consistent behavior observed |
⚠️ Ethical Use Policy: Use only in authorized research environments, educational institutions, or systems you own. Unauthorized use against third-party services is prohibited.
We do not provide the private key required to generate new profiles. If you need additional profiles, please contact us directly. We maintain a large set of synthetic and aggregated profiles for testing. These profiles do not contain personal or identifying data.
Contact Information:
| Contact Method | Link |
|---|---|
| botbrowser@bk.ru | |
| 📱 Telegram | @botbrowser_support |
If you wish to compile your own version of Chromium with our modifications, follow the instructions provided here.
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.