bot-detection
v0.2.4
Published
Zero‑config client bot detector that sets an 'isbot' cookie.
Downloads
157
Maintainers
sai_krishna_mReadme
bot-detection
Zero‑config client bot detector. Import it once, and it sets a cookie isbot to true (bot) or false (human). No server, no telemetry, no configuration required.
Features
- One‑liner: just import and it sets
isbotcookie - Heuristics: user agent headless/bot keywords,
navigator.webdriver, empty languages/plugins - Light interaction sampling (2s): if the user interacts, cookie flips to
false
Install
npm install bot-detectionUsage (React, Vite, CRA, Next.js client component)
- Import once in your client entry or root layout:
import 'bot-detection/auto'; // sets document.cookie isbot=true|false- Read the cookie anywhere:
function getCookie(name: string) {
return document.cookie
.split(';')
.map(s => s.trim())
.find(s => s.startsWith(name + '='))?.split('=')[1];
}
const isBot = getCookie('isbot') === 'true';- Optional: stricter detection or debug logging (set before import):
;(window as any).__BOT_DETECTION__ = {
// Lower the threshold and raise flip requirements
strict: true, // default false
threshold: 0.5, // default 0.6 (0..1)
debug: true, // logs score and reasons to console
};
import 'bot-detection/auto';React (CRA/Vite) placement
- CRA: add the import at the top of
src/index.tsxorsrc/index.jsx. - Vite: add the import at the top of
src/main.tsxorsrc/main.jsx. - It must run in the browser; do not import it in Node/server code.
Next.js
- App Router (app/): create a tiny client component and include it in
app/layout.tsx.
// app/bot-detect-client.tsx
'use client'
import 'bot-detection/auto'
export default function BotDetectClient(){ return null }// app/layout.tsx
import BotDetectClient from './bot-detect-client'
export default function RootLayout({ children }){
return (
<html><body>
<BotDetectClient />
{children}
</body></html>
)
}Troubleshooting
- Not seeing the
isbotcookie:- Ensure the import runs on the client (open DevTools Console and run
document.cookie). - Disable strict privacy/extensions that block cookies for
localhost. - The cookie is not HttpOnly; check DevTools → Application → Cookies.
- Wait ~2 seconds after page load; interaction sampling may flip it to
false.
- Ensure the import runs on the client (open DevTools Console and run
- Seeing
POST /api/bot/telemetry 404in your dev server:- That means you are using an older version of this package that sent telemetry.
- Update to the latest version with zero telemetry:
npm i bot-detection@latest. - Also remove any older setup that sets
window.__BOT_DETECTION__or manually posts to/api/bot/telemetry.
Notes
- Cookie name:
isbot, value'true' | 'false' - Detection runs immediately; after ~2 seconds, if user interacts (mouse/keys/touch), cookie is forced to
'false' - Import only on the client (e.g., within a Next.js client component)
Limitations (and what we check)
- Heuristics are lightweight and can be bypassed by sophisticated bots.
- Legit environments (privacy modes) can trigger signals; we keep their weights small.
- Signals used:
- User‑Agent headless/automation keywords
navigator.webdriver- Empty
navigator.languages/navigator.plugins - UA mobile vs
maxTouchPointsmismatch (small weight) hardwareConcurrency <= 1(small weight)- Chrome UA without
window.chrome(small weight) devicePixelRatio === 1with very large width (tiny weight)
- Treat it as a quick client hint, not a sole security control.
Why a proxied Chromium (e.g., via Burp) may read as human
- Proxies operate at the network layer; client‑side heuristics only see browser APIs and behavior.
- To treat such traffic as bots client‑side, enable
strictand lowerthreshold, but expect more false positives. - For robust proxy detection, add server‑side checks (TLS/JA3, header anomalies, IP reputation) in your app.