0
# Browser Fingerprinting Evasions
1

2
Advanced evasion techniques that modify browser fingerprinting vectors including media codecs, WebGL properties, and comprehensive user agent handling. These evasions target sophisticated detection methods that analyze browser capabilities and characteristics.
3

4
## Capabilities
5

6
### User Agent Override Evasion
7

8
Comprehensive user agent management that fixes user agent strings, platform information, and user agent client hints.
9

10
```javascript { .api }
11
// Evasion name: 'user-agent-override'
12
// Fixes: User agent string, Accept-Language header, navigator.platform, UA client hints
13
```
14

15
**Configuration Options:**
16

17
```javascript { .api }
18
interface UserAgentOptions {
19
  /** Custom user agent string (default: auto-generated from browser) */
20
  userAgent?: string;
21
  /** Locale for Accept-Language header (default: 'en-US,en') */
22
  locale?: string;
23
  /** Whether to mask Linux as Windows (default: true) */
24
  maskLinux?: boolean;
25
}
26
```
27

28
This evasion:
29
- Strips "HeadlessChrome" from user agent strings
30
- Optionally masks Linux systems as Windows for better anonymity
31
- Sets consistent Accept-Language headers
32
- Provides accurate user agent client hints (brands, platform, architecture)
33
- Coordinates with user preferences plugin for browser language settings
34

35
**Detection Methods Prevented:**
36
```javascript
37
// These detection methods will be fooled:
38

39
// 1. Headless Chrome detection
40
if (navigator.userAgent.includes('HeadlessChrome')) {
41
  // Would detect headless mode
42
}
43

44
// 2. Platform inconsistency detection  
45
if (navigator.platform === 'Linux' && navigator.userAgent.includes('Windows')) {
46
  // Would detect user agent spoofing
47
}
48

49
// 3. Language header inconsistency
50
// Accept-Language header now matches navigator.languages
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
// Use default user agent override
57
const stealth = StealthPlugin({
58
  enabledEvasions: new Set(['user-agent-override'])
59
});
60

61
// Custom user agent and locale
62
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
63
const UserAgentOverride = require('puppeteer-extra-plugin-stealth/evasions/user-agent-override');
64

65
const customUA = UserAgentOverride({
66
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
67
  locale: 'de-DE,de',
68
  maskLinux: false
69
});
70

71
puppeteer.use(customUA);
72
```
73

74
### Media Codecs Evasion
75

76
Fixes media codec detection to prevent fingerprinting through supported audio/video formats.
77

78
```javascript { .api }
79
// Evasion name: 'media.codecs'
80
// Fixes: HTMLMediaElement.canPlayType() responses for realistic codec support
81
```
82

83
This evasion:
84
- Provides realistic responses to `video.canPlayType()` and `audio.canPlayType()`
85
- Ensures codec support matches the simulated browser environment
86
- Prevents detection through unusual codec support patterns
87
- Covers common formats: MP4, WebM, OGG, etc.
88

89
**Detection Method Prevented:**
90
```javascript
91
// This detection method will be fooled:
92
const video = document.createElement('video');
93
const codecs = ['video/mp4', 'video/webm', 'video/ogg'];
94
const support = codecs.map(codec => video.canPlayType(codec));
95

96
if (support.every(s => s === '')) {
97
  // Would detect unusual lack of codec support
98
}
99
```
100

101
### WebGL Vendor Evasion
102

103
Fixes WebGL vendor and renderer information to prevent graphics-based fingerprinting.
104

105
```javascript { .api }
106
// Evasion name: 'webgl.vendor'
107
// Fixes: WebGL vendor and renderer strings for realistic GPU fingerprinting
108
```
109

110
This evasion:
111
- Modifies `WEBGL_debug_renderer_info` extension responses
112
- Provides realistic vendor strings (e.g., "Google Inc.")
113
- Sets believable renderer information (e.g., "ANGLE (Intel HD Graphics)")
114
- Prevents detection through unusual WebGL properties
115

116
**Detection Method Prevented:**
117
```javascript
118
// This detection method will be fooled:
119
const canvas = document.createElement('canvas');
120
const gl = canvas.getContext('webgl');
121
const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
122

123
if (debugInfo) {
124
  const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
125
  const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
126
  
127
  if (vendor.includes('SwiftShader') || renderer.includes('SwiftShader')) {
128
    // Would detect software rendering indicating automation
129
  }
130
}
131
```
132

133
**Usage Examples:**
134

135
```javascript
136
const puppeteer = require('puppeteer-extra');
137
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
138

139
// Enable fingerprinting evasions
140
const fingerprintStealth = StealthPlugin({
141
  enabledEvasions: new Set([
142
    'user-agent-override',
143
    'media.codecs',
144
    'webgl.vendor'
145
  ])
146
});
147

148
puppeteer.use(fingerprintStealth);
149

150
const browser = await puppeteer.launch();
151
const page = await browser.newPage();
152

153
// Fingerprinting will now return realistic values
154
await page.evaluate(() => {
155
  // User agent is clean
156
  console.log(navigator.userAgent); // No "HeadlessChrome"
157
  
158
  // Media codecs work normally
159
  const video = document.createElement('video');
160
  console.log(video.canPlayType('video/mp4')); // "probably" or "maybe"
161
  
162
  // WebGL vendor is realistic
163
  const canvas = document.createElement('canvas');
164
  const gl = canvas.getContext('webgl');
165
  const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
166
  if (debugInfo) {
167
    console.log(gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL)); // "Google Inc."
168
  }
169
});
170
```
171

172
## Advanced Configuration
173

174
### User Agent Override Options
175

176
```javascript
177
// Minimal user agent override (keeps original user agent, just removes headless indicators)
178
const minimalUA = StealthPlugin({
179
  enabledEvasions: new Set(['user-agent-override'])
180
});
181

182
// Custom user agent with specific locale
183
const UserAgentOverride = require('puppeteer-extra-plugin-stealth/evasions/user-agent-override');
184
const customUA = UserAgentOverride({
185
  userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
186
  locale: 'en-GB,en',
187
  maskLinux: false
188
});
189

190
// Don't mask Linux (keep original platform)
191
const linuxUA = UserAgentOverride({
192
  maskLinux: false,
193
  locale: 'en-US,en'
194
});
195
```
196

197
### Coordinated Fingerprinting Protection
198

199
These evasions work together to provide comprehensive fingerprinting protection:
200

201
```javascript
202
// Full fingerprinting protection
203
const fullFingerprintProtection = StealthPlugin({
204
  enabledEvasions: new Set([
205
    'user-agent-override',  // Clean user agent and headers
206
    'media.codecs',         // Realistic media support  
207
    'webgl.vendor',         // Clean WebGL fingerprint
208
    'navigator.languages',  // Consistent language reporting
209
    'navigator.plugins',    // Realistic plugin list
210
    'window.outerdimensions' // Proper window dimensions
211
  ])
212
});
213
```
214

215
## Implementation Details
216

217
### User Agent Processing
218

219
The user agent override evasion:
220
1. **Captures Original**: Gets the browser's natural user agent
221
2. **Removes Headless Indicators**: Strips "HeadlessChrome/" and similar markers
222
3. **Platform Masking**: Optionally changes Linux indicators to Windows
223
4. **Client Hints Generation**: Creates matching user agent client hints
224
5. **Header Coordination**: Sets Accept-Language header to match navigator.languages
225

226
### Media Codec Simulation
227

228
The media codecs evasion:
229
1. **Overrides canPlayType**: Intercepts HTMLMediaElement.prototype.canPlayType calls
230
2. **Provides Realistic Responses**: Returns appropriate "probably", "maybe", or "" responses
231
3. **Format Coverage**: Handles all common video/audio formats and codecs
232
4. **Version Awareness**: Adapts responses based on the browser version being simulated
233

234
### WebGL Fingerprint Modification
235

236
The WebGL vendor evasion:
237
1. **Extension Interception**: Modifies WEBGL_debug_renderer_info extension
238
2. **Parameter Override**: Changes UNMASKED_VENDOR_WEBGL and UNMASKED_RENDERER_WEBGL
239
3. **Realistic Values**: Provides common vendor/renderer combinations
240
4. **Consistency Maintenance**: Ensures WebGL properties align with user agent
241

242
## Security and Privacy Considerations
243

244
These fingerprinting evasions:
245
- **Reduce Trackability**: Make browsers harder to fingerprint and track
246
- **Improve Privacy**: Reduce the uniqueness of browser fingerprints
247
- **Maintain Functionality**: Don't break websites that rely on proper codec/WebGL detection
248
- **Require Responsibility**: Should be used ethically and in compliance with website terms