BotDetect v2 — Libreria di Rilevamento Bot per Produzione

Libreria client-side per il rilevamento di bot e automazione con punteggio ponderato, analisi comportamentale, fingerprinting del browser e soglie configurabili. Rileva browser headless, Selenium, Puppeteer, Playwright, strumenti basati su CDP e framework di automazione stealth.

v2.1.0 — honeypot anti-rilevamento, fingerprinting canvas stabile su GPU, analisi comportamentale migliorata, inizializzazione lazy, rilevamento lato server di manomissioni, binding dell'impronta della richiesta e limitazione della frequenza.

---

Indice

• Funzionalità
• Architettura
• Avvio Rapido
• API Lato Client
• Integrazione Lato Server
• Moduli di Rilevamento
• Configurazione
• Checklist per la Produzione
• Test

---

Funzionalità

• 28 moduli di rilevamento che coprono framework di automazione, browser headless, fingerprinting, analisi comportamentale, honeypot e trappole per stack trace
• Sistema di punteggio ponderato — ogni segnale ha un peso configurabile; il punteggio finale viene calcolato lato server
• Tre livelli di verdetto: human, suspicious, bot con corrispondenti azioni di contrasto (monitor, challenge, block)
• Verifica lato server — protetta da nonce, replay, proof-of-work firmato
• Trappole per stack trace — monkey-patching delle API DOM per catturare gli stack delle chiamate degli strumenti di automazione
• Analisi comportamentale — curvatura del mouse, varianza temporale della digitazione, accelerazione dello scorrimento, dinamiche tattili
• Honeypot anti-rilevamento — mascheramento CSS randomizzato, campi esca, nomi di campo realistici
• Rilevamento lato server di manomissioni — verifica l'integrità dei segnali, rileva tentativi di manipolazione
• Binding dell'impronta della richiesta — token PoW legati agli attributi della richiesta HTTP
• Limitazione della frequenza — limitazione per sessione su tutti gli endpoint di verifica
• Rilevamento no-script — identifica i client che non inviano mai payload di rilevamento
• Whitelist di crawler noti — oltre 20 bot legittimi esclusi dal calcolo del punteggio

---

Architettura

Browser                                  Il tuo Server
┌──────────────────────────┐            ┌──────────────────────┐
│ Collector (singleton)    │  POST      │ Express Middleware    │
│  ├─ 28 moduli rilevam.   │  segnali   │  ├─ NonceManager      │
│  ├─ BehaviorTracker      │  + nonce   │  ├─ RateLimiter       │
│  ├─ HoneypotTraps        │───────────▶│  ├─ TamperDetector    │
│  ├─ Trappole stack trace │            │  ├─ computeVerdict()  │
│  └─ IframeContext        │            │  └─ Proof-of-Work     │
│                          │  verdetto  │                        │
│  ↓ collect() →           │  + proof   │  Restituisce:         │
│  DetectionResult[]       │◀───────────│  { verdict, score,    │
└──────────────────────────┘            │    confidence, proof, │
                                        │    tamperScore }      │
                                        └──────────────────────┘
                                              │
                                              ▼
                                        Endpoint protetto da sessione
                                        (login, checkout, etc.)
                                        valida il proof prima di
                                        concedere l'accesso

Principio chiave: Il browser raccoglie solo i segnali DetectionResult[] grezzi. Il server calcola il verdetto finale utilizzando una tabella di pesi segreta. I verdetti calcolati dal client non sono mai attendibili.

---

Avvio Rapido

1. Build

npm install
npm run build

Output in dist/:

• botdetect.min.js (con polyfill, ~151 KB)
• botdetect-clean.min.js (solo browser moderni, ~74 KB)

2. Includere nella pagina

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

3. Configurare la verifica lato server

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

4. Inviare i segnali in occasione di un'azione sensibile

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. Validare lato server

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 Lato Client

Collector (singleton)

import Collector from './collector/Collector';
// oppure via globale: BotDetect.collector

Metodo	Restituisce	Descrizione
getInstance(config?)	Collector	Accessor singleton
configure(config)	void	Aggiorna la configurazione a runtime
getConfig()	CollectorConfig	Configurazione corrente
init()	void	Inizializzazione lazy di trappole, tracciamento, honeypot
enableTraps()	void	Installa trappole per stack trace sulle API DOM
enableBehavioralTracking()	void	Avvia il monitoraggio di mouse/tastiera/scorrimento
enableHoneypots(container?)	void	Installa campi honeypot
collect()	Promise<DetectionResult[]>	Esegue tutti i rilevamenti
setNonce(nonce)	void	Memorizza il nonce emesso dal server
getSessionId()	string	Identificatore univoco di sessione
getFingerprint()	string	Hash dell'impronta di sessione
resetBehavioralData()	void	Cancella i dati comportamentali
destroy()	void	Pulisce tutti i listener e gli elementi DOM

Detector (solo debug)

import Detector from './detector/Detector';

Metodo	Restituisce	Descrizione
getInstance(config?)	Detector	Accessor singleton
configure(config)	void	Aggiorna la configurazione
analyze(results)	DetectionVerdict	Calcola punteggio + classifica (solo debug locale)
handleError(error)	DetectionVerdict	Verdetto di fallback in caso di errore

Attenzione: analyze() viene eseguito interamente nel browser. Non utilizzare mai il suo output per decisioni in produzione.

Tipi

interface DetectionResult {
  name: string;      // Nome del modulo
  score: number;     // 0.0 – 1.0
  weight: number;    // 1 – 10 (importanza)
  detail?: string;   // Descrizione leggibile dall'uomo
}

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