BotDetect v2 — Bibliothèque de détection de robots en production

Bibliothèque de détection de robots et d'automatisation côté client avec score pondéré, analyse comportementale, empreinte numérique du navigateur et seuils configurables. Détecte les navigateurs sans tête, Selenium, Puppeteer, Playwright, les outils basés sur CDP et les frameworks d'automatisation furtifs.

v2.1.0 — pots de miel anti-détection, empreinte canvas stable sur GPU, analyse comportementale améliorée, initialisation paresseuse, détection de falsification côté serveur, liaison d'empreinte de requête, et limitation de débit.

---

Table des matières

• Fonctionnalités
• Architecture
• Démarrage rapide
• API côté client
• Intégration côté serveur
• Modules de détection
• Configuration
• Liste de vérification pour la production
• Tests

---

Fonctionnalités

• 28 modules de détection couvrant les frameworks d'automatisation, les navigateurs sans tête, l'empreinte numérique, l'analyse comportementale, les pots de miel et les pièges de trace de pile
• Système de score pondéré — chaque signal a un poids configurable ; le score final est calculé côté serveur
• Trois niveaux de verdict : humain, suspect, robot avec des actions de friction correspondantes (surveiller, défier, bloquer)
• Vérification côté serveur — protégée par nonce, contre la relecture, signée par preuve de travail
• Pièges de trace de pile — modifie les API DOM pour capturer les appels de pile des outils d'automatisation
• Analyse comportementale — courbure de la souris, variance temporelle des frappes, accélération du défilement, dynamique tactile
• Pots de miel anti-détection — masquage CSS aléatoire, champs leurres, noms de champs réalistes
• Détection de falsification côté serveur — valide l'intégrité des signaux, détecte les tentatives de triche
• Liaison d'empreinte de requête — jetons PoW liés aux attributs de la requête HTTP
• Limitation de débit — limitation de débit par session sur tous les points de terminaison de vérification
• Détection sans script — identifie les clients qui n'envoient jamais de charges utiles de détection
• Liste blanche de robots connus — 20+ robots légitimes exclus du score

---

Architecture

Navigateur                                 Votre Serveur
┌──────────────────────────────┐            ┌──────────────────────────┐
│ Collecteur (singleton)       │  POST      │ Middleware Express        │
│  ├─ 28 modules de détection │  signaux   │  ├─ GestionnaireNonce     │
│  ├─ SuiviComportemental     │  + nonce   │  ├─ LimiteurDébit         │
│  ├─ PiègesPotMiel           │───────────▶│  ├─ DétecteurFalsification│
│  ├─ PiègesTracePile         │            │  ├─ calculerVerdict()     │
│  └─ ContexteIframe         │            │  └─ Preuve-de-Travail      │
│                              │  verdict   │                            │
│  ↓ collect() →              │  + preuve  │  Retourne :               │
│  DetectionResult[]          │◀───────────│  { verdict, score,        │
└──────────────────────────────┘            │    confiance, preuve,     │
                                            │    scoreFalsification }   │
                                            └──────────────────────────┘
                                                  │
                                                  ▼
                                            Point de terminaison
                                            protégé par session
                                            (connexion, paiement, etc.)
                                            valide la preuve avant
                                            d'accorder l'accès

Principe clé : Le navigateur collecte uniquement les signaux bruts DetectionResult[]. Le serveur calcule le verdict final à l'aide d'une table de poids secrète. Les verdicts calculés par le client ne sont jamais fiables.

---

Démarrage rapide

1. Construire

npm install
npm run build

Produit dans dist/ :

• botdetect.min.js (avec polyfills, ~151 Ko)
• botdetect-clean.min.js (navigateurs modernes uniquement, ~74 Ko)

2. Inclure sur votre page

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

3. Configurer la vérification côté serveur

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

4. Envoyer les signaux lors d'une action 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. Valider sur le serveur

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 côté client

Collecteur (singleton)

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

Méthode	Retour	Description
getInstance(config?)	Collector	Accesseur singleton
configure(config)	void	Mettre à jour la configuration en cours d'exécution
getConfig()	CollectorConfig	Configuration actuelle
init()	void	Initialisation paresseuse des pièges, suivi, pots de miel
enableTraps()	void	Installer les pièges de trace de pile sur les API DOM
enableBehavioralTracking()	void	Démarrer la surveillance souris/clavier/défilement
enableHoneypots(conteneur?)	void	Installer les champs pot de miel
collect()	Promise<DetectionResult[]>	Exécuter toutes les détections
setNonce(nonce)	void	Stocker le nonce émis par le serveur
getSessionId()	string	Identifiant unique de session
getFingerprint()	string	Hachage d'empreinte de session
resetBehavioralData()	void	Effacer les données comportementales
destroy()	void	Nettoyer tous les écouteurs et éléments DOM

Détecteur (débogage uniquement)

import Detector from './detector/Detector';

Méthode	Retour	Description
getInstance(config?)	Detector	Accesseur singleton
configure(config)	void	Mettre à jour la configuration
analyze(résultats)	DetectionVerdict	Score + classification (débogage local uniquement)
handleError(erreur)	DetectionVerdict	Verdict de secours en cas d'échec

Avertissement : analyze() s'exécute entièrement dans le navigateur. N'utilisez jamais sa sortie pour des décisions de production.

Types

interface DetectionResult {
  name: string;      // Nom du module
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (importance)
  detail?: string;   // Description lisible par un humain
}