0
# Puppeteer Extra Plugin Stealth
1

2
Puppeteer Extra Plugin Stealth is a comprehensive stealth mode plugin for puppeteer-extra and playwright-extra that applies various techniques to make detection of headless browsers harder. It provides 17 different evasion techniques that can be selectively enabled to avoid detection by anti-bot systems.
3

4
## Package Information
5

6
- **Package Name**: puppeteer-extra-plugin-stealth
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install puppeteer-extra-plugin-stealth`
10

11
## Core Imports
12

13
```javascript
14
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import StealthPlugin from 'puppeteer-extra-plugin-stealth';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const puppeteer = require('puppeteer-extra');
27
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
28

29
// Use stealth plugin with all evasions enabled
30
puppeteer.use(StealthPlugin());
31

32
// Launch browser with stealth mode
33
const browser = await puppeteer.launch({ headless: true });
34
const page = await browser.newPage();
35

36
// Navigate normally - stealth techniques are applied automatically
37
await page.goto('https://example.com');
38
await browser.close();
39
```
40

41
### Using Individual Evasions
42

43
Individual evasion techniques can be used independently without the main stealth plugin:
44

45
```javascript
46
const puppeteer = require('puppeteer-extra');
47

48
// Use only specific evasions
49
puppeteer.use(require('puppeteer-extra-plugin-stealth/evasions/navigator.webdriver')());
50
puppeteer.use(require('puppeteer-extra-plugin-stealth/evasions/user-agent-override')());
51

52
const browser = await puppeteer.launch({ headless: true });
53
```
54

55
## Architecture
56

57
The Puppeteer Extra Plugin Stealth is built around several key components:
58

59
- **Main Plugin Class**: `StealthPlugin` extends `PuppeteerExtraPlugin` and manages evasion techniques
60
- **Modular Evasions**: 17 individual evasion techniques that can be independently enabled/disabled
61
- **Utility System**: Shared utilities for stealth API manipulation and proxy management
62
- **Dynamic Dependencies**: Plugin dependencies are loaded based on enabled evasions
63
- **Browser Integration**: Hooks into puppeteer's lifecycle events for seamless stealth application
64

65
## Capabilities
66

67
### Core Plugin Management
68

69
Main plugin functionality for configuring and managing stealth evasions. Controls which evasion techniques are active and provides access to plugin metadata.
70

71
```javascript { .api }
72
/**
73
 * Creates a new stealth plugin instance
74
 * @param opts - Configuration options
75
 * @param opts.enabledEvasions - Set of evasion names to enable
76
 * @returns StealthPlugin instance
77
 */
78
function StealthPlugin(opts?: {
79
  enabledEvasions?: Set<string>;
80
}): StealthPlugin;
81

82
class StealthPlugin extends PuppeteerExtraPlugin {
83
  /** Plugin identifier */
84
  get name(): string;
85
  
86
  /** Default configuration with all available evasions */
87
  get defaults(): {
88
    availableEvasions: Set<string>;
89
    enabledEvasions: Set<string>;
90
  };
91
  
92
  /** Get all available evasion technique names */
93
  get availableEvasions(): Set<string>;
94
  
95
  /** Get/set currently enabled evasion techniques */
96
  get enabledEvasions(): Set<string>;
97
  set enabledEvasions(evasions: Set<string>): void;
98
  
99
  /** Browser setup hook for configuring browser-level options */
100
  onBrowser(browser: any): Promise<void>;
101
}
102
```
103

104
[Core Plugin Management](./core-plugin.md)
105

106
### Chrome API Evasions
107

108
Evasion techniques that mock Chrome-specific APIs to prevent detection through missing Chrome objects. These evasions simulate the presence of Chrome extension APIs.
109

110
```javascript { .api }
111
// Available Chrome API evasions:
112
// - chrome.app: Mocks chrome.app API
113
// - chrome.csi: Mocks chrome.csi API  
114
// - chrome.loadTimes: Mocks chrome.loadTimes API
115
// - chrome.runtime: Mocks chrome.runtime API
116
```
117

118
[Chrome API Evasions](./chrome-evasions.md)
119

120
### Navigator Object Evasions
121

122
Evasion techniques that modify navigator properties to hide headless browser indicators. These techniques fix various navigator object properties that can reveal automation.
123

124
```javascript { .api }
125
// Available Navigator evasions:
126
// - navigator.hardwareConcurrency: Fixes hardware concurrency reporting
127
// - navigator.languages: Fixes language array detection
128
// - navigator.permissions: Fixes permission API behavior
129
// - navigator.plugins: Mocks browser plugins
130
// - navigator.vendor: Overrides navigator.vendor property
131
// - navigator.webdriver: Removes webdriver property
132
```
133

134
[Navigator Evasions](./navigator-evasions.md)
135

136
### Browser Fingerprinting Evasions
137

138
Advanced evasion techniques that modify browser fingerprinting vectors including media codecs, WebGL properties, and user agent handling.
139

140
```javascript { .api }
141
// Available fingerprinting evasions:
142
// - media.codecs: Fixes media codec detection
143
// - webgl.vendor: Fixes WebGL vendor information
144
// - user-agent-override: Comprehensive user agent management
145
```
146

147
[Browser Fingerprinting Evasions](./fingerprinting-evasions.md)
148

149
### Window and Frame Evasions
150

151
Evasion techniques that fix window dimension and iframe-related detection methods.
152

153
```javascript { .api }
154
// Available window/frame evasions:
155
// - window.outerdimensions: Fixes outer window dimensions in headless mode
156
// - iframe.contentWindow: Fixes iframe content window detection
157
```
158

159
[Window and Frame Evasions](./window-frame-evasions.md)
160

161
### Miscellaneous Evasions
162

163
Additional evasion techniques for launch arguments and source code obfuscation.
164

165
```javascript { .api }
166
// Available miscellaneous evasions:
167
// - defaultArgs: Modifies default Puppeteer launch arguments
168
// - sourceurl: Removes source URL traces from injected code
169
```
170

171
[Miscellaneous Evasions](./misc-evasions.md)
172

173
## Configuration Options
174

175
```javascript { .api }
176
interface StealthOptions {
177
  /** Set of evasion technique names to enable (default: all available) */
178
  enabledEvasions?: Set<string>;
179
}
180
```
181

182
## Available Evasion Techniques
183

184
The following evasion techniques are available:
185

186
- `chrome.app` - Mocks Chrome app API
187
- `chrome.csi` - Mocks Chrome CSI API
188
- `chrome.loadTimes` - Mocks Chrome loadTimes API
189
- `chrome.runtime` - Mocks Chrome runtime API
190
- `defaultArgs` - Modifies default launch arguments
191
- `iframe.contentWindow` - Fixes iframe detection
192
- `media.codecs` - Fixes media codec fingerprinting
193
- `navigator.hardwareConcurrency` - Fixes hardware concurrency
194
- `navigator.languages` - Fixes language detection
195
- `navigator.permissions` - Fixes permission API
196
- `navigator.plugins` - Mocks browser plugins
197
- `navigator.vendor` - Overrides navigator.vendor property
198
- `navigator.webdriver` - Removes webdriver property
199
- `sourceurl` - Removes source URL traces
200
- `user-agent-override` - Comprehensive user agent handling
201
- `webgl.vendor` - Fixes WebGL vendor fingerprinting
202
- `window.outerdimensions` - Fixes window dimensions