Bot Scanners

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

Visitor loads your page
        │
        ▼
Bot Scanner JavaScript executes
        │
        ├── Checks for WebDriver
        ├── Detects headless browsers
        ├── Analyzes browser fingerprint
        ├── Monitors behavior patterns
        └── Checks honeypot interactions
        │
        ▼
Bot score calculated (0-100)
        │
        ▼
Detection sent to WebDecoy

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

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

---

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 Options

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

Monitors user behavior for non-human patterns:

Signal	Human	Bot
Mouse movement	Curved, varied	Linear, precise
Scroll patterns	Smooth, variable	Instant jumps
Form filling	Takes time	Instantaneous
Click timing	Variable	Consistent

Enable when: You want deeper analysis of visitor behavior.

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.

---

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 src="https://cdn.webdecoy.com/scanner/v1/scanner.js"
        data-scanner-id="YOUR_SCANNER_ID"
        async>
</script>

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 src="https://cdn.webdecoy.com/scanner/v1/scanner.js"
          data-scanner-id="abc123def456"
          async>
  </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 src="https://cdn.webdecoy.com/scanner/v1/scanner.js"
        data-scanner-id="abc123def456"
        async>
</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/scanner/v1/scanner.js"
        data-scanner-id="abc123def456"
        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/scanner/v1/scanner.js';
    script.setAttribute('data-scanner-id', 'abc123def456');
    script.async = true;
    document.body.appendChild(script);
  }
};
</script>

Snippet Attributes

Attribute	Required	Description
src	Yes	CDN URL for scanner
data-scanner-id	Yes	Your unique scanner ID
async	Recommended	Non-blocking load
data-exclude-paths	Optional	Paths to skip (comma-separated)
data-sample-rate	Optional	Percentage of visitors to scan (1-100)

Verifying Installation

1. Load your website in a browser
2. Open Developer Tools (F12)
3. Go to the Network tab
4. Look for scanner.js request
5. Check Console for any errors

---

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

---

Bot Scanner Pro

Bot Scanner Pro provides enhanced detection for sophisticated AI browsers like Stagehand, Browserbase, and Playwright with stealth plugins.

Lite vs Pro Comparison

Feature	Lite	Pro
Script size	~12KB	~16KB
Detection latency	Immediate	Immediate + 5s behavioral update
Behavioral tracking	Basic	Advanced (raw coordinates)
Canvas fingerprint	Existence check	Full hash
WebGL fingerprint	VERSION only	Deep (UNMASKED_*, extensions)
Audio fingerprint	No	Yes
Best for	High-traffic pages	Login, checkout, sensitive pages

When to Use Pro

Use Bot Scanner Pro when you need to detect:

• AI browsers (Stagehand, Browserbase) that use real Chromium
• Stealth automation (Playwright/Puppeteer with stealth plugins)
• Commercial anti-detect browsers that bypass basic checks

Pro Detection Signals

Behavioral Analysis

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

Signal	Points	Description
Low mousemove count	+25	Fewer than 10 mouse events
Linear paths	+20	Mouse moves in straight lines
Constant velocity	+15	No speed variation
Grid-aligned moves	+15	Exact coordinate positions
Instant clicks	+30	No delay after mouse movement
No pre-movement	+25	Clicks without mouse activity

WebGL Deep Fingerprinting

Signal	Points	Description
SwiftShader renderer	+30	Software rendering (headless)
No unmasked renderer	+15	GPU info hidden
Low extension count	+10	Fewer than 10 WebGL extensions

Audio Fingerprinting

Signal	Points	Description
AudioContext unavailable	+15	API missing or blocked
Zero fingerprint	+25	Mocked AudioContext
Missing baseLatency	+10	Chrome 74+ should have this

Installing Pro 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>

Two-Phase Detection

Pro uses a two-phase approach:

1. Phase 1 (Immediate): Basic detection signals sent on page load
2. Phase 2 (5 seconds): Behavioral analysis sent after user interaction

This catches bots that leave immediately AND provides deep analysis for those that stay.

Expected Detection Rates

AI Browser Type	Lite	Pro
Stagehand + Browserbase	~20%	~60-70%
Playwright + Stealth	~40%	~75%
Basic Puppeteer	~70%	~90%
Commercial anti-detect	~10%	~40%

CDN URLs

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

---

Next Steps

Connect third-party services for automated response:

• Integrations - Cloudflare, Slack, webhooks