BotDetect v2 — Produktions-Bot-Erkennungsbibliothek

Clientseitige Bot- und Automatisierungserkennungsbibliothek mit gewichteter Bewertung, Verhaltensanalyse, Browser-Fingerprinting und konfigurierbaren Schwellenwerten. Erkennt Headless-Browser, Selenium, Puppeteer, Playwright, CDP-basierte Tools und Stealth-Automatisierungsframeworks.

v2.1.0 — Anti-Erkennungs-Honeypots, GPU-stabiles Canvas-Fingerprinting, verbesserte Verhaltensanalyse, träge Initialisierung, serverseitige Manipulationserkennung, Anforderungs-Fingerprint-Bindung und Ratenbegrenzung.

Funktionen

28 Erkennungsmodule decken Automatisierungsframeworks, Headless-Browser, Fingerprinting, Verhaltensanalyse, Honeypots und Stack-Trace-Fallen ab.
Gewichtetes Bewertungssystem — jedes Signal hat ein konfigurierbares Gewicht; endgültige Bewertung serverseitig berechnet.
Drei Urteilsstufen: human, suspicious, bot mit entsprechenden Reaktionsmaßnahmen (monitor, challenge, block)
Serverseitige Überprüfung — Nonce-gesteuert, replay-geschützt, Proof-of-Work-signiert.
Stack-Trace-Fallen — patcht DOM-APIs, um Aufrufstapel von Automatisierungswerkzeugen zu erfassen.
Verhaltensanalyse — Mauskrümmung, Tastenanschlagsdauervarianz, Scrollbeschleunigung, Touch-Dynamik.
Anti-Erkennungs-Honeypots — zufälliges CSS-Cloaking, Täuschungsfelder, realistische Feldnamen.
Serverseitige Manipulationserkennung — prüft Signalintegrität, erkennt Manipulationsversuche.
Anforderungs-Fingerprint-Bindung — PoW-Tokens an HTTP-Anforderungsattribute gebunden.
Ratenbegrenzung — sitzungsbezogene Ratenbegrenzung auf allen Verifikationsendpunkten.
No-Script-Erkennung — identifiziert Clients, die nie Erkennungspayloads senden.
Bekannte Crawler-Whitelist — 20+ legitime Bots von der Bewertung ausgeschlossen.

Architektur

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

Schlüsselprinzip: Der Browser sammelt nur rohe DetectionResult[]-Signale. Der Server berechnet das endgültige Urteil mit einer geheimen Gewichtstabelle. Vom Client berechnete Urteile werden niemals vertraut.

Schnellstart

1. Erstellen

npm install
npm run build

Ausgabe in dist/:

botdetect.min.js (mit Polyfills, ~151 KB)
botdetect-clean.min.js (nur moderne Browser, ~74 KB)

2. Auf Ihrer Seite einbinden

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

3. Serverseitige Verifikation einrichten

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

4. Signale bei sensiblen Aktionen senden

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. Auf dem Server validieren

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 });
});

Clientseitige API

Collector (Singleton)

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

Methode	Rückgabe	Beschreibung
`getInstance(config?)`	`Collector`	Singleton-Zugriff
`configure(config)`	`void`	Konfiguration zur Laufzeit aktualisieren
`getConfig()`	`CollectorConfig`	Aktuelle Konfiguration
`init()`	`void`	Lazy-Initialisierung von Traps, Tracking, Honeypots
`enableTraps()`	`void`	Stack-Trace-Fallen auf DOM-APIs installieren
`enableBehavioralTracking()`	`void`	Maus-/Tastatur-/Scroll-Überwachung starten
`enableHoneypots(container?)`	`void`	Honeypot-Felder installieren
`collect()`	`Promise<DetectionResult[]>`	Alle Erkennungen ausführen
`setNonce(nonce)`	`void`	Vom Server ausgestellte Nonce speichern
`getSessionId()`	`string`	Eindeutige Sitzungskennung
`getFingerprint()`	`string`	Sitzungs-Fingerprint-Hash
`resetBehavioralData()`	`void`	Verhaltensdaten zurücksetzen
`destroy()`	`void`	Alle Listener und DOM-Elemente bereinigen

Detektor (nur Debug)

import Detector from './detector/Detector';

Methode	Rückgabe	Beschreibung
`getInstance(config?)`	`Detector`	Singleton-Zugriff
`configure(config)`	`void`	Konfiguration aktualisieren
`analyze(results)`	`DetectionVerdict`	Bewerten + klassifizieren (nur lokales Debug)
`handleError(error)`	`DetectionVerdict`	Fallback-Urteil bei Fehler

Warnung: analyze() läuft vollständig im Browser. Verwenden Sie seine Ausgabe niemals für Produktionsentscheidungen.

Typen

interface DetectionResult {
  name: string;      // Modulname
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (Wichtigkeit)
  detail?: string;   // Menschenlesbare Beschreibung
}

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;   // Zeitüberschreitung pro Modul (Standard: 3000)
  enableTraps: boolean;
  enableBehavioralTracking: boolean;
  enableHoneypots: boolean;
  thresholds: { strict: number; balanced: number; relaxed: number };
}

vi-bot

Beliebteste