New Research: Supply Chain Attack on Axios Pulls Malicious Dependency from npm.Details →
Socket
Book a DemoSign in
Socket

bot-detection

Package Overview
Dependencies
Maintainers
1
Versions
12
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

bot-detection

Zero‑config client bot detector that sets an 'isbot' cookie.

latest
npmnpm
Version
0.2.4
Version published
Maintainers
1
Created
Source

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 isbot cookie
  • 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-detection

Usage (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.tsx or src/index.jsx.
  • Vite: add the import at the top of src/main.tsx or src/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 isbot cookie:
    • 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.
  • Seeing POST /api/bot/telemetry 404 in 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 maxTouchPoints mismatch (small weight)
    • hardwareConcurrency <= 1 (small weight)
    • Chrome UA without window.chrome (small weight)
    • devicePixelRatio === 1 with 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 strict and lower threshold, but expect more false positives.
  • For robust proxy detection, add server‑side checks (TLS/JA3, header anomalies, IP reputation) in your app.

Keywords

bot

FAQs

Package last updated on 21 Nov 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts