@niksbanna/bot-detector 1.0.0

package/src/signals/behavior/MouseMovementSignal.js

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Detects non-human mouse movement patterns.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Tracks and analyzes mouse movement patterns.
+ * Bots often have perfectly linear paths, no movement, or teleportation.
+ */
+class MouseMovementSignal extends Signal {
+  static id = 'mouse-movement';
+  static category = 'behavior';
+  static weight = 0.9;
+  static description = 'Detects non-human mouse movement patterns';
+  static requiresInteraction = true;
+
+  constructor(options = {}) {
+    super(options);
+    this._movements = [];
+    this._isTracking = false;
+    this._trackingDuration = options.trackingDuration || 3000; // Default 3 seconds
+    this._minMovements = options.minMovements || 5;
+    this._boundHandler = null;
+  }
+
+  /**
+   * Start tracking mouse movements.
+   * @returns {Promise<void>}
+   */
+  startTracking() {
+    if (this._isTracking) return;
+    
+    this._movements = [];
+    this._isTracking = true;
+    
+    this._boundHandler = (e) => {
+      this._movements.push({
+        x: e.clientX,
+        y: e.clientY,
+        t: performance.now(),
+      });
+    };
+    
+    document.addEventListener('mousemove', this._boundHandler, { passive: true });
+  }
+
+  /**
+   * Stop tracking mouse movements.
+   */
+  stopTracking() {
+    if (!this._isTracking) return;
+    
+    this._isTracking = false;
+    if (this._boundHandler) {
+      document.removeEventListener('mousemove', this._boundHandler);
+      this._boundHandler = null;
+    }
+  }
+
+  async detect() {
+    const anomalies = [];
+    let confidence = 0;
+
+    // If no tracking has occurred, check if we have movement data
+    if (this._movements.length === 0) {
+      // Start tracking for a period, then analyze
+      this.startTracking();
+      
+      await new Promise(resolve => setTimeout(resolve, this._trackingDuration));
+      
+      this.stopTracking();
+    }
+
+    const movements = this._movements;
+
+    // No mouse movements detected
+    if (movements.length < this._minMovements) {
+      anomalies.push('no-mouse-movement');
+      confidence = Math.max(confidence, 0.6);
+      return this.createResult(true, { anomalies, movements: movements.length }, confidence);
+    }
+
+    // Analyze movement patterns
+    const analysis = this._analyzeMovements(movements);
+
+    // Check for teleportation (large instant jumps)
+    if (analysis.teleportCount > 0) {
+      anomalies.push('mouse-teleportation');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for perfect linear paths
+    if (analysis.linearPathRatio > 0.9) {
+      anomalies.push('linear-path');
+      confidence = Math.max(confidence, 0.8);
+    }
+
+    // Check for constant velocity (too perfect)
+    if (analysis.velocityVariance < 0.01 && movements.length > 10) {
+      anomalies.push('constant-velocity');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for zero acceleration changes
+    if (analysis.accelerationChanges === 0 && movements.length > 10) {
+      anomalies.push('no-acceleration-variance');
+      confidence = Math.max(confidence, 0.6);
+    }
+
+    // Check for robotic timing (perfect intervals)
+    if (analysis.timingVariance < 1 && movements.length > 10) {
+      anomalies.push('robotic-timing');
+      confidence = Math.max(confidence, 0.8);
+    }
+
+    const triggered = anomalies.length > 0;
+
+    return this.createResult(triggered, {
+      anomalies,
+      movementCount: movements.length,
+      analysis,
+    }, confidence);
+  }
+
+  /**
+   * Analyze movement patterns for anomalies.
+   * @param {Array} movements - Array of movement points
+   * @returns {Object} Analysis results
+   */
+  _analyzeMovements(movements) {
+    if (movements.length < 3) {
+      return {
+        teleportCount: 0,
+        linearPathRatio: 0,
+        velocityVariance: 0,
+        accelerationChanges: 0,
+        timingVariance: 0,
+      };
+    }
+
+    let teleportCount = 0;
+    const velocities = [];
+    const angles = [];
+    const timeIntervals = [];
+
+    for (let i = 1; i < movements.length; i++) {
+      const prev = movements[i - 1];
+      const curr = movements[i];
+      
+      const dx = curr.x - prev.x;
+      const dy = curr.y - prev.y;
+      const dt = curr.t - prev.t;
+      
+      if (dt === 0) continue;
+      
+      const distance = Math.sqrt(dx * dx + dy * dy);
+      const velocity = distance / dt;
+      
+      velocities.push(velocity);
+      angles.push(Math.atan2(dy, dx));
+      timeIntervals.push(dt);
+
+      // Teleportation: large jump in very short time
+      if (distance > 300 && dt < 10) {
+        teleportCount++;
+      }
+    }
+
+    // Calculate velocity variance
+    const avgVelocity = velocities.reduce((a, b) => a + b, 0) / velocities.length;
+    const velocityVariance = velocities.reduce((acc, v) => 
+      acc + Math.pow(v - avgVelocity, 2), 0) / velocities.length;
+
+    // Calculate angle consistency (linear path detection)
+    let angleConsistency = 0;
+    if (angles.length > 1) {
+      let consistentAngles = 0;
+      for (let i = 1; i < angles.length; i++) {
+        const angleDiff = Math.abs(angles[i] - angles[i - 1]);
+        if (angleDiff < 0.1) consistentAngles++;
+      }
+      angleConsistency = consistentAngles / (angles.length - 1);
+    }
+
+    // Calculate timing variance
+    const avgInterval = timeIntervals.reduce((a, b) => a + b, 0) / timeIntervals.length;
+    const timingVariance = timeIntervals.reduce((acc, t) => 
+      acc + Math.pow(t - avgInterval, 2), 0) / timeIntervals.length;
+
+    // Count acceleration changes
+    let accelerationChanges = 0;
+    for (let i = 1; i < velocities.length; i++) {
+      if ((velocities[i] - velocities[i - 1]) * (velocities[i - 1] - (velocities[i - 2] || 0)) < 0) {
+        accelerationChanges++;
+      }
+    }
+
+    return {
+      teleportCount,
+      linearPathRatio: angleConsistency,
+      velocityVariance,
+      accelerationChanges,
+      timingVariance,
+    };
+  }
+
+  reset() {
+    super.reset();
+    this.stopTracking();
+    this._movements = [];
+  }
+}
+
+export { MouseMovementSignal };

package/src/signals/behavior/ScrollBehaviorSignal.js

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview Detects non-human scroll patterns.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Tracks and analyzes scroll behavior patterns.
+ * Detects programmatic scrolling and non-human scroll patterns.
+ */
+class ScrollBehaviorSignal extends Signal {
+  static id = 'scroll-behavior';
+  static category = 'behavior';
+  static weight = 0.5;
+  static description = 'Detects programmatic scroll patterns';
+  static requiresInteraction = true;
+
+  constructor(options = {}) {
+    super(options);
+    this._scrollEvents = [];
+    this._isTracking = false;
+    this._trackingDuration = options.trackingDuration || 3000;
+    this._boundHandler = null;
+  }
+
+  /**
+   * Start tracking scroll events.
+   */
+  startTracking() {
+    if (this._isTracking) return;
+    
+    this._scrollEvents = [];
+    this._isTracking = true;
+    
+    this._boundHandler = () => {
+      this._scrollEvents.push({
+        scrollY: window.scrollY,
+        scrollX: window.scrollX,
+        t: performance.now(),
+      });
+    };
+    
+    window.addEventListener('scroll', this._boundHandler, { passive: true });
+  }
+
+  /**
+   * Stop tracking scroll events.
+   */
+  stopTracking() {
+    if (!this._isTracking) return;
+    
+    this._isTracking = false;
+    if (this._boundHandler) {
+      window.removeEventListener('scroll', this._boundHandler);
+      this._boundHandler = null;
+    }
+  }
+
+  async detect() {
+    const anomalies = [];
+    let confidence = 0;
+
+    // Start tracking if needed
+    if (this._scrollEvents.length === 0) {
+      this.startTracking();
+      await new Promise(resolve => setTimeout(resolve, this._trackingDuration));
+      this.stopTracking();
+    }
+
+    const events = this._scrollEvents;
+
+    // No scroll events - not necessarily suspicious
+    if (events.length < 3) {
+      return this.createResult(false, {
+        reason: 'insufficient-scroll-data',
+        scrollEvents: events.length,
+      }, 0);
+    }
+
+    const analysis = this._analyzeScrollPatterns(events);
+
+    // Check for instant jumps (scrollTo without animation)
+    if (analysis.instantJumps > 0) {
+      anomalies.push('instant-scroll-jumps');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for perfectly consistent scroll speed
+    if (analysis.velocityVariance < 0.1 && events.length > 10) {
+      anomalies.push('constant-scroll-velocity');
+      confidence = Math.max(confidence, 0.6);
+    }
+
+    // Check for no momentum (instant stops)
+    if (analysis.momentumEvents === 0 && events.length > 5) {
+      anomalies.push('no-scroll-momentum');
+      confidence = Math.max(confidence, 0.5);
+    }
+
+    // Check for perfectly even scroll intervals
+    if (analysis.intervalVariance < 5 && events.length > 10) {
+      anomalies.push('robotic-scroll-timing');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for exclusively vertical or horizontal scroll
+    if (analysis.scrollDirections === 1 && Math.abs(analysis.totalScrollY) > 1000) {
+      // Could be normal, but combined with other factors is suspicious
+      if (analysis.velocityVariance < 1) {
+        anomalies.push('one-dimensional-scroll');
+        confidence = Math.max(confidence, 0.4);
+      }
+    }
+
+    // Check for scroll-to-element patterns (exact positions)
+    if (analysis.exactPositionScrolls > 2) {
+      anomalies.push('exact-position-scrolls');
+      confidence = Math.max(confidence, 0.6);
+    }
+
+    const triggered = anomalies.length > 0;
+
+    return this.createResult(triggered, {
+      anomalies,
+      scrollEventCount: events.length,
+      analysis,
+    }, confidence);
+  }
+
+  /**
+   * Analyze scroll patterns for anomalies.
+   * @param {Array} events - Array of scroll events
+   * @returns {Object} Analysis results
+   */
+  _analyzeScrollPatterns(events) {
+    if (events.length < 2) {
+      return {
+        instantJumps: 0,
+        velocityVariance: 0,
+        momentumEvents: 0,
+        intervalVariance: 0,
+        scrollDirections: 0,
+        totalScrollY: 0,
+        exactPositionScrolls: 0,
+      };
+    }
+
+    let instantJumps = 0;
+    let momentumEvents = 0;
+    const velocities = [];
+    const intervals = [];
+    let hasVertical = false;
+    let hasHorizontal = false;
+    let exactPositionScrolls = 0;
+
+    // Common scroll targets (element heights, percentages)
+    const commonPositions = [0, 100, 200, 300, 400, 500, 600, 800, 1000];
+
+    for (let i = 1; i < events.length; i++) {
+      const prev = events[i - 1];
+      const curr = events[i];
+      
+      const dy = curr.scrollY - prev.scrollY;
+      const dx = curr.scrollX - prev.scrollX;
+      const dt = curr.t - prev.t;
+      
+      intervals.push(dt);
+
+      if (Math.abs(dy) > 0) hasVertical = true;
+      if (Math.abs(dx) > 0) hasHorizontal = true;
+
+      if (dt === 0) continue;
+
+      const velocity = Math.sqrt(dy * dy + dx * dx) / dt;
+      velocities.push(velocity);
+
+      // Instant jump: large distance in very short time (< 16ms, one frame)
+      const distance = Math.abs(dy) + Math.abs(dx);
+      if (distance > 200 && dt < 20) {
+        instantJumps++;
+      }
+
+      // Momentum: decreasing velocity (natural scroll deceleration)
+      if (i > 1 && velocities.length > 1) {
+        const prevVelocity = velocities[velocities.length - 2];
+        if (velocity < prevVelocity * 0.9 && velocity > 0) {
+          momentumEvents++;
+        }
+      }
+
+      // Check for exact positions
+      if (commonPositions.includes(Math.round(curr.scrollY))) {
+        exactPositionScrolls++;
+      }
+    }
+
+    // Calculate velocity variance
+    const avgVelocity = velocities.length > 0 
+      ? velocities.reduce((a, b) => a + b, 0) / velocities.length 
+      : 0;
+    const velocityVariance = velocities.length > 0
+      ? velocities.reduce((acc, v) => acc + Math.pow(v - avgVelocity, 2), 0) / velocities.length
+      : 0;
+
+    // Calculate interval variance
+    const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+    const intervalVariance = intervals.reduce((acc, t) => 
+      acc + Math.pow(t - avgInterval, 2), 0) / intervals.length;
+
+    // Count scroll directions
+    let scrollDirections = 0;
+    if (hasVertical) scrollDirections++;
+    if (hasHorizontal) scrollDirections++;
+
+    // Total scroll distance
+    const totalScrollY = events[events.length - 1].scrollY - events[0].scrollY;
+
+    return {
+      instantJumps,
+      velocityVariance,
+      momentumEvents,
+      intervalVariance,
+      scrollDirections,
+      totalScrollY,
+      exactPositionScrolls,
+    };
+  }
+
+  reset() {
+    super.reset();
+    this.stopTracking();
+    this._scrollEvents = [];
+  }
+}
+
+export { ScrollBehaviorSignal };

package/src/signals/behavior/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Behavioral signals index.
+ */
+
+export { MouseMovementSignal } from './MouseMovementSignal.js';
+export { KeyboardPatternSignal } from './KeyboardPatternSignal.js';
+export { InteractionTimingSignal } from './InteractionTimingSignal.js';
+export { ScrollBehaviorSignal } from './ScrollBehaviorSignal.js';

package/src/signals/environment/HeadlessSignal.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Detects headless browser indicators.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Detects indicators of headless browser execution.
+ * Headless browsers often have missing or inconsistent features.
+ */
+class HeadlessSignal extends Signal {
+  static id = 'headless';
+  static category = 'environment';
+  static weight = 0.8;
+  static description = 'Detects headless browser indicators';
+
+  async detect() {
+    const indicators = [];
+    let confidence = 0;
+
+    // Check for HeadlessChrome in user agent
+    const ua = navigator.userAgent || '';
+    if (ua.includes('HeadlessChrome')) {
+      indicators.push('headless-ua');
+      confidence = Math.max(confidence, 1.0);
+    }
+
+    // Check for missing chrome.runtime in Chrome
+    if (ua.includes('Chrome') && !ua.includes('Chromium')) {
+      if (typeof window.chrome === 'undefined') {
+        indicators.push('missing-chrome-object');
+        confidence = Math.max(confidence, 0.6);
+      } else if (!window.chrome.runtime) {
+        indicators.push('missing-chrome-runtime');
+        confidence = Math.max(confidence, 0.4);
+      }
+    }
+
+    // Check for empty plugins (common in headless)
+    if (navigator.plugins && navigator.plugins.length === 0) {
+      indicators.push('no-plugins');
+      confidence = Math.max(confidence, 0.5);
+    }
+
+    // Check for missing languages
+    if (!navigator.languages || navigator.languages.length === 0) {
+      indicators.push('no-languages');
+      confidence = Math.max(confidence, 0.6);
+    }
+
+    // Check window dimensions anomalies
+    if (window.outerWidth === 0 && window.outerHeight === 0) {
+      indicators.push('zero-outer-dimensions');
+      confidence = Math.max(confidence, 0.7);
+    }
+
+    // Check for missing connection info
+    if (typeof navigator.connection === 'undefined' && ua.includes('Chrome')) {
+      indicators.push('missing-connection-api');
+      confidence = Math.max(confidence, 0.3);
+    }
+
+    // Check for Notification API permission inconsistency
+    try {
+      if (typeof Notification !== 'undefined' && Notification.permission === 'denied' &&
+          window.outerWidth === 0) {
+        indicators.push('notification-headless-pattern');
+        confidence = Math.max(confidence, 0.5);
+      }
+    } catch (e) {
+      // Ignore errors
+    }
+
+    // Phantom.js specific check
+    if (window.callPhantom || window._phantom) {
+      indicators.push('phantomjs');
+      confidence = Math.max(confidence, 1.0);
+    }
+
+    // Nightmare.js check
+    if (window.__nightmare) {
+      indicators.push('nightmare');
+      confidence = Math.max(confidence, 1.0);
+    }
+
+    const triggered = indicators.length > 0;
+    
+    // Increase confidence if multiple indicators are present
+    if (indicators.length >= 3) {
+      confidence = Math.min(1.0, confidence + 0.2);
+    }
+
+    return this.createResult(triggered, { indicators }, confidence);
+  }
+}
+
+export { HeadlessSignal };

package/src/signals/environment/NavigatorAnomalySignal.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Detects navigator property anomalies and inconsistencies.
+ */
+
+import { Signal } from '../../core/Signal.js';
+
+/**
+ * Detects inconsistencies in navigator properties.
+ * Bots often have mismatched or spoofed navigator values.
+ */
+class NavigatorAnomalySignal extends Signal {
+  static id = 'navigator-anomaly';
+  static category = 'environment';
+  static weight = 0.7;
+  static description = 'Detects navigator property inconsistencies';
+
+  async detect() {
+    const anomalies = [];
+    let totalScore = 0;
+    let checksPerformed = 0;
+
+    const ua = navigator.userAgent || '';
+    const platform = navigator.platform || '';
+
+    // Platform vs UserAgent consistency check
+    checksPerformed++;
+    if (platform.includes('Win') && !ua.includes('Windows')) {
+      anomalies.push('platform-ua-mismatch-windows');
+      totalScore += 1;
+    } else if (platform.includes('Mac') && !ua.includes('Mac')) {
+      anomalies.push('platform-ua-mismatch-mac');
+      totalScore += 1;
+    } else if (platform.includes('Linux') && !ua.includes('Linux') && !ua.includes('Android')) {
+      anomalies.push('platform-ua-mismatch-linux');
+      totalScore += 1;
+    }
+
+    // Check for empty or suspicious platform
+    checksPerformed++;
+    if (!platform || platform === '' || platform === 'undefined') {
+      anomalies.push('empty-platform');
+      totalScore += 1;
+    }
+
+    // Language consistency
+    checksPerformed++;
+    if (navigator.language && navigator.languages) {
+      if (!navigator.languages.includes(navigator.language)) {
+        anomalies.push('language-mismatch');
+        totalScore += 0.5;
+      }
+    }
+
+    // Check vendor consistency with browser
+    checksPerformed++;
+    if (ua.includes('Chrome') && navigator.vendor !== 'Google Inc.') {
+      anomalies.push('vendor-mismatch-chrome');
+      totalScore += 0.5;
+    } else if (ua.includes('Firefox') && navigator.vendor !== '') {
+      anomalies.push('vendor-mismatch-firefox');
+      totalScore += 0.5;
+    } else if (ua.includes('Safari') && !ua.includes('Chrome') && 
+               navigator.vendor !== 'Apple Computer, Inc.') {
+      anomalies.push('vendor-mismatch-safari');
+      totalScore += 0.5;
+    }
+
+    // Check for hardwareConcurrency anomaly
+    checksPerformed++;
+    if (typeof navigator.hardwareConcurrency !== 'undefined') {
+      if (navigator.hardwareConcurrency === 0 || navigator.hardwareConcurrency > 128) {
+        anomalies.push('suspicious-hardware-concurrency');
+        totalScore += 0.5;
+      }
+    }
+
+    // Check deviceMemory if available
+    checksPerformed++;
+    if (typeof navigator.deviceMemory !== 'undefined') {
+      if (navigator.deviceMemory === 0 || navigator.deviceMemory > 512) {
+        anomalies.push('suspicious-device-memory');
+        totalScore += 0.5;
+      }
+    }
+
+    // Check maxTouchPoints consistency
+    checksPerformed++;
+    const isMobileUA = /Android|iPhone|iPad|iPod|Mobile/i.test(ua);
+    const hasTouchPoints = navigator.maxTouchPoints > 0;
+    
+    // Desktop claiming touch or mobile with no touch
+    if (!isMobileUA && navigator.maxTouchPoints > 5) {
+      anomalies.push('desktop-high-touch-points');
+      totalScore += 0.3;
+    }
+
+    // Check for overridden properties (common in spoofing)
+    checksPerformed++;
+    try {
+      const desc = Object.getOwnPropertyDescriptor(Navigator.prototype, 'userAgent');
+      if (desc && desc.get && desc.get.toString().includes('native code') === false) {
+        anomalies.push('spoofed-user-agent');
+        totalScore += 1;
+      }
+    } catch (e) {
+      // Ignore errors
+    }
+
+    // Calculate confidence based on number and severity of anomalies
+    const triggered = anomalies.length > 0;
+    const confidence = Math.min(1, totalScore / Math.max(1, checksPerformed));
+
+    return this.createResult(triggered, { anomalies }, confidence);
+  }
+}
+
+export { NavigatorAnomalySignal };