bot-script

BotBrowser Script Examples

Privacy-first, framework-less scripting using BotBrowser's native --bot-script feature.

These examples assume an authorized privacy research environment. Review the project Legal Disclaimer and Responsible Use Guidelines before adapting them to your own lab.

What Is --bot-script?

--bot-script executes JavaScript in a privileged, non-extension context where the chrome.debugger API is available. This provides:

• No framework dependencies: pure Chrome DevTools Protocol access for fingerprint protection
• Earlier intervention: execute before page navigation to establish privacy protections
• Privileged context: full chrome.debugger API access
• Isolated execution: framework artifacts do not appear in page context, maintaining fingerprint protection

Usage

chrome.exe --bot-profile="C:\\absolute\\path\\to\\profile.enc" --bot-script="your-script.js"

Examples

Cloudflare Turnstile Challenge Handler

File: cloudflare-turnstile.js

Demonstrates handling of Cloudflare Turnstile challenges using:

• chrome.debugger.getTargets() - Find challenge frames
• chrome.debugger.attach() - Attach to targets
• chrome.debugger.sendCommand() - Send CDP commands
• Mobile device detection and touch event emulation
• Direct coordinate clicking

Usage:

chrome.exe --bot-profile="C:\\absolute\\path\\to\\profile.enc" --bot-script="cloudflare-turnstile.js"

Key APIs Available

Because scripts run in a privileged context, you have access to:

• chrome.debugger - Full Chrome DevTools Protocol access
• chrome.runtime - Runtime APIs
• Standard browser APIs (console, setTimeout, etc.)

Best Practices

1. Error handling: always check chrome.runtime.lastError
2. Target management: track active targets to avoid duplicates
3. Resource cleanup: detach from the debugger when done
4. Timing control: use appropriate delays between actions

Behavior Recipes (Human-Like Interaction)

Mouse movement (CDP)

// Minimal example: smooth cursor path with jitter
const path = [{x:100,y:200},{x:140,y:220},{x:180,y:230},{x:220,y:240}];
for (const p of path) {
  await chrome.debugger.sendCommand({tabId}, 'Input.dispatchMouseEvent', {
    type: 'mouseMoved', x: p.x + Math.random()*0.7, y: p.y + Math.random()*0.7,
    modifiers: 0, buttons: 0
  });
  await new Promise(r => setTimeout(r, 12 + Math.random()*18));
}

Typing cadence (CDP)

const text = 'hello world';
for (const ch of text) {
  await chrome.debugger.sendCommand({tabId}, 'Input.insertText', { text: ch });
  await new Promise(r => setTimeout(r, 35 + Math.random()*45));
}

Scrolling pattern (CDP)

// Wheel events with easing
for (let i = 0; i < 20; i++) {
  await chrome.debugger.sendCommand({tabId}, 'Input.dispatchMouseEvent', {
    type: 'mouseWheel', x: 400, y: 300, deltaY: 60 + Math.sin(i/3)*10
  });
  await new Promise(r => setTimeout(r, 30 + Math.random()*30));
}

Documentation

Chrome Debugger API: https://developer.chrome.com/docs/extensions/reference/api/debugger/

Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/

---

Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.