@axeptio/behavior-detection
v1.1.0
Published
Lightweight behavior detection library to assess human likelihood of user sessions
Readme
@axeptio/behavior-detection
Lightweight, privacy-first behavior detection library to distinguish human users from automated bots
A sophisticated JavaScript library that analyzes user behavior patterns to determine if interactions are human-like or bot-like. Unlike traditional CAPTCHA systems, this library works silently in the background, providing a seamless user experience while offering robust bot detection capabilities.
✨ Features
- 🎯 High Accuracy: Multi-strategy detection approach with configurable weights
- 🤖 Automation Detection: Immediate detection of
navigator.webdriver, headless browsers, and automation frameworks - 🌲 Tree-shakeable: Import only the strategies you need
- 🚀 Zero Dependencies: Lightweight and fast (< 15KB minified)
- 📱 Cross-platform: Works on desktop and mobile browsers
- 🔒 Privacy-first: All processing happens client-side, no data sent to servers
- ⚡ Real-time: Continuously monitors and scores user behavior
- 🎨 Framework Agnostic: Works with vanilla JS, React, Vue, Angular, etc.
- 📦 Multiple Build Formats: ESM, CommonJS, and IIFE (browser CDN)
- 🧪 Battle-tested: Comprehensive adversarial testing against Playwright, Puppeteer, and Selenium
🎬 Demo

Try the interactive test harness locally:
npm run trymeThis will build the library and open the comprehensive test harness in your browser, showing real-time detection scores and visualizations as you interact with the page.
Demo Files:
demos/test-harness.html- Full-featured interactive test harness with real-time graphsdemos/browser-demo.html- Simple CDN usage example with auto-initializationdemos/example.html- Strategy-based usage example with detailed visualizations
📦 Installation
NPM/Yarn
npm install @axeptio/behavior-detection
# or
yarn add @axeptio/behavior-detectionCDN (Browser)
<script src="https://static.axept.io/behavior-detector.latest.js"></script>🚀 Quick Start
Strategy-based Usage (Recommended)
Import only the strategies you need for optimal bundle size:
import {
BehaviorDetector,
Mouse,
Click,
Keyboard,
Environment,
Timing,
Visibility
} from '@axeptio/behavior-detection';
const detector = new BehaviorDetector()
.addStrategy(new Mouse())
.addStrategy(new Click())
.addStrategy(new Keyboard())
.addStrategy(new Environment()) // Detects automation frameworks
.addStrategy(new Timing()) // Detects machine-like timing
.addStrategy(new Visibility()); // Detects hidden tab actions
// Start tracking
detector.start();
// Get score (0 = bot-like, 1 = human-like)
const result = await detector.score({ breakdown: true });
console.log('Human likelihood:', result.score);
console.log('Breakdown:', result.breakdown);
// Stop tracking when done
detector.stop();Browser CDN Usage
<!DOCTYPE html>
<html>
<head>
<title>Bot Detection Demo</title>
</head>
<body>
<h1>Interact with this page</h1>
<button>Click me</button>
<input type="text" placeholder="Type something...">
<script src="https://static.axept.io/behavior-detector.latest.js"></script>
<script>
// Configure before the script loads (or call init after)
window.bdSettings = {
autoStart: true,
checkMs: 2000, // Check every 2 seconds
onScore: (result) => {
console.log('Score:', result.score);
},
ifBot: (result) => {
console.warn('Bot detected!', result.score);
// Take action: show CAPTCHA, limit features, etc.
},
ifHuman: (result) => {
console.log('Human confirmed!', result.score);
},
botThreshold: 0.3, // Below this = bot
humanThreshold: 0.7 // Above this = human
};
</script>
</body>
</html>Framework Examples
React
import { useEffect, useRef } from 'react';
import { BehaviorDetector, Mouse, Click, Scroll } from '@axeptio/behavior-detection';
function App() {
const detectorRef = useRef<BehaviorDetector>();
useEffect(() => {
const detector = new BehaviorDetector()
.addStrategy(new Mouse())
.addStrategy(new Click())
.addStrategy(new Scroll());
detector.start();
detectorRef.current = detector;
// Check score periodically
const interval = setInterval(async () => {
const result = await detector.score();
if (result.score < 0.3) {
console.warn('Bot detected!');
// Show CAPTCHA or take other action
}
}, 3000);
return () => {
clearInterval(interval);
detector.stop();
};
}, []);
return <div>Your app content</div>;
}Vue
<template>
<div>Your app content</div>
</template>
<script setup>
import { onMounted, onUnmounted } from 'vue';
import { BehaviorDetector, Mouse, Click, Scroll } from '@axeptio/behavior-detection';
let detector;
let checkInterval;
onMounted(() => {
detector = new BehaviorDetector()
.addStrategy(new Mouse())
.addStrategy(new Click())
.addStrategy(new Scroll());
detector.start();
checkInterval = setInterval(async () => {
const result = await detector.score();
if (result.score < 0.3) {
console.warn('Bot detected!');
}
}, 3000);
});
onUnmounted(() => {
clearInterval(checkInterval);
detector?.stop();
});
</script>🎯 Detection Strategies
The library uses multiple autonomous detection strategies, each analyzing different aspects of user behavior:
🖱️ Mouse Strategy
Weight: 0.30 (default)
Analyzes mouse movement patterns for human-like characteristics:
- Velocity Variation: Humans have natural acceleration/deceleration (CV ~0.8-1.2)
- Direction Changes: Organic curves vs. linear interpolation
- Movement Smoothness: Natural micro-corrections vs. perfect paths
- Entry Point Analysis: Where mouse enters the viewport
- Micro-movement Detection: Natural hand tremor (1-5px jitter)
import { MouseStrategy } from '@axeptio/behavior-detection';
const mouse = new MouseStrategy({
rollingWindow: 5000 // Keep last 5 seconds of data
});
detector.addStrategy(mouse, 0.30); // Custom weightBot Indicators:
- Constant velocity movements
- Perfect straight lines or curves
- Instant position jumps
- No micro-corrections or hand tremor
- Entry at (0,0) or exact viewport center
- No micro-movements (1-5px) before actions
👆 Click Strategy
Weight: 0.30 (default)
Monitors click positioning accuracy and timing on interactive elements:
import { ClickStrategy } from '@axeptio/behavior-detection';
const click = new ClickStrategy({
targetSelectors: ['button', 'a', '[role="button"]']
});
detector.addStrategy(click);
// Add custom targets dynamically
click.addTarget('.custom-clickable');Detection Patterns:
- ✅ Human: Mouse positioned over element before click
- ⚠️ Suspicious: Click at exact center (pixel-perfect)
- ❌ Bot: Click without mouse movement or mouse outside element
Enhanced Detection (v1.1+):
| Signal | Human | Bot |
|--------|-------|-----|
| Mouse-click position delta | 0px (exact match) | > 5px (mismatched) |
| Time since last mousemove | 50-300ms | < 10ms or > 2000ms |
| isTrusted event property | true | false (programmatic) |
Bots using element.click() often have click event coordinates that don't match the last mouse position, which is a strong indicator of programmatic clicks.
📜 Scroll Strategy
Weight: 0.15 (default)
Analyzes scrolling behavior patterns:
import { ScrollStrategy } from '@axeptio/behavior-detection';
const scroll = new ScrollStrategy({
rollingWindow: 5000
});Bot Indicators:
- Identical scroll distances (smoking gun)
- Instant jumps (programmatic scrollTo)
- Too consistent velocity
- No natural acceleration/deceleration
⌨️ Keyboard Strategy
Weight: 0.10 (default)
Examines typing patterns and timing:
import { KeyboardStrategy } from '@axeptio/behavior-detection';
const keyboard = new KeyboardStrategy({
targetSelectors: ['input[type="text"]', 'textarea']
});
// Add custom input targets
keyboard.addTarget('#custom-input');Detection Factors:
- Keystroke interval variation (natural human timing has CV ~0.4-0.6)
- Key press duration variance
- Backspace usage (error correction = human)
- Too fast/instant key releases (<5ms = bot)
📱 Tap Strategy (Mobile)
Weight: 0.35 (mobile default)
Mobile-specific touch interaction detection:
import { TapStrategy } from '@axeptio/behavior-detection';
const tap = new TapStrategy({
targetSelectors: ['button', 'a']
});Analyzes:
- Touch pressure patterns
- Tap duration and timing
- Multi-touch gestures
🌐 Environment Strategy
Weight: 0.08 (default)
Fingerprints browser environment for automation indicators. This strategy provides immediate bot detection for the most reliable automation signals.
import { EnvironmentStrategy } from '@axeptio/behavior-detection';
const env = new EnvironmentStrategy();
// Check if automation is detected
if (env.isLikelyBot()) {
console.warn('Automation detected!');
}
// Get detailed automation indicators
const indicators = env.getAutomationIndicators();
console.log(indicators);
// {
// isWebdriver: true, // navigator.webdriver === true
// hasHeadlessUA: false, // HeadlessChrome in user agent
// hasChromelessRuntime: true, // Chrome without chrome.runtime
// hasSoftwareRenderer: false, // SwiftShader WebGL renderer
// hasAutomationGlobals: false, // Selenium, Phantom, etc. globals
// hasCDPInjection: false, // Chrome DevTools Protocol injection
// ...
// }Immediate Disqualification Signals (returns very low scores):
| Signal | Score | Description |
|--------|-------|-------------|
| navigator.webdriver === true | 0.05 | Most reliable automation indicator |
| Automation globals detected | 0.10 | Selenium, Phantom, Nightmare, etc. |
| CDP injection (cdc_* properties) | 0.10 | Chrome DevTools Protocol |
| Multiple headless indicators | 0.15 | Combined headless signals |
| HeadlessChrome in user agent | 0.20 | Explicit headless mode |
Automation Globals Detected:
__selenium_evaluate,__webdriver_evaluate,__driver_evaluate_phantom,callPhantom,__nightmare_Selenium_IDE_Recorder,domAutomation,domAutomationController- And more...
Additional Checks:
- Suspicious dimensions (800x600, 1024x768)
- Missing browser features (WebGL, localStorage)
- Plugin/MIME type inconsistencies
- Software WebGL renderer (SwiftShader)
- Chrome without
chrome.runtime(headless indicator)
📐 Resize Strategy
Weight: 0.02 (default)
Monitors window resize behavior:
import { ResizeStrategy } from '@axeptio/behavior-detection';
const resize = new ResizeStrategy();Detects:
- Programmatic resizing patterns
- Suspicious resize timing
- Mouse position during resize
⏱️ Timing Strategy
Weight: 0.15 (default)
Analyzes timing patterns in user interactions to detect bot-like precision:
import { TimingStrategy } from '@axeptio/behavior-detection';
const timing = new TimingStrategy();Detection Signals:
| Signal | Human Behavior | Bot Behavior | |--------|---------------|--------------| | Pre-action stillness | Micro-movements (1-5px tremor) | Perfect stillness | | Mouse-to-click delay | 50-300ms with variation | 0-10ms (instant) | | Action intervals | Variable timing | Machine-precise (100ms, 500ms, 1000ms) | | Hidden tab actions | None (can't interact) | Continues while hidden |
Bot Indicators:
- Zero mouse movement before clicks (perfect stillness)
- Suspiciously consistent action intervals (CV < 0.15)
- Actions at machine-precise intervals (multiples of 100ms, 500ms)
- Any actions while
document.hidden === true
👁️ Visibility Strategy
Weight: 0.10 (default)
Monitors tab visibility and focus patterns:
import { VisibilityStrategy } from '@axeptio/behavior-detection';
const visibility = new VisibilityStrategy();Detection Signals:
| Signal | Human Behavior | Bot Behavior | |--------|---------------|--------------| | Actions while hidden | Impossible | Continues normally | | Resume delay | 100-500ms to refocus | Instant (< 50ms) | | Focus-to-type delay | 100-500ms natural delay | Instant (< 20ms) |
Bot Indicators:
- Actions occurring while
document.hidden === true - Instant activity resume when tab becomes visible
- Typing immediately after focus without human reaction time
📊 API Reference
BehaviorDetector
Main class for managing detection strategies.
Constructor
constructor(options?: TickOptions)Options:
interval?: number- Tick interval in milliseconds (default: 1000)pauseOnHidden?: boolean- Automatically pause detection when tab is hidden (default: true)
Methods
addStrategy(strategy: DetectionStrategy, weight?: number): this
Add a detection strategy with optional custom weight.
detector.addStrategy(new Mouse(), 0.35);removeStrategy(name: string): this
Remove a strategy by name.
detector.removeStrategy('mouse');setStrategyEnabled(name: string, enabled: boolean): this
Enable or disable a strategy without removing it.
detector.setStrategyEnabled('mouse', false);start(): void
Start all enabled strategies.
detector.start();stop(): void
Stop all strategies and cleanup listeners.
detector.stop();reset(): void
Clear all collected data without stopping.
detector.reset();score(options?: ScoreOptions): Promise<ScoreResult>
Calculate the human likelihood score.
const result = await detector.score({
breakdown: true, // Include per-strategy scores
});ScoreOptions:
breakdown?: boolean- Include detailed breakdown of each strategy
ScoreResult:
{
score: number; // 0-1 (0=bot, 1=human)
breakdown?: {
overall: number;
factors: {
mouse?: number;
click?: number;
scroll?: number;
keyboard?: number;
environment?: number;
// ...
};
weights: {
mouse: number;
click: number;
// ...
};
};
}isActive(): boolean
Check if detector is currently tracking.
if (detector.isActive()) {
console.log('Detector is running');
}isPaused(): boolean
Check if detector is currently paused due to tab visibility.
if (detector.isPaused()) {
console.log('Detector is paused (tab hidden)');
}Note: A detector can be both active and paused. When the tab is hidden with pauseOnHidden: true, the detector remains active but is temporarily paused.
getEventCount(): Record<string, number>
Get event counts from all strategies.
getStrategyDebugInfo(): Record<string, any>
Get debug information from all strategies.
destroy(): void
Complete cleanup and remove all strategies.
detector.destroy();⚙️ Configuration
Strategy Weights
Customize how much each strategy contributes to the final score:
const detector = new BehaviorDetector()
.addStrategy(new Mouse(), 0.40) // 40% weight
.addStrategy(new Click(), 0.35) // 35% weight
.addStrategy(new Scroll(), 0.15) // 15% weight
.addStrategy(new Keyboard(), 0.10); // 10% weightDesktop vs Mobile
The library automatically adjusts strategies based on device type:
Desktop (default):
- Mouse: 0.30
- Click: 0.30
- Scroll: 0.15
- Keyboard: 0.10
- Environment: 0.08
- Resize: 0.02
Mobile (automatic):
- Tap: 0.35 (replaces click)
- Scroll: 0.35 (increased)
- Keyboard: 0.15
- Environment: 0.10
- Resize: 0.05
Tick Interval
Control how often strategies receive tick updates:
const detector = new BehaviorDetector({
interval: 500 // Check every 500ms
});Automatic Pause on Hidden Tab
By default, the detector automatically pauses when the browser tab becomes hidden (using the Page Visibility API) and resumes when the tab becomes visible again. This provides several benefits:
- Better Performance: Saves CPU cycles when the tab isn't visible
- Battery Life: Reduces power consumption on mobile devices
- Accuracy: Avoids collecting misleading data from background tabs
// Default: pause on hidden (recommended)
const detector = new BehaviorDetector({
pauseOnHidden: true // Default
});
// Disable if you need to track background behavior
const detector = new BehaviorDetector({
pauseOnHidden: false
});
// Check if currently paused
if (detector.isPaused()) {
console.log('Detection is paused (tab hidden)');
}Browser CDN Usage:
window.bdSettings = {
autoStart: true,
pauseOnHidden: true, // Default: true
// ... other settings
};The detector remains "active" (via isActive()) while paused, but strategies and tick updates are temporarily stopped until the tab becomes visible again. All collected data is preserved during the pause.
🎨 Browser Support
- ✅ Chrome/Edge 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Mobile Safari (iOS 14+)
- ✅ Chrome Mobile (Android 90+)
🧪 Testing & Validation
The library includes comprehensive adversarial testing against popular automation frameworks:
Run All Tests
npm run test:adversarialIndividual Framework Tests
# Test against Playwright
npm run test:playwright
# Test against Puppeteer
npm run test:puppeteer
# Test against Selenium
npm run test:selenium
# Stress test (extensive scenarios)
npm run test:stressTest Scenarios
Each framework is tested with:
- Bot-like behavior - Rapid actions, no delays (expected: score < 0.4)
- Human-like behavior - Natural delays and movements (expected: score > 0.6)
- Stealth mode - Automation with evasion techniques
- Headless vs Headed - Different browser modes
See tests/adversarial/README.md for detailed testing documentation.
🏗️ Architecture
Strategy Pattern
Each detection strategy is a fully autonomous module:
interface DetectionStrategy {
readonly name: string;
readonly defaultWeight: number;
start(): void; // Register listeners
stop(): void; // Cleanup
reset(): void; // Clear data
score(): number | undefined; // Calculate score
onTick?(timestamp: number): void; // Optional polling
getDebugInfo?(): any; // Optional debug data
}Benefits:
- 🌲 Tree-shakeable (import only what you need)
- 🔌 Fully autonomous (manages own listeners and state)
- 🎯 Single responsibility
- 🧩 Easy to extend with custom strategies
Mathematical Scoring
Uses smooth mathematical functions instead of magic numbers:
import { gaussian, sigmoid, inverseSigmoid } from './math-utils';
// Gaussian: ideal value with symmetric falloff
score = gaussian(actualCV, idealCV, width);
// Sigmoid: smooth 0-1 mapping
score = sigmoid(value, midpoint, steepness);
// Inverse sigmoid: penalize high values
score = inverseSigmoid(value, midpoint, steepness);📈 Performance
- Minimal CPU Impact: Sampling and rolling windows prevent data buildup
- Memory Efficient: ~1-2MB typical memory usage
- No Network Calls: Everything runs client-side
- Async Scoring: Non-blocking score calculations
🔐 Privacy & Security
- ✅ Client-side only: No data transmitted to servers
- ✅ No PII collected: Only behavioral patterns (no keystrokes content)
- ✅ GDPR friendly: No cookies, no tracking, no storage
- ✅ Transparent: Open source and auditable
🛠️ Development
Build
# Build all formats (ESM, CJS, IIFE)
npm run build:all
# Build only ESM/CJS
npm run build
# Build browser bundle
npm run build:browserProject Structure
behavior-detection/
├── src/
│ ├── behavior-detector.ts # Main detector class
│ ├── strategy.ts # Strategy interface
│ ├── types.ts # TypeScript types
│ ├── math-utils.ts # Mathematical functions
│ ├── browser.ts # Browser CDN wrapper
│ └── strategies/
│ ├── mouse.ts # Mouse movement + entry point detection
│ ├── click.ts # Click accuracy + position delta
│ ├── scroll.ts # Scroll behavior detection
│ ├── keyboard.ts # Keyboard timing detection
│ ├── tap.ts # Mobile tap detection
│ ├── environment.ts # Automation + headless detection
│ ├── timing.ts # Action timing patterns
│ ├── visibility.ts # Tab visibility behavior
│ └── resize.ts # Window resize detection
├── dist/ # Build output
├── demos/
│ ├── test-harness.html # Interactive testing UI with graphs
│ ├── browser-demo.html # CDN usage example
│ └── example.html # Strategy-based usage example
├── tests/
│ └── adversarial/ # Automation framework tests
└── docs/ # Documentation assetsScripts
npm run build # Build library (ESM + CJS)
npm run build:all # Build all formats
npm run build:browser # Build browser IIFE bundle
npm run clean # Clean dist directory
npm run tryme # Build and start demo server
npm run deploy # Deploy to CDN (AWS S3/CloudFront)
npm run test # Run basic tests
npm run test:adversarial # Run all adversarial tests
npm run test:stress # Stress test with extensive scenarios🤝 Contributing
Contributions are welcome! This library can be extended with:
- New strategies: Add detection for new behavioral patterns
- Improved algorithms: Enhance existing detection logic
- Mobile optimizations: Better touch/gesture detection
- Performance improvements: Reduce overhead
- Test coverage: Add more adversarial test scenarios
Creating Custom Strategies
import { DetectionStrategy } from '@axeptio/behavior-detection';
export class CustomStrategy implements DetectionStrategy {
readonly name = 'custom';
readonly defaultWeight = 0.10;
private data: any[] = [];
private listener: any;
start(): void {
this.listener = (e: Event) => {
// Collect data
this.data.push(/* ... */);
};
document.addEventListener('someevent', this.listener);
}
stop(): void {
if (this.listener) {
document.removeEventListener('someevent', this.listener);
}
}
reset(): void {
this.data = [];
}
score(): number | undefined {
if (this.data.length < 5) return undefined;
// Calculate and return score (0-1)
return 0.85;
}
getDebugInfo() {
return {
eventCount: this.data.length,
data: this.data
};
}
}📝 Use Cases
- Form Protection: Detect automated form submissions
- Account Security: Identify credential stuffing attacks
- E-commerce: Prevent inventory hoarding bots
- Analytics: Filter bot traffic from user metrics
- Rate Limiting: Adaptive limits based on behavior
- A/B Testing: Exclude bots from experiments
- Progressive CAPTCHAs: Only show CAPTCHA to suspicious users
🎯 Detection Thresholds
Recommended score interpretation:
| Score Range | Interpretation | Action | |-------------|---------------|--------| | 0.8 - 1.0 | Very likely human | Full access | | 0.6 - 0.8 | Probably human | Monitor | | 0.3 - 0.6 | Suspicious | Add friction (CAPTCHA) | | 0.0 - 0.3 | Very likely bot | Block or severely limit |
Note: Thresholds should be tuned based on your specific use case and acceptable false positive rate.
⚠️ Limitations
- Not foolproof: Sophisticated bots with human-like behavior can evade detection
- Initial period: Requires user interaction to build confidence
- False positives: Accessibility tools, keyboard-only navigation may score lower
- Context matters: Some legitimate use cases (automation testing, scripts) will be flagged
Best Practice: Use as one layer in a defense-in-depth strategy, not as the sole security measure.
📄 License
Proprietary © Axeptio
🙏 Acknowledgments
- Inspired by research in behavioral biometrics and bot detection
- Built with TypeScript for type safety
- Tested against real-world automation frameworks
- Mathematical approach based on statistical pattern recognition
Made with ❤️ by Axeptio
