BotDetect v2 — Librería de Detección de Bots en Producción

Librería de detección de bots y automatización del lado del cliente con puntuación ponderada, análisis de comportamiento, huella digital del navegador y umbrales configurables. Detecta navegadores sin cabeza, Selenium, Puppeteer, Playwright, herramientas basadas en CDP y marcos de automatización sigilosos.

v2.1.0 — honeypots anti-detección, huella digital de canvas estable en GPU, análisis de comportamiento mejorado, inicialización diferida, detección de manipulación del lado del servidor, vinculación de huella de solicitud y limitación de tasa.

---

Tabla de Contenidos

• Características
• Arquitectura
• Inicio Rápido
• API del Lado del Cliente
• Integración del Lado del Servidor
• Módulos de Detección
• Configuración
• Lista de Verificación para Producción
• Pruebas

---

Características

• 28 módulos de detección que cubren marcos de automatización, navegadores sin cabeza, huellas digitales, análisis de comportamiento, honeypots y trampas de traza de pila
• Sistema de puntuación ponderada — cada señal tiene un peso configurable; la puntuación final se calcula en el servidor
• Tres niveles de veredicto: human, suspicious, bot con acciones de fricción correspondientes (monitor, challenge, block)
• Verificación del lado del servidor — protegida por nonce, con protección contra repetición y firma de prueba de trabajo
• Trampas de traza de pila — modifica APIs del DOM para capturar las pilas de llamadas de herramientas de automatización
• Análisis de comportamiento — curvatura del ratón, variación de tiempo de pulsaciones, aceleración de desplazamiento, dinámica táctil
• Honeypots anti-detección — ocultación CSS aleatoria, campos señuelo, nombres de campo realistas
• Detección de manipulación del lado del servidor — valida la integridad de las señales, detecta intentos de engaño
• Vinculación de huella de solicitud — tokens PoW vinculados a atributos de solicitud HTTP
• Limitación de tasa — limitación de tasa por sesión en todos los endpoints de verificación
• Detección sin script — identifica clientes que nunca envían cargas de detección
• Lista blanca de rastreadores conocidos — más de 20 bots legítimos excluidos de la puntuación

---

Arquitectura

Navegador                                  Tu Servidor
┌──────────────────────────┐            ┌──────────────────────┐
│ Colector (singleton)     │  POST      │ Middleware Express     │
│  ├─ 28 módulos detección│  señales   │  ├─ NonceManager       │
│  ├─ BehaviorTracker     │  + nonce   │  ├─ RateLimiter        │
│  ├─ HoneypotTraps       │───────────▶│  ├─ TamperDetector     │
│  ├─ Trampas traza pila  │            │  ├─ computeVerdict()   │
│  └─ IframeContext       │            │  └─ Prueba de trabajo  │
│                         │  veredicto │                        │
│  ↓ collect() →          │  + prueba  │  Devuelve:             │
│  DetectionResult[]      │◀───────────│  { verdict, score,     │
└──────────────────────────┘            │    confidence, proof,  │
                                        │    tamperScore }       │
                                        └──────────────────────┘
                                              │
                                              ▼
                                        Endpoint con compuerta de sesión
                                        (inicio sesión, pago, etc.)
                                        valida la prueba antes de
                                        conceder acceso

Principio clave: El navegador solo recopila señales DetectionResult[] sin procesar. El servidor calcula el veredicto final utilizando una tabla de pesos secreta. Los veredictos calculados por el cliente nunca se confían.

---

Inicio Rápido

1. Construir

npm install
npm run build

Salida en dist/:

• botdetect.min.js (con polyfills, ~151 KB)
• botdetect-clean.min.js (solo navegadores modernos, ~74 KB)

2. Incluir en tu página

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

3. Configurar la verificación del lado del servidor

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

4. Enviar señales en acción sensible

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. Validar en el servidor

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 del Lado del Cliente

Colector (singleton)

import Collector from './collector/Collector';
// o mediante global: BotDetect.collector

Método	Devuelve	Descripción
getInstance(config?)	Collector	Accesor singleton
configure(config)	void	Actualizar configuración en tiempo de ejecución
getConfig()	CollectorConfig	Configuración actual
init()	void	Inicialización diferida de trampas, seguimiento, honeypots
enableTraps()	void	Instalar trampas de traza de pila en APIs del DOM
enableBehavioralTracking()	void	Iniciar monitoreo de ratón/teclado/desplazamiento
enableHoneypots(container?)	void	Instalar campos honeypot
collect()	Promise<DetectionResult[]>	Ejecutar todas las detecciones
setNonce(nonce)	void	Almacenar nonce emitido por el servidor
getSessionId()	string	Identificador único de sesión
getFingerprint()	string	Hash de huella de sesión
resetBehavioralData()	void	Limpiar datos de comportamiento
destroy()	void	Limpiar todos los listeners y elementos DOM

Detector (solo depuración)

import Detector from './detector/Detector';

Método	Devuelve	Descripción
getInstance(config?)	Detector	Accesor singleton
configure(config)	void	Actualizar configuración
analyze(results)	DetectionVerdict	Puntuar + clasificar (solo depuración local)
handleError(error)	DetectionVerdict	Veredicto de respaldo en caso de fallo

Advertencia: analyze() se ejecuta completamente en el navegador. Nunca uses su salida para decisiones en producción.

Tipos

interface DetectionResult {
  name: string;      // Nombre del módulo
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (importancia)
  detail?: string;   // Descripción legible por humanos
}