BotDetect v2 — библиотека обнаружения ботов для продакшена

Клиентская библиотека для обнаружения ботов и автоматизации с взвешенной оценкой, поведенческим анализом, сбором цифрового отпечатка браузера и настраиваемыми порогами. Обнаруживает безголовые браузеры, Selenium, Puppeteer, Playwright, инструменты на основе CDP и стелс-фреймворки автоматизации.

v2.1.0 — антидетекционные приманки, стабильный к GPU canvas-отпечаток, улучшенный поведенческий анализ, ленивая инициализация, серверное обнаружение подделки сигналов, привязка отпечатка запроса и ограничение скорости.

---

Содержание

• Возможности
• Архитектура
• Быстрый старт
• Клиентский API
• Серверная интеграция
• Модули обнаружения
• Конфигурация
• Чек-лист для продакшена
• Тестирование

---

Возможности

• 28 модулей обнаружения, покрывающих фреймворки автоматизации, безголовые браузеры, сбор отпечатков, поведенческий анализ, приманки и ловушки стек-трейсов
• Взвешенная система оценки — каждый сигнал имеет настраиваемый вес; итоговый вердикт вычисляется на сервере
• Три уровня вердикта: human, suspicious, bot с соответствующими действиями (monitor, challenge, block)
• Серверная верификация — защита от повторного использования nonce, подпись proof-of-work
• Ловушки стек-трейсов — подмена методов DOM для захвата стеков вызовов инструментов автоматизации
• Поведенческий анализ — кривизна мыши, вариативность времени нажатий клавиш, ускорение прокрутки, динамика касаний
• Антидетекционные приманки — рандомизированное CSS-маскирование, поля-приманки, реалистичные имена полей
• Серверное обнаружение подделки — проверка целостности сигналов, выявление попыток обмана
• Привязка отпечатка запроса — токены PoW привязаны к атрибутам HTTP-запроса
• Ограничение скорости — ограничение на сессию для всех эндпоинтов верификации
• Обнаружение отключенного JavaScript — выявление клиентов, никогда не отправляющих полезную нагрузку обнаружения
• Белый список известных краулеров — 20+ легитимных ботов исключены из оценки

---

Архитектура

Браузер                                  Ваш сервер
┌──────────────────────────┐            ┌──────────────────────┐
│ Collector (синглтон)     │  POST      │ Express Middleware    │
│  ├─ 28 модулей          │  signals   │  ├─ NonceManager      │
│  ├─ BehaviorTracker     │  + nonce   │  ├─ RateLimiter       │
│  ├─ HoneypotTraps       │───────────▶│  ├─ TamperDetector    │
│  ├─ Stack trace traps   │            │  ├─ computeVerdict()  │
│  └─ IframeContext       │            │  └─ Proof-of-Work     │
│                         │  verdict   │                        │
│  ↓ collect() →          │  + proof   │  Возвращает:          │
│  DetectionResult[]      │◀───────────│  { verdict, score,    │
└──────────────────────────┘            │    confidence, proof, │
                                        │    tamperScore }      │
                                        └──────────────────────┘
                                              │
                                              ▼
                                        Эндпоинт, защищённый сессией
                                        (логин, оформление заказа и т.д.)
                                        проверяет proof перед
                                        предоставлением доступа

Ключевой принцип: браузер собирает только необработанные сигналы DetectionResult[]. Сервер вычисляет итоговый вердикт, используя секретную таблицу весов. Вердикты, вычисленные на клиенте, никогда не доверяются.

---

Быстрый старт

1. Сборка

npm install
npm run build

Результат в dist/:

• botdetect.min.js (с полифиллами, ~151 КБ)
• botdetect-clean.min.js (только для современных браузеров, ~74 КБ)

2. Подключение на странице

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

3. Настройка серверной верификации

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

4. Отправка сигналов при чувствительном действии

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. Проверка на сервере

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

---

Клиентский API

Collector (синглтон)

import Collector from './collector/Collector';
// или через глобал: BotDetect.collector

Метод	Возвращает	Описание
getInstance(config?)	Collector	Доступ к синглтону
configure(config)	void	Обновление конфигурации во время выполнения
getConfig()	CollectorConfig	Текущая конфигурация
init()	void	Ленивая инициализация ловушек, отслеживания, приманок
enableTraps()	void	Установка ловушек стек-трейсов на DOM API
enableBehavioralTracking()	void	Запуск мониторинга мыши/клавиатуры/прокрутки
enableHoneypots(container?)	void	Установка полей-приманок
collect()	Promise<DetectionResult[]>	Запуск всех обнаружений
setNonce(nonce)	void	Сохранение nonce, выданного сервером
getSessionId()	string	Уникальный идентификатор сессии
getFingerprint()	string	Хэш отпечатка сессии
resetBehavioralData()	void	Очистка поведенческих данных
destroy()	void	Очистка всех слушателей и DOM-элементов

Detector (только для отладки)

import Detector from './detector/Detector';

Метод	Возвращает	Описание
getInstance(config?)	Detector	Доступ к синглтону
configure(config)	void	Обновление конфигурации
analyze(results)	DetectionVerdict	Оценка + классификация (только локальная отладка)
handleError(error)	DetectionVerdict	Вердикт по умолчанию при ошибке

Предупреждение: analyze() выполняется полностью в браузере. Никогда не используйте его результат для продакшен-решений.

Типы

interface DetectionResult {
  name: string;      // Имя модуля
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (важность)
  detail?: string;   // Описание на человеческом языке
}

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;   // таймаут на модуль (по умолчанию: 3000)
  enableTraps: boolean;
  enableBehavioralTracking: boolean;
  enableHoneypots: boolean;
  thresholds: { strict: number; balanced: number; relaxed: number };
}

---