BotDetect v2 — Production Bot Detection Library

Client-side bot and automation detection library with weighted scoring, behavioral analysis, browser fingerprinting, and configurable thresholds. Detects headless browsers, Selenium, Puppeteer, Playwright, CDP-based tools, and stealth automation frameworks.

v2.1.0 — anti-detection honeypots, GPU-stable canvas fingerprinting, enhanced behavioral analysis, lazy initialization, server-side tamper detection, request fingerprint binding, and rate limiting.

---

Table of Contents

• Features
• Architecture
• Quick Start
• Client-Side API
• Server-Side Integration
• Detection Modules
• Configuration
• Production Checklist
• Testing

---

Features

• 28 detection modules covering automation frameworks, headless browsers, fingerprinting, behavioral analysis, honeypots, and stack trace traps
• Weighted scoring system — each signal has configurable weight; final score computed server-side
• Three verdict levels: human, suspicious, bot with corresponding friction actions (monitor, challenge, block)
• Server-side verification — nonce-gated, replay-protected, proof-of-work signed
• Stack trace traps — monkey-patches DOM APIs to capture automation tool call stacks
• Behavioral analysis — mouse curvature, keystroke timing variance, scroll acceleration, touch dynamics
• Anti-detection honeypots — randomized CSS cloaking, decoy fields, realistic field names
• Server-side tamper detection — validates signal integrity, detects gaming attempts
• Request fingerprint binding — PoW tokens bound to HTTP request attributes
• Rate limiting — per-session rate limiting on all verification endpoints
• No-script detection — identifies clients that never send detection payloads
• Known crawler allowlist — 20+ legitimate bots excluded from scoring

---

Architecture

Browser                                  Your Server
┌──────────────────────────┐            ┌──────────────────────┐
│ Collector (singleton)    │  POST      │ Express Middleware    │
│  ├─ 28 detection modules│  signals   │  ├─ NonceManager      │
│  ├─ BehaviorTracker     │  + nonce   │  ├─ RateLimiter       │
│  ├─ HoneypotTraps       │───────────▶│  ├─ TamperDetector    │
│  ├─ Stack trace traps   │            │  ├─ computeVerdict()  │
│  └─ IframeContext       │            │  └─ Proof-of-Work     │
│                         │  verdict   │                        │
│  ↓ collect() →          │  + proof   │  Returns:             │
│  DetectionResult[]      │◀───────────│  { verdict, score,    │
└──────────────────────────┘            │    confidence, proof, │
                                        │    tamperScore }      │
                                        └──────────────────────┘
                                              │
                                              ▼
                                        Session-gated endpoint
                                        (login, checkout, etc.)
                                        validates proof before
                                        granting access

Key principle: The browser only collects raw DetectionResult[] signals. The server computes the final verdict using a secret weight table. Client-computed verdicts are never trusted.

---

Quick Start

1. Build

npm install
npm run build

Outputs to dist/:

• botdetect.min.js (with polyfills, ~151 KB)
• botdetect-clean.min.js (modern browsers only, ~74 KB)

2. Include on your page

<script src="/path/to/botdetect.min.js"></script>
<script>
  BotDetect.collector.enableTraps();
  BotDetect.collector.enableBehavioralTracking();
  BotDetect.collector.enableHoneypots();
</script>

3. Set up server-side verification

cd server
npm install express cors express-session
node example-integration.js

4. Send signals on sensitive action

async function onLogin() {
  const { nonce } = await (await fetch('/api/botdetect/nonce')).json();
  BotDetect.collector.setNonce(nonce);

  const signals = await BotDetect.collector.collect();

  const resp = await fetch('/api/botdetect/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ signals, nonce })
  });
  const { verdict, score, proof, friction } = await resp.json();

  document.getElementById('botdetect-proof').value = proof;
  document.getElementById('login-form').submit();
}

5. Validate on the server

app.post('/api/login', (req, res) => {
  const bd = req.session.botdetect;
  if (!bd) return res.status(403).json({ error: 'no_verification' });
  if (bd.verdict === 'bot') return res.status(403).json({ error: 'access_denied' });
  if (bd.verdict === 'suspicious') return challengeCaptcha(req, res);
  res.json({ success: true });
});

---

Client-Side API

Collector (singleton)

import Collector from './collector/Collector';
// or via global: BotDetect.collector

Method	Returns	Description
getInstance(config?)	Collector	Singleton accessor
configure(config)	void	Update config at runtime
getConfig()	CollectorConfig	Current configuration
init()	void	Lazy-init traps, tracking, honeypots
enableTraps()	void	Install stack trace traps on DOM APIs
enableBehavioralTracking()	void	Start mouse/keyboard/scroll monitoring
enableHoneypots(container?)	void	Install honeypot fields
collect()	Promise<DetectionResult[]>	Run all detections
setNonce(nonce)	void	Store server-issued nonce
getSessionId()	string	Unique session identifier
getFingerprint()	string	Session fingerprint hash
resetBehavioralData()	void	Clear behavioral data
destroy()	void	Clean up all listeners and DOM elements

Detector (debug only)

import Detector from './detector/Detector';

Method	Returns	Description
getInstance(config?)	Detector	Singleton accessor
configure(config)	void	Update config
analyze(results)	DetectionVerdict	Score + classify (local debug only)
handleError(error)	DetectionVerdict	Fallback verdict on failure

Warning: analyze() runs entirely in the browser. Never use its output for production decisions.

Types

interface DetectionResult {
  name: string;      // Module name
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (importance)
  detail?: string;   // Human-readable description
}

interface DetectionVerdict {
  verdict: 'bot' | 'suspicious' | 'human';
  score: number;       // 0.0 – 1.0
  confidence: number;  // 0.0 – 1.0
  signals: DetectionResult[];
  threshold: number;
  friction: 'monitor' | 'challenge' | 'block';
}

interface CollectorConfig {
  detectionTimeoutMs: number;   // per-module timeout (default: 3000)
  enableTraps: boolean;
  enableBehavioralTracking: boolean;
  enableHoneypots: boolean;
  thresholds: { strict: number; balanced: number; relaxed: number };
}

---

Server-Side Integration

Express Middleware

const { createBotDetectEndpoint } = require('./server');