Skip to content

Commit a68fafb

Browse files
MSTU0MSTU0
committed
docs: add WebGPU, media devices, CPU core scaling guides, fix stack depth format, GPU backend docs
1 parent 684241f commit a68fafb

8 files changed

Lines changed: 462 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ Examples: [Playwright](examples/playwright/) • [Puppeteer](examples/puppeteer/
144144
| Performance timing protection (27 browser operations) | [Performance Timing Protection](ADVANCED_FEATURES.md#performance-timing-protection) | [Guide](docs/guides/fingerprint/PERFORMANCE.md) |
145145
| Stack depth fingerprint control (main/Worker/WASM) | [Stack Depth Control](ADVANCED_FEATURES.md#stack-depth-control) | [Guide](docs/guides/fingerprint/STACK_DEPTH.md) |
146146
| Network information privacy (rtt/downlink/effectiveType) | [Network Info Privacy](ADVANCED_FEATURES.md#network-info-privacy) | [Guide](docs/guides/fingerprint/NAVIGATOR_PROPERTIES.md) |
147-
| CPU core scaling protection | [CPU Core Scaling](ADVANCED_FEATURES.md#cpu-core-scaling) | |
147+
| CPU core scaling protection | [CPU Core Scaling](ADVANCED_FEATURES.md#cpu-core-scaling) | [Guide](docs/guides/fingerprint/CPU_CORE_SCALING.md) |
148148
| Cross-platform font engine (Win/Mac/Android) | [Font Engine](ADVANCED_FEATURES.md#cross-platform-font-engine) | [Guide](docs/guides/fingerprint/FONT.md) |
149149
| GPU simulation on headless servers | [Headless Compatibility](ADVANCED_FEATURES.md#headless-incognito-compatibility) | [Guide](docs/guides/fingerprint/INCOGNITO.md) |
150150

‎docs/guides/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,9 @@ These guides cover everything from initial setup to advanced deployment scenario
6262
| [Incognito Fingerprinting](fingerprint/INCOGNITO.md) | Keep fingerprint surfaces consistent between regular and private browsing sessions. |
6363
| [Console Suppression](fingerprint/CONSOLE_SUPPRESSION.md) | Suppress CDP-forwarded console artifacts that can affect runtime consistency checks. |
6464
| [Active Window Emulation](fingerprint/ACTIVE_WINDOW.md) | Prevent focus-based tracking by keeping windows in an always-active state. |
65+
| [WebGPU Fingerprint Protection](fingerprint/WEBGPU.md) | Control WebGPU adapter information and rendering behavior across platforms. |
66+
| [Media Devices Privacy](fingerprint/MEDIA_DEVICES.md) | Control device enumeration to return consistent audio/video device lists. |
67+
| [CPU Core Scaling Protection](fingerprint/CPU_CORE_SCALING.md) | Constrain Worker parallelism to match the profile's claimed core count. |
6568

6669
<a id="identity-session"></a>
6770
## Identity and Session

‎docs/guides/deployment/PERFORMANCE_OPTIMIZATION.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ BotBrowser performance is influenced by several factors:
4949

5050
2. **Profile loading.** Each profile contains fingerprint data (fonts, GPU info, screen properties) that controls the browser's protected identity. Loading happens once at startup. Keeping profiles on fast local storage (SSD) reduces startup time.
5151

52-
3. **GPU rendering.** On servers without a physical GPU, BotBrowser uses SwiftShader (software rendering). This is slower than hardware GPU but provides consistent output. For tasks that do not require screenshots or visual rendering, this overhead is minimal.
52+
3. **GPU rendering.** On servers without a physical GPU, BotBrowser automatically selects the best available software rendering backend. If your system has GPU or GL drivers installed (e.g., Mesa on Linux), BotBrowser will use them for better performance. Otherwise it falls back to its built-in software renderer. You can control this with [`--bot-gpu-emulation`](../../../CLI_FLAGS.md#behavior--protection-toggles) (ENT Tier2).
5353

5454
4. **Browser contexts.** Creating multiple BrowserContexts within a single browser process is more efficient than launching separate browser instances. Each context can have its own fingerprint via Per-Context Fingerprint (ENT Tier3).
5555

@@ -159,6 +159,30 @@ Tips for reducing memory consumption:
159159
- **Limit concurrent pages.** Each tab consumes additional memory. Close pages you no longer need.
160160
- **Set container memory limits.** In Docker, use `--memory=2g` to prevent a single instance from consuming all host memory.
161161

162+
### GPU rendering backend on Linux
163+
164+
On headless Linux servers without a physical GPU, BotBrowser automatically detects and uses your system's GL drivers (e.g., Mesa GL drivers) when available. This typically delivers better performance than the built-in fallback renderer.
165+
166+
```bash
167+
# Default: BotBrowser auto-detects the best backend (recommended)
168+
chromium-browser \
169+
--headless \
170+
--bot-profile="/path/to/profile.enc" \
171+
--user-data-dir="$(mktemp -d)"
172+
173+
# If you have your own GPU or GL driver and want BotBrowser
174+
# to skip all rendering backend configuration:
175+
chromium-browser \
176+
--headless \
177+
--bot-profile="/path/to/profile.enc" \
178+
--bot-gpu-emulation=false \
179+
--user-data-dir="$(mktemp -d)"
180+
```
181+
182+
When `--bot-gpu-emulation=false` is set, BotBrowser does not configure any GPU rendering flags. Chrome's own GPU process handles backend selection. WebGL and Canvas fingerprint protection still work normally.
183+
184+
> **Note:** If you disable GPU emulation and your system has no GL drivers, WebGL may become unavailable. Ensure your environment provides GPU or GL support (e.g., `apt install mesa-utils libegl-mesa0 mesa-vulkan-drivers` on Debian/Ubuntu).
185+
162186
### Optimized browser flags for production
163187

164188
```bash
@@ -190,7 +214,7 @@ chromium-browser \
190214
| CPU spikes during idle | Disable background features: `--disable-background-networking`, `--disable-sync`. |
191215
| Slow screenshot capture | Ensure a virtual display is running on Linux. Consider reducing profile screen resolution for faster rendering. |
192216
| Profile loading takes too long | Store profiles on SSD, not network-mounted storage. Profile files are small but read on every startup. |
193-
| GPU process consuming CPU | Expected on servers using SwiftShader. This is software rendering. For CPU-sensitive workloads, consider a GPU-equipped server. |
217+
| GPU process consuming CPU | Install Mesa GL drivers (`apt install libegl-mesa0 mesa-utils`) for better software rendering performance. If your server has a GPU, set `--bot-gpu-emulation=false` to use it directly. |
194218

195219
---
196220

‎docs/guides/fingerprint/CPU_CORE_SCALING.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# CPU Core Scaling Protection
2+
3+
> BotBrowser constrains Worker thread parallelism to match the profile's `navigator.hardwareConcurrency`, keeping computation scaling consistent with the claimed core count.
4+
5+
---
6+
7+
<a id="prerequisites"></a>
8+
9+
## Prerequisites
10+
11+
- **BotBrowser** installed. See [Installation Guide](../../../INSTALLATION.md).
12+
- **A profile file** (`.enc` for production).
13+
14+
---
15+
16+
<a id="overview"></a>
17+
18+
## Overview
19+
20+
`navigator.hardwareConcurrency` tells JavaScript how many CPU cores are available. Tracking systems can verify this value by measuring actual parallel computation speed. If a profile claims 4 cores but the host has 16, Worker-based benchmarks will complete faster than expected for a 4-core machine.
21+
22+
BotBrowser solves this by constraining Worker threads to match the profile's claimed core count via CPU affinity on Linux and Windows. The computation scaling curve aligns with the reported value.
23+
24+
---
25+
26+
<a id="quick-start"></a>
27+
28+
## Quick Start
29+
30+
```bash
31+
# Profile defines hardwareConcurrency. Workers are automatically constrained.
32+
chromium-browser \
33+
--bot-profile="/path/to/profile.enc" \
34+
--user-data-dir="$(mktemp -d)"
35+
```
36+
37+
No extra flags needed. When the profile sets `navigator.hardwareConcurrency`, BotBrowser automatically applies CPU affinity to Worker threads.
38+
39+
---
40+
41+
<a id="how-it-works"></a>
42+
43+
## How It Works
44+
45+
1. **Profile sets the value.** The profile defines `navigator.hardwareConcurrency` (e.g., 4 cores).
46+
47+
2. **Workers are constrained.** When a Worker, SharedWorker, or ServiceWorker is created, BotBrowser pins it to a subset of physical cores matching the claimed count.
48+
49+
3. **Computation scales correctly.** A parallel benchmark using 4 Workers on a "4-core" profile will show the same scaling behavior as a real 4-core machine, even if the host has more cores.
50+
51+
---
52+
53+
<a id="common-scenarios"></a>
54+
55+
## Common Scenarios
56+
57+
### High-core server running low-core profiles
58+
59+
A 32-core server running a mobile profile (4 cores) will constrain all Workers to 4 physical cores:
60+
61+
```javascript
62+
const browser = await chromium.launch({
63+
executablePath: process.env.BOTBROWSER_EXEC_PATH,
64+
headless: true,
65+
args: [
66+
"--bot-profile=/path/to/mobile-profile.enc",
67+
],
68+
});
69+
70+
const page = await browser.newPage();
71+
const cores = await page.evaluate(() => navigator.hardwareConcurrency);
72+
console.log(cores); // 4 (from profile)
73+
// Worker-based parallel benchmarks will show 4-core scaling behavior
74+
await browser.close();
75+
```
76+
77+
### Multiple profiles on same host
78+
79+
Each browser instance is constrained independently based on its profile. A 4-core profile and an 8-core profile on the same 32-core server show different computation scaling curves matching their respective claims.
80+
81+
---
82+
83+
<a id="platform-support"></a>
84+
85+
## Platform Support
86+
87+
| Platform | CPU Affinity | Notes |
88+
|----------|-------------|-------|
89+
| **Linux** | Supported | Uses CPU affinity to pin Worker threads |
90+
| **Windows** | Supported | Uses CPU affinity to pin Worker threads |
91+
| **macOS** | Not supported | macOS does not expose CPU affinity APIs. Workers run on all cores. `navigator.hardwareConcurrency` is still set from the profile, but parallel timing may not match. |
92+
93+
---
94+
95+
<a id="troubleshooting"></a>
96+
97+
## Troubleshooting / FAQ
98+
99+
| Problem | Solution |
100+
|---------|----------|
101+
| `hardwareConcurrency` shows wrong value | Ensure your profile contains the correct core count. The value comes from the profile, not from a CLI flag. |
102+
| Parallel benchmark still fast on macOS | macOS does not support CPU affinity. Consider running on Linux for full protection. |
103+
| Workers seem slow | Expected when the profile claims fewer cores than the host. Workers are intentionally constrained. |
104+
105+
---
106+
107+
<a id="next-steps"></a>
108+
109+
## Next Steps
110+
111+
- [Performance Optimization](../deployment/PERFORMANCE_OPTIMIZATION.md). Tune throughput on multi-core servers.
112+
- [Navigator Properties](NAVIGATOR_PROPERTIES.md). Other navigator-level fingerprint surfaces.
113+
- [Stack Depth Protection](STACK_DEPTH.md). Control JavaScript recursive stack depth.
114+
- [CLI Flags Reference](../../../CLI_FLAGS.md). Complete flag documentation.
115+
116+
---
117+
118+
**Related documentation:** [Advanced Features: CPU Core Scaling](../../../ADVANCED_FEATURES.md#cpu-core-scaling) | [CLI Flags](../../../CLI_FLAGS.md)
119+
120+
---
121+
122+
**[Legal Disclaimer & Terms of Use](https://github.com/botswin/BotBrowser/blob/main/DISCLAIMER.md) • [Responsible Use Guidelines](https://github.com/botswin/BotBrowser/blob/main/RESPONSIBLE_USE.md)**. BotBrowser is for authorized fingerprint protection and privacy research only.

‎docs/guides/fingerprint/MEDIA_DEVICES.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Media Devices Privacy
2+
3+
> Control how `navigator.mediaDevices.enumerateDevices()` reports audio and video devices with `--bot-config-media-devices`.
4+
5+
---
6+
7+
<a id="prerequisites"></a>
8+
9+
## Prerequisites
10+
11+
- **BotBrowser** installed. See [Installation Guide](../../../INSTALLATION.md).
12+
- **A profile file** (`.enc` for production).
13+
14+
---
15+
16+
<a id="overview"></a>
17+
18+
## Overview
19+
20+
`navigator.mediaDevices.enumerateDevices()` returns a list of available audio and video input/output devices. The number, names, and IDs of these devices vary by system and can be used as a fingerprint signal. BotBrowser controls the device list to return consistent results regardless of the host machine's actual hardware.
21+
22+
---
23+
24+
<a id="quick-start"></a>
25+
26+
## Quick Start
27+
28+
```bash
29+
# Default: use profile-defined device list (recommended)
30+
chromium-browser \
31+
--bot-profile="/path/to/profile.enc" \
32+
--user-data-dir="$(mktemp -d)"
33+
```
34+
35+
By default, BotBrowser returns the profile's device list. No extra flags needed.
36+
37+
---
38+
39+
<a id="configuration"></a>
40+
41+
## Configuration
42+
43+
The `--bot-config-media-devices` flag controls device enumeration:
44+
45+
| Value | Behavior |
46+
|-------|----------|
47+
| `profile` (default) | Return profile-defined devices. The device list matches the target platform regardless of host hardware. |
48+
| `real` | Use the host system's actual devices. Useful for development or when you need real audio/video capture. |
49+
50+
```bash
51+
# Use profile devices (default)
52+
chromium-browser \
53+
--bot-profile="/path/to/profile.enc" \
54+
--bot-config-media-devices=profile
55+
56+
# Use host system devices
57+
chromium-browser \
58+
--bot-profile="/path/to/profile.enc" \
59+
--bot-config-media-devices=real
60+
```
61+
62+
---
63+
64+
<a id="common-scenarios"></a>
65+
66+
## Common Scenarios
67+
68+
### Consistent device count across servers
69+
70+
Different servers have different audio hardware (or none). With `profile` mode, every instance reports the same device list:
71+
72+
```javascript
73+
const browser = await chromium.launch({
74+
executablePath: process.env.BOTBROWSER_EXEC_PATH,
75+
headless: true,
76+
args: [
77+
"--bot-profile=/path/to/profile.enc",
78+
],
79+
});
80+
81+
const page = await browser.newPage();
82+
const devices = await page.evaluate(async () => {
83+
const list = await navigator.mediaDevices.enumerateDevices();
84+
return list.map(d => ({ kind: d.kind, label: d.label }));
85+
});
86+
console.log(devices); // Same list on any host
87+
await browser.close();
88+
```
89+
90+
### Development with real devices
91+
92+
When testing audio/video capture locally, use `real` mode:
93+
94+
```bash
95+
chromium-browser \
96+
--bot-profile="/path/to/profile.enc" \
97+
--bot-config-media-devices=real \
98+
--user-data-dir="$(mktemp -d)"
99+
```
100+
101+
---
102+
103+
<a id="troubleshooting"></a>
104+
105+
## Troubleshooting / FAQ
106+
107+
| Problem | Solution |
108+
|---------|----------|
109+
| Empty device list | Ensure the profile contains media device data. Most standard profiles include default device entries. |
110+
| Need real microphone access | Set `--bot-config-media-devices=real` to expose host hardware. |
111+
| Device IDs change between sessions | Device IDs are derived from the profile. Use the same profile for consistent IDs across sessions. |
112+
113+
---
114+
115+
<a id="next-steps"></a>
116+
117+
## Next Steps
118+
119+
- [Audio Fingerprint Protection](AUDIO.md). Control audio rendering and noise.
120+
- [Navigator Properties](NAVIGATOR_PROPERTIES.md). Other navigator-level fingerprint surfaces.
121+
- [CLI Flags Reference](../../../CLI_FLAGS.md#profile-configuration-override-flags). Complete flag documentation.
122+
123+
---
124+
125+
**Related documentation:** [CLI Flags](../../../CLI_FLAGS.md) | [Profile Configuration](../../../profiles/PROFILE_CONFIGS.md)
126+
127+
---
128+
129+
**[Legal Disclaimer & Terms of Use](https://github.com/botswin/BotBrowser/blob/main/DISCLAIMER.md) • [Responsible Use Guidelines](https://github.com/botswin/BotBrowser/blob/main/RESPONSIBLE_USE.md)**. BotBrowser is for authorized fingerprint protection and privacy research only.

0 commit comments

Comments
 (0)