Bot Scanner

What Is a Bot Scanner?

A bot scanner is a JavaScript-based detection system that runs in visitors’ browsers. It analyzes browser characteristics and behavior to identify automated tools, headless browsers, and bots.

How Bot Scanners Work

Bot Scanner uses a two-phase approach to maximize detection:

Page Load (0ms)
    │
    ├── Phase 1: Immediate Detection
    │   ├── Basic bot signals (webdriver, headless)
    │   ├── CDP artifact detection
    │   ├── Canvas fingerprint hash
    │   ├── WebGL deep parameters
    │   ├── Audio context fingerprint
    │   └── Send detection if score > 20
    │
    ▼
User Interaction (5 seconds)
    │
    ├── Phase 2: Behavioral Analysis
    │   ├── Mouse movement patterns
    │   ├── Click timing analysis
    │   ├── Scroll velocity patterns
    │   ├── Keystroke dynamics
    │   └── Send behavioral update
    │
    ▼
Final Score Calculated

Why two phases?

• Phase 1 catches bots that leave immediately
• Phase 2 provides deep analysis for bots that stay
• Combined data gives the most accurate detection

What Bot Scanners Detect

Detection Type	What It Catches
WebDriver	Selenium, Puppeteer, Playwright automation
Headless Browsers	Chrome Headless, PhantomJS, Firefox Headless
AI Crawlers	GPTBot, ClaudeBot, ChatGPT-User
Browser Anomalies	Inconsistent navigator properties
Behavioral Patterns	Non-human mouse movements, instant form fills
Fingerprint Mismatches	Canvas, WebGL, font rendering inconsistencies
CDP Artifacts	ChromeDriver, Selenium, Puppeteer markers
Environment Integrity	MessageChannel, API mocking detection

Bot Scanner vs. Server-Side Detection

Aspect	Bot Scanner (Client)	Server-Side Detection
Where it runs	Visitor’s browser	Your server
What it sees	Browser internals	HTTP requests
Detection depth	Deep browser analysis	Headers, IP, patterns
Bypass difficulty	Harder to evade	Easier to spoof
Best for	Headless browsers, automation	Scanners, scrapers

Expected Detection Rates

AI Browser Type	Detection Rate
Stagehand + Browserbase	~60-70%
Playwright + Stealth	~75%
Basic Puppeteer	~90%
Commercial anti-detect	~40%

---

Creating a Bot Scanner

Step-by-Step Guide

1. Navigate to Bot Scanners

   • Click Bot Scanners in the sidebar

2. Click “New Bot Scanner”

   • The create scanner dialog opens

3. Configure the Scanner

   Field	Description	Example
   Name	Internal identifier	”Main Website Scanner”
   Property	Associate with property	”Production Website”
   Sensitivity	Detection strictness	Medium
   Enabled	Active/inactive	Yes

4. Click “Create”

   • Scanner is created with a unique ID

5. Install the Snippet

   • Copy the provided JavaScript snippet
   • Add it to your website (see Installing the Snippet)

Scanner Configuration Example

Name: Main Website Scanner
Property: Production Website
Sensitivity: Medium
Enabled: Yes

Detection Options:
✓ Detect automation
✓ Detect headless browsers
✓ Detect AI crawlers
✓ Detect behavioral anomalies
✓ Browser fingerprinting

Honeypot Options:
✓ Inject form honeypot
✓ Inject link honeypot

---

Detection Signals

Automation Detection

Detects browser automation frameworks:

Framework	Detection Method
Selenium WebDriver	navigator.webdriver property
Puppeteer	Chrome DevTools Protocol traces
Playwright	Browser-specific markers
Cypress	Test runner indicators

Enable when: You want to catch automated testing tools and bots.

Headless Browser Detection

Identifies browsers running without a visible UI:

Signal	Description
Missing plugins	Headless browsers often have no plugins
Canvas fingerprint	Rendering differences
WebGL anomalies	Graphics processing inconsistencies
User agent hints	Client hints mismatches

Enable when: Attackers use headless Chrome, PhantomJS, etc.

AI Crawler Detection

Identifies AI/LLM training crawlers:

Bot	User Agent Pattern
GPTBot	GPTBot
ClaudeBot	ClaudeBot
Google-Extended	Google-Extended
PerplexityBot	PerplexityBot
CCBot	CCBot

Enable when: You want to detect AI training data collection.

Behavioral Analysis

Bot Scanner tracks mouse movements, clicks, scrolls, and keystrokes to detect non-human patterns:

Mouse Movement Signals

Signal	Points	What It Detects
Low mousemove count	+25	Fewer than 10 mouse events (bots often skip mouse simulation)
Linear paths	+20	Mouse moves in perfectly straight lines (humans curve)
Constant velocity	+15	No speed variation (humans accelerate/decelerate)
Grid-aligned moves	+15	Positions on exact coordinates (automation artifacts)

Click Signals

Signal	Points	What It Detects
Instant clicks	+30	No delay between mouse stop and click (humans have reaction time)
No pre-movement	+25	Clicks without preceding mouse movement (teleporting cursor)

Scroll Signals

Signal	Points	What It Detects
Constant scroll velocity	+10	Same speed throughout (humans vary)
Perfect scroll intervals	+10	Exact timing between scroll events

Keystroke Signals

Signal	Points	What It Detects
Constant typing rhythm	+15	No variation in keystroke timing
Superhuman typing speed	+20	Less than 30ms between keystrokes

Browser Fingerprinting

Builds a fingerprint from browser characteristics:

• Canvas rendering
• WebGL renderer
• Audio context
• Font enumeration
• Screen properties
• Timezone/language

Enable when: You want to track returning visitors and detect fingerprint anomalies.

WebGL Deep Fingerprinting

Signal	Points	What It Detects
SwiftShader renderer	+30	Software rendering (common in headless Chrome)
Mesa LLVMpipe renderer	+25	Software rendering on Linux
No unmasked renderer	+15	GPU info hidden (real browsers expose this)
Low extension count	+10	Fewer than 10 WebGL extensions

Audio Fingerprinting

Signal	Points	What It Detects
AudioContext unavailable	+15	API missing or blocked
Zero audio fingerprint	+25	Mocked AudioContext returns zero
Missing baseLatency	+10	Chrome 74+ should have this property
Unusual sample rate	+10	Not 44100 or 48000 Hz
Zero channel count	+15	Invalid audio configuration

Canvas Fingerprinting

Bot Scanner generates a unique hash from canvas rendering:

1. Draws specific shapes and text
2. Uses specific fonts and colors
3. Generates hash from the rendered output
4. Compares against known patterns

Headless browsers often have distinct canvas fingerprints due to software rendering.

CDP Artifact Detection

Chrome DevTools Protocol (CDP) is the automation protocol used by ChromeDriver, Puppeteer, Playwright, and other browser automation tools. These tools inject identifiable artifacts that are extremely difficult to hide.

Signal	Points	What It Detects
cdc_ properties	+40	ChromeDriver injects cdc_* prefixed global variables
$cdc_ properties	+40	Older ChromeDriver variants with $cdc_* prefix
__webdriver_evaluate	+30	Selenium WebDriver evaluation artifacts
__selenium_evaluate	+30	Direct Selenium markers
__puppeteer_evaluation_script__	+35	Puppeteer script injection markers
__fxdriver_evaluate	+25	Firefox WebDriver (Geckodriver) artifacts
__cdp_binding__	+40	CDP runtime binding artifacts
__chromium_protocol__	+40	Chromium protocol handler markers
Modified webdriver getter	+35	Attempts to hide navigator.webdriver leave traces
CDP script injection	+30	Scripts injected via Runtime.evaluate protocol

Why CDP detection is highly reliable:

1. Protocol-level injection - These artifacts are injected by the automation framework itself, not the browser
2. Hard to remove - Removing them requires patching the automation tool’s source code
3. Near-zero false positives - Normal browsers never have these properties
4. Catches stealth attempts - Tools that try to hide navigator.webdriver often leave other CDP traces

Example detection:

// ChromeDriver leaves these artifacts:
window.cdc_adoQpoasnfa76pfcZLmcfl_Array    // Random but always cdc_ prefixed
window.cdc_adoQpoasnfa76pfcZLmcfl_Promise  // Multiple cdc_ properties

// Selenium WebDriver leaves:
window.__webdriver_evaluate               // Evaluation function
window.__driver_unwrapped                 // Unwrapped driver reference

// Puppeteer leaves:
window.__puppeteer_evaluation_script__    // Script injection marker

High-Confidence Signal

CDP artifact detection contributes up to +50 points to the threat score because false positives are virtually non-existent. A single CDP artifact is strong evidence of automation.

Environment Integrity Checks

Bot Scanner performs additional environment integrity checks that verify browser APIs behave correctly. Automation tools sometimes incorrectly mock or break these APIs.

MessageChannel Communication Test

The MessageChannel API enables communication between different browsing contexts. Some automation frameworks incorrectly implement or break this API.

Signal	Points	What It Detects
MessageChannel timeout	+10*	Message not received within 100ms
MessageChannel error	+10*	API throws error or is unavailable
MessageChannel exception	+10*	Cannot create MessageChannel

*Weak signal: Only counted when combined with other strong bot indicators. This prevents false positives from legitimate environments that restrict MessageChannel (some sandboxed iframes, older browsers).

Why this detection works:

• Real browsers have full MessageChannel support
• Automation frameworks sometimes mock MessageChannel incorrectly
• The test is fast (100ms timeout) and non-blocking
• Very low performance impact

Low False-Positive Risk

MessageChannel is well-supported across all modern browsers. The test only contributes to the score when other strong indicators are already present.

---

Honeypot Injection

Bot scanners can automatically inject honeypot elements into your pages.

Form Honeypot

Adds hidden form fields that humans can’t see or fill:

<!-- Injected automatically by bot scanner -->
<input type="text"
       name="website_url"
       style="position:absolute;left:-9999px"
       tabindex="-1"
       autocomplete="off">

Behavior	Result
Field is empty	Likely human
Field has value	Definitely a bot

Best for: Contact forms, signup forms, comment sections.

Link Honeypot

Adds hidden links that only bots follow:

<!-- Injected automatically by bot scanner -->
<a href="/trap-path-abc123"
   style="display:none;visibility:hidden">
   Secret Link
</a>

Behavior	Result
Link not clicked	Normal user
Link is followed	Bot or crawler

Best for: Any page where you want crawler detection.

Honeypot Configuration

Option	Description
Inject into forms	Add hidden fields to all forms
Inject links	Add hidden links to page footer
Custom field names	Use realistic-looking field names
Injection frequency	Every page, random pages, specific pages

---

Sensitivity Levels

The sensitivity level determines how strictly the scanner scores visitors.

Low Sensitivity

Score threshold: 70+ to flag as bot False positives: Very rare Detection rate: Catches obvious bots

Best for:

• Sites with privacy-conscious users
• When false positives are unacceptable
• Initial testing

Detects:

• Obvious automation (WebDriver present)
• Known headless browsers
• Honeypot interactions

Medium Sensitivity (Recommended)

Score threshold: 50+ to flag as suspicious False positives: Rare Detection rate: Good balance

Best for:

• Most websites
• Production environments
• General protection

Detects:

• Everything in Low, plus:
• Browser inconsistencies
• Behavioral anomalies
• Fingerprint mismatches

High Sensitivity

Score threshold: 30+ to flag as suspicious False positives: Possible Detection rate: Maximum detection

Best for:

• High-security applications
• Financial services
• When false positives are acceptable

Detects:

• Everything in Medium, plus:
• Subtle automation indicators
• Minor behavioral differences
• Edge-case browser configurations

Sensitivity Comparison

Sensitivity	Score Range Flagged	False Positive Risk	Bot Detection
Low	70-100	Very Low	Basic
Medium	50-100	Low	Good
High	30-100	Medium	Maximum

---

Installing the Bot Scanner Snippet

Getting Your Snippet

1. Go to Bot Scanners
2. Find your scanner in the list
3. Click Copy Snippet (or the copy icon)

Snippet Format

<script async src="https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.min.js"
        data-aid="your-organization-uuid"
        data-sid="your-scanner-uuid">
</script>

Snippet Attributes

Attribute	Required	Description
src	Yes	CDN URL for scanner
data-aid	Yes	Your organization UUID
data-sid	Yes	Your bot scanner UUID
data-endpoint	No	Custom ingest endpoint (default: https://ingest.webdecoy.com/api/v1/detect)
data-exclude-paths	No	Paths to skip (comma-separated)
data-sample-rate	No	Percentage of visitors to scan (1-100)

CDN URLs

Version	URL
Minified	https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.min.js
Source	https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.js

Installation Methods

Method 1: Direct HTML

Add the snippet before the closing </body> tag:

<!DOCTYPE html>
<html>
<head>
  <title>Your Site</title>
</head>
<body>
  <!-- Your content -->

  <!-- WebDecoy Bot Scanner -->
  <script async src="https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.min.js"
          data-aid="your-organization-uuid"
          data-sid="your-scanner-uuid">
  </script>
</body>
</html>

Method 2: Google Tag Manager

1. Create a new Custom HTML tag
2. Paste the snippet
3. Set trigger to All Pages
4. Publish the container

Method 3: WordPress (Manual)

Add to your theme’s footer.php:

<?php if (!is_admin()) : ?>
<script async src="https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.min.js"
        data-aid="your-organization-uuid"
        data-sid="your-scanner-uuid">
</script>
<?php endif; ?>

Method 4: React/Next.js

// _app.js or layout.js
import Script from 'next/script';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.min.js"
        data-aid="your-organization-uuid"
        data-sid="your-scanner-uuid"
        strategy="afterInteractive"
      />
    </>
  );
}

Method 5: Vue.js

App.vue

<template>
  <div id="app">
    <router-view />
  </div>
</template>

<script>
export default {
  mounted() {
    const script = document.createElement('script');
    script.src = 'https://cdn.webdecoy.com/bot-detection/v1/pro/bot-detection-pro.min.js';
    script.setAttribute('data-aid', 'your-organization-uuid');
    script.setAttribute('data-sid', 'your-scanner-uuid');
    script.async = true;
    document.body.appendChild(script);
  }
};
</script>

Verifying Installation

1. Load your website in a browser
2. Open Developer Tools (F12)
3. Go to the Network tab
4. Look for bot-detection-pro.min.js request
5. Check Console for [WebDecoy] messages

---

Managing Bot Scanners

Viewing Scanner List

Go to Bot Scanners to see all scanners:

Column	Description
Name	Scanner identifier
Enabled	Active status toggle
Methods	HTTP methods monitored
Created	Creation date
Actions	Edit, delete, copy snippet

Enabling/Disabling a Scanner

1. Find the scanner in the list
2. Toggle the Enabled switch
3. Scanner is immediately active/inactive

Editing a Scanner

1. Click the menu (three dots)
2. Select Edit
3. Modify settings
4. Click Save

Deleting a Scanner

1. Click the menu (three dots)
2. Select Delete
3. Confirm deletion
4. Scanner and snippet stop working immediately

---

Best Practices

Do’s

• ✅ Start with Medium sensitivity
• ✅ Enable honeypot injection
• ✅ Test on staging before production
• ✅ Monitor false positive rates
• ✅ Combine with server-side detection

Don’ts

• ❌ Use High sensitivity without testing
• ❌ Block users based solely on scanner results
• ❌ Install multiple scanners on the same page
• ❌ Forget to update snippet when changing scanners

Recommended Configuration

Detection Options:
✓ Detect automation - Essential
✓ Detect headless - Essential
✓ Detect AI crawlers - Recommended
✓ Behavioral analysis - Recommended
✓ Fingerprinting - Optional (privacy considerations)

Honeypot Options:
✓ Form honeypot - Highly recommended
✓ Link honeypot - Recommended

---

Privacy Considerations

Bot Scanner collects data for detection purposes:

Data Type	Collected	Purpose
Browser properties	✅	Basic detection
Mouse coordinates	✅	Movement pattern analysis
Click positions	✅	Click behavior analysis
Scroll positions	✅	Scroll pattern analysis
Keystroke timing	✅	Typing rhythm analysis
Canvas fingerprint	✅	Rendering consistency
WebGL parameters	✅	Hardware fingerprinting
Audio fingerprint	✅	Audio context verification

Important:

• Data is used solely for bot detection scoring
• No actual keystrokes are captured (only timing intervals)
• Data is not used for user tracking or advertising
• Consider your privacy policy when deploying

---

Troubleshooting

Detection not sending

1. Check browser console for [WebDecoy] messages
2. Verify data-aid and data-sid attributes are set correctly
3. Ensure score threshold (20) is exceeded
4. Check network tab for requests to ingest endpoint

Low detection rate

1. Ensure behavioral phase has time to collect data (users need 5+ seconds on page)
2. Check that users interact with page (mouse movement, scrolling)
3. Review detection metadata to see which signals are triggering
4. Consider if bots are leaving before Phase 2 completes

CORS errors

Scripts are served with permissive CORS headers. If you see CORS errors:

1. Ensure you’re loading from cdn.webdecoy.com
2. Check if a proxy or CDN is stripping headers
3. Verify no browser extensions are blocking requests

---

Next Steps

• Integrations - Connect to Cloudflare, Slack, webhooks
• Threat Scoring - Understand how scores are calculated
• Decoy Links - Set up server-side detection