0
# Chrome API Evasions
1

2
Evasion techniques that mock Chrome-specific APIs to prevent detection through missing Chrome objects. These evasions simulate the presence of Chrome extension APIs that are typically available in regular Chrome browsers but missing in headless mode.
3

4
## Capabilities
5

6
### Chrome App API Evasion
7

8
Mocks the `chrome.app` API to prevent detection through its absence.
9

10
```javascript { .api }
11
// Evasion name: 'chrome.app'
12
// Simulates: chrome.app.isInstalled property and related functionality
13
```
14

15
This evasion:
16
- Creates a mock `chrome.app` object when it doesn't exist
17
- Provides realistic `chrome.app.isInstalled` property
18
- Prevents detection through missing Chrome app API
19

20
**Detection Method Prevented:**
21
```javascript
22
// This detection method will be fooled:
23
if (typeof chrome !== 'undefined' && chrome.app) {
24
  // Assumes real browser
25
} else {
26
  // Detects headless/automation
27
}
28
```
29

30
### Chrome CSI API Evasion
31

32
Mocks the `chrome.csi` API for Chrome Site Isolation metrics.
33

34
```javascript { .api }
35
// Evasion name: 'chrome.csi'
36
// Simulates: chrome.csi() function and performance metrics
37
```
38

39
This evasion:
40
- Creates a mock `chrome.csi()` function
41
- Returns realistic performance timing data
42
- Simulates Chrome's internal performance measurement API
43

44
**Detection Method Prevented:**
45
```javascript
46
// This detection method will be fooled:
47
try {
48
  const csi = chrome.csi();
49
  if (csi && csi.pageT) {
50
    // Assumes real Chrome browser
51
  }
52
} catch (e) {
53
  // Detects missing Chrome CSI API
54
}
55
```
56

57
### Chrome LoadTimes API Evasion
58

59
Mocks the deprecated `chrome.loadTimes` API for backward compatibility.
60

61
```javascript { .api }
62
// Evasion name: 'chrome.loadTimes'
63
// Simulates: chrome.loadTimes() function with realistic timing data
64
```
65

66
This evasion:
67
- Creates a mock `chrome.loadTimes()` function
68
- Returns realistic page load timing information
69
- Simulates the deprecated but still detectable Chrome API
70

71
**Detection Method Prevented:**
72
```javascript
73
// This detection method will be fooled:
74
if (chrome && chrome.loadTimes) {
75
  const loadTimes = chrome.loadTimes();
76
  if (loadTimes.requestTime && loadTimes.finishDocumentLoadTime) {
77
    // Assumes real Chrome with load times API
78
  }
79
}
80
```
81

82
### Chrome Runtime API Evasion
83

84
Mocks the `chrome.runtime` API that's normally available in Chrome extensions.
85

86
```javascript { .api }
87
// Evasion name: 'chrome.runtime'
88
// Simulates: chrome.runtime object with extension-like properties
89
```
90

91
This evasion:
92
- Creates a comprehensive mock `chrome.runtime` object
93
- Includes realistic `chrome.runtime.sendMessage` function
94
- Provides `chrome.runtime.connect` and related methods
95
- Simulates extension-like environment
96

97
**Detection Method Prevented:**
98
```javascript
99
// This detection method will be fooled:
100
if (chrome && chrome.runtime && chrome.runtime.sendMessage) {
101
  try {
102
    chrome.runtime.sendMessage('test');
103
    // Assumes Chrome extension environment
104
  } catch (e) {
105
    // Would detect fake/missing runtime API
106
  }
107
}
108
```
109

110
**Usage Examples:**
111

112
```javascript
113
const puppeteer = require('puppeteer-extra');
114
const StealthPlugin = require('puppeteer-extra-plugin-stealth');
115

116
// Enable only Chrome API evasions
117
const chromeOnlyStealth = StealthPlugin({
118
  enabledEvasions: new Set([
119
    'chrome.app',
120
    'chrome.csi', 
121
    'chrome.loadTimes',
122
    'chrome.runtime'
123
  ])
124
});
125

126
puppeteer.use(chromeOnlyStealth);
127

128
const browser = await puppeteer.launch();
129
const page = await browser.newPage();
130

131
// These Chrome APIs will now be available and functional
132
await page.evaluate(() => {
133
  console.log(chrome.app.isInstalled); // Works
134
  console.log(chrome.csi()); // Returns timing data
135
  console.log(chrome.loadTimes()); // Returns load timing
136
  chrome.runtime.sendMessage('test'); // Functions without error
137
});
138
```
139

140
## Static Data and Realism
141

142
The Chrome API evasions use static data files to provide realistic responses:
143

144
- **chrome.runtime** uses `staticData.json` for realistic extension-like data
145
- **chrome.csi** provides believable performance timing metrics
146
- **chrome.loadTimes** returns plausible page load timing information
147
- **chrome.app** provides consistent app installation status
148

149
## Implementation Details
150

151
Each Chrome API evasion:
152

153
1. **Detects Environment**: Checks if running in a secure context where Chrome APIs should exist
154
2. **Creates Mock Objects**: Builds realistic Chrome API objects with proper structure
155
3. **Provides Functional Methods**: Ensures mocked methods can be called without errors
156
4. **Uses Stealth Utilities**: Leverages the shared utility system for undetectable API modification
157
5. **Handles Edge Cases**: Accounts for different Chrome versions and API variations
158

159
## Security Considerations
160

161
These evasions:
162
- Only create Chrome API mocks, they don't provide real Chrome extension functionality
163
- Are designed for testing and automation, not for bypassing security measures
164
- Should be used responsibly in compliance with website terms of service
165
- May trigger security warnings in some Chrome configurations