bot-signal : je l’ai testé contre des bots réels

bot-signal est une librairie TypeScript de détection de bots, pensée pour le navigateur et Node.js. Après un vrai essai avec Chromium headless, des marqueurs Playwright, un scénario comportemental scripté et des requêtes serveur suspectes, mon verdict est simple : ça vaut l’essai si vous voulez des signaux explicables sans dépendre d’un SaaS externe.

bot-signal, c’est quoi ?

bot-signal est un toolkit anti-bot open source. Il ne promet pas une vérité absolue sur l’humain derrière l’écran, il calcule un score de suspicion à partir de plusieurs couches :

• signaux instantanés côté navigateur, comme navigator.webdriver, HeadlessChrome, WebGL logiciel, objets Playwright ou Puppeteer oubliés
• signaux comportementaux, comme souris trop linéaire, frappe trop régulière, scroll mécanique, événements synthétiques
• signaux serveur, comme IP de datacenter, User-Agent de script, JA3 suspect, timezone incohérente, headers navigateur manquants

Ce positionnement me plaît, parce qu’il ressemble plus à une boîte à outils de scoring qu’à une boîte noire. Chaque signal a un nom, un poids et un niveau de confiance. Pour une équipe sécu ou DevOps, c’est souvent plus utile qu’un verdict magique impossible à expliquer au support client.

Point testé	Résultat observé
Version du dépôt	commit db3e7b5, package 2.0.3
Runtime demandé	Node.js 22 ou plus
Installation	npm ci, puis build TypeScript
Tests unitaires	168 tests passés
Tests navigateur Patchright	52 passés, 1 test headed ignoré en CI
UI de démo	servie localement puis capturée en Chromium headless
Clé API	aucune, pas de LLM requis

Installation de bot-signal

J’ai commencé par cloner le dépôt dans /tmp, lire le README, le package.json et les tests. Premier détail important : le package demande Node.js 22. Mon conteneur avait Node 20 par défaut, donc j’ai lancé les scripts avec un binaire Node 22.

Autre détail très concret : /tmp était monté en noexec, ce qui a cassé l’installation d’esbuild dans node_modules. J’ai donc gardé le clone de référence dans /tmp, puis j’ai exécuté l’installation dans une copie temporaire sur un volume exécutable. C’est un problème de sandbox, pas de bot-signal.

Les commandes utiles ressemblent à ça :

git clone https://github.com/okasi/bot-signal.git /tmp/bot-signal
cd /tmp/bot-signal
npm ci
npm run typecheck
npm run test
npm run build

Avec Node 22 et un dossier exécutable, le socle passe proprement : typecheck OK, 168 tests unitaires OK, build ESM, CJS et types OK.

Pour la partie navigateur, j’ai installé le Chromium attendu par Patchright, puis relancé les tests dédiés. Sans écran X, le test headed échoue comme prévu. En mode CI, il est ignoré et la suite passe : 52 tests passés, 1 ignoré.

npx patchright install --with-deps chromium
CI=true npm run test:patchright

bot-signal à l’usage

Je n’ai pas voulu me limiter à un npm test. J’ai monté un mini scénario avec trois axes.

Premier axe : la démo web générée par le projet. Je l’ai servie localement, ouverte dans Chromium headless via Patchright, puis j’ai exécuté detectInstantClient(window) dans la page. Résultat sur mon Chromium headless : isLegitClient: false, score 0.986, confiance haute. Les signaux déclenchés étaient parlants : isHeadless, isSoftwareRenderer, isMissingChromeObject, isSuspiciousWindowDimensions et isEmptyPlugins.

Ensuite, j’ai injecté un marqueur Playwright dans la page, window.__playwright__binding__. Le score est monté à 1.000, avec automation.kind: playwright. C’est le comportement que j’attendais : quand un artefact explicite existe, bot-signal ne reste pas dans le flou.

Deuxième axe : le comportement. J’ai créé un échantillon de session avec 16 mouvements de souris parfaitement alignés, 8 scrolls identiques, 9 frappes à intervalle fixe et un clic synthétique. La librairie a retourné isLegitClient: false, score 0.829, confiance haute. Les signaux déclenchés : linear-mouse-movement, linear-scroll, linear-typing, synthetic-events.

Troisième axe : le serveur. J’ai testé trois contextes :

• curl/8.7.1 depuis une plage AWS, score 0.863, détecté comme curl
• User-Agent Chrome depuis AWS, timezone Paris, JA3 marqué suspect, score 0.971
• Google DNS avec headers navigateur cohérents, score 0.45, encore considéré légitime au seuil par défaut

Ce dernier cas est intéressant. Une seule incohérence de timezone ne suffit pas à bloquer. C’est sain, parce qu’un VPN ou un déplacement peut produire ce genre de bruit.

Est-ce que bot-signal marche vraiment ?

Sur les cas évidents, oui. Headless Chromium est repéré. Un artefact Playwright explicite est repéré. Un comportement robotique caricatural est repéré. Un User-Agent curl est attribué correctement.

Ce que j’apprécie surtout, c’est que le score n’est pas binaire dès qu’un signal faible apparaît. Le cas Google DNS avec timezone suspecte reste légitime au seuil par défaut. C’est exactement le genre de nuance qu’il faut en production, sinon votre anti-bot devient un générateur de faux positifs.

Il faut quand même rester lucide. Un bot moderne peut durcir son navigateur, lisser ses mouvements, passer par une IP résidentielle et aligner timezone, locale et headers. bot-signal ne remplace pas une défense complète avec rate limiting, challenge adaptatif, logs, réputation applicative et règles métier.

Ce que j’aime dans bot-signal

J’aime la lisibilité. Les noms de signaux sont suffisamment clairs pour écrire une règle, une alerte ou une explication au support.

J’aime aussi le fait que le package fonctionne sans clé API. Les listes IP et la GeoIP sont embarquées, ce qui évite d’envoyer chaque requête à un service tiers. Pour un site à trafic modéré, c’est simple à opérer.

Le double usage browser et Node est bien vu. Côté client, on peut faire un premier tri. Côté serveur, on peut recouper avec l’IP, les headers et les empreintes TLS fournies par un reverse proxy de confiance.

Enfin, les tests sont sérieux pour un petit projet. Les scénarios Patchright couvrent des injections Playwright, ChromeDriver, Selenium, PhantomJS, des comportements linéaires et des cas d’évasion.

Les limites de bot-signal

La première limite est l’environnement. Le package demande Node 22, ce qui peut obliger à mettre à jour des stacks encore en Node 20 LTS côté applicatif.

La deuxième limite concerne le TLS. bot-signal sait utiliser un JA3 ou JA4, mais il ne peut pas l’inventer. Il faut que votre edge ou votre reverse proxy calcule l’empreinte et l’injecte dans un header interne fiable. Si vous acceptez un header JA3 envoyé directement par le client, il ne vaut rien.

La troisième limite est le risque de surinterprétation. Une IP de datacenter n’est pas forcément un bot hostile. Une timezone incohérente n’est pas forcément une fraude. Il faut traiter ces signaux comme des pondérations, pas comme des preuves judiciaires.

Faut-il adopter bot-signal ?

Mon verdict : essayer, puis adopter si vous avez besoin d’un scoring anti-bot léger et explicable dans une application TypeScript.

Je le vois bien sur un formulaire public, une page de login, une API d’inscription, une file d’attente, un back-office exposé ou un blog qui subit du scraping agressif. Je ne le mettrais pas seul devant un système critique, mais je l’ajouterais volontiers comme couche de signal dans une stratégie plus large.

Pour un freelance sécu ou DevOps, c’est une bonne brique : facile à lire, facile à tester, assez transparente pour être auditée, et suffisamment concrète pour produire de vrais signaux dès le premier run.

FAQ

bot-signal bloque-t-il automatiquement les visiteurs ?

Non. La librairie retourne un score, des signaux et un verdict isLegitClient. C’est à vous de décider si vous bloquez, challengez, logguez ou laissez passer.

bot-signal détecte-t-il Playwright et Puppeteer ?

Oui, quand des artefacts sont visibles, et il repère aussi des symptômes plus génériques comme HeadlessChrome ou un rendu logiciel. Un Playwright bien durci peut toutefois réduire ces traces.

bot-signal remplace-t-il Cloudflare Bot Management ?

Non. C’est une librairie applicative open source, pas une plateforme complète de protection edge. Elle est utile pour enrichir vos décisions, surtout si vous voulez garder la logique dans votre code.