BotDetect v2 — Biblioteca de Detecção de Bots de Produção

Biblioteca de detecção de bots e automação no lado do cliente com pontuação ponderada, análise comportamental, impressão digital do navegador e limites configuráveis. Detecta navegadores headless, Selenium, Puppeteer, Playwright, ferramentas baseadas em CDP e estruturas de automação furtiva.

v2.1.0 — honeypots anti-detecção, impressão digital de canvas estável em GPU, análise comportamental aprimorada, inicialização preguiçosa, detecção de adulteração no lado do servidor, vinculação de impressão digital de requisição e limitação de taxa.

---

Índice

• Funcionalidades
• Arquitetura
• Início Rápido
• API do Lado do Cliente
• Integração no Lado do Servidor
• Módulos de Detecção
• Configuração
• Lista de Verificação para Produção
• Testes

---

Funcionalidades

• 28 módulos de detecção cobrindo estruturas de automação, navegadores headless, impressão digital, análise comportamental, honeypots e armadilhas de stack trace
• Sistema de pontuação ponderada — cada sinal tem peso configurável; pontuação final calculada no servidor
• Três níveis de veredito: human, suspicious, bot com ações de atrito correspondentes (monitor, challenge, block)
• Verificação no lado do servidor — protegido por nonce, replay protegido, prova-de-trabalho assinada
• Armadilhas de stack trace — monkey-patches de APIs DOM para capturar call stacks de ferramentas de automação
• Análise comportamental — curvatura do mouse, variação de tempo de digitação, aceleração de rolagem, dinâmica de toque
• Honeypots anti-detecção — ocultação CSS aleatória, campos isca, nomes de campo realistas
• Detecção de adulteração no servidor — valida integridade do sinal, detecta tentativas de manipulação
• Vinculação de impressão digital da requisição — tokens PoW vinculados a atributos da requisição HTTP
• Limitação de taxa — limitação de taxa por sessão em todos os endpoints de verificação
• Detecção sem script — identifica clientes que nunca enviam payloads de detecção
• Lista de permissão de crawlers conhecidos — 20+ bots legítimos excluídos da pontuação

---

Arquitetura

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

Princípio chave: O navegador apenas coleta sinais brutos DetectionResult[]. O servidor calcula o veredito final usando uma tabela de pesos secreta. Vereditos calculados no cliente nunca são confiáveis.

---

Início Rápido

1. Construir

npm install
npm run build

Saída em dist/:

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

2. Incluir na sua página

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

3. Configurar verificação no lado do servidor

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

4. Enviar sinais em ação sensível

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 no 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 do Lado do Cliente

Coletor (singleton)

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

Método	Retorno	Descrição
getInstance(config?)	Collector	Acessor singleton
configure(config)	void	Atualizar configuração em tempo de execução
getConfig()	CollectorConfig	Configuração atual
init()	void	Inicialização preguiçosa de armadilhas, rastreamento, honeypots
enableTraps()	void	Instalar armadilhas de stack trace em APIs DOM
enableBehavioralTracking()	void	Iniciar monitoramento de mouse/teclado/rolagem
enableHoneypots(container?)	void	Instalar campos honeypot
collect()	Promise<DetectionResult[]>	Executar todas as detecções
setNonce(nonce)	void	Armazenar nonce emitido pelo servidor
getSessionId()	string	Identificador único de sessão
getFingerprint()	string	Hash da impressão digital da sessão
resetBehavioralData()	void	Limpar dados comportamentais
destroy()	void	Limpar todos os listeners e elementos DOM

Detector (apenas depuração)

import Detector from './detector/Detector';

Método	Retorno	Descrição
getInstance(config?)	Detector	Acessor singleton
configure(config)	void	Atualizar configuração
analyze(results)	DetectionVerdict	Pontuar + classificar (apenas depuração local)
handleError(error)	DetectionVerdict	Veredito de fallback em caso de falha

Aviso: analyze() é executado inteiramente no navegador. Nunca use sua saída para decisões de produção.

Tipos

interface DetectionResult {
  name: string;      // Nome do módulo
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (importância)
  detail?: string;   // Descrição legível
}

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