Understanding Scores

BotSigged provides real-time risk scores that indicate the likelihood a session is automated. This guide explains how to interpret and act on these scores.

Score Basics

Bot Score

The primary metric is bot_score, a number from 0-100:

• 0-39: Low risk - Behavior consistent with human users
• 40-69: Medium risk - Some anomalies detected, may warrant monitoring
• 70-89: High risk - Strong indicators of automation
• 90-100: Critical risk - Very likely automated traffic

botsigged.onScoreUpdate((score) => {
  if (score.bot_score >= 70) {
    // Take protective action
  }
});

Classification

Each score update includes a granular classification based on user agent, behavior, automation signals, and cohort risk. Classifications are grouped by severity:

Trusted (allow):

• human - Interactive, human-like behavior
• search_engine - Declared search engine crawler
• known_agent - Declared AI agent with benign behavior

Neutral (monitor/challenge):

• scraper - Declared fetch tool
• headless_fetch - Browser UA but no behavioral signals
• suspicious - Anomalous behavior patterns

Malicious (block/challenge):

• bad_bot, stealth_bot, bad_agent, bad_scraper, abusive_human

See Session Classifications for detailed explanations and response strategies.

Triggered Rules

The triggered_rules array shows which detection categories flagged the session. This helps with debugging and tuning:

{
  bot_score: 85,
  classification: 'stealth_bot',
  triggered_rules: ['automation_detected', 'cohort_session_rate_exceeded']
}

Score Evolution

Scores update throughout a session as more behavioral data is collected:

1. Initial score - Computed immediately on connection from fingerprint and IP data
2. Behavioral updates - Refined as mouse, scroll, and form interactions are analyzed
3. Final score - Complete assessment when the session ends

Early scores may be less accurate. For critical actions (like form submissions), consider waiting for behavioral signals to be processed.

Responding to Scores

Passive Monitoring

Log scores for analysis without affecting user experience:

BotSigged.init({
  apiKey: 'your-api-key',
  onScoreUpdate: (score) => {
    analytics.track('bot_score', {
      score: score.bot_score,
      classification: score.classification
    });
  }
});

Automatic Actions

Let BotSigged handle common responses:

BotSigged.init({
  apiKey: 'your-api-key',
  actionThreshold: 70,
  action: 'block'  // or 'challenge'
});

Available actions:

• none - No automatic action (handle via callbacks)
• block - Block form submissions entirely
• challenge - Require proof-of-work before allowing submission

Custom Handling

For full control, use the onHighBotScore callback:

BotSigged.init({
  apiKey: 'your-api-key',
  actionThreshold: 70,
  onHighBotScore: (event) => {
    switch (event.level) {
      case 'critical':
        redirectToErrorPage();
        break;
      case 'high':
        showCaptcha();
        break;
      case 'medium':
        addExtraValidation();
        break;
    }
  }
});

Score Thresholds

Default thresholds can be customized:

BotSigged.init({
  apiKey: 'your-api-key',
  botScoreThresholds: {
    medium: 40,   // Default
    high: 70,     // Default
    critical: 90  // Default
  }
});

Best Practices

Don’t Block Too Aggressively

Setting thresholds too low can block legitimate users. Start with monitoring mode and adjust based on your traffic patterns.

Layer Your Defenses

Use BotSigged alongside other protections:

• Rate limiting
• Server-side validation
• Honeypot fields

Monitor False Positives

Track blocked sessions to identify patterns that might indicate false positives. Legitimate users with accessibility tools or unusual devices may trigger some detections.

Consider Context

The appropriate threshold depends on what you’re protecting:

• Newsletter signup: Lower threshold acceptable
• Payment processing: Higher threshold for safety
• Login forms: Balance security with user friction

Session Data

In addition to scores, you can access session metadata:

// Get session identifier
const sessionId = botsigged.getSessionId();

// Get current score
const score = botsigged.getLastScore();

// Check connection status
const connected = botsigged.isConnected();

This data can be sent to your backend for server-side decisions or audit logging.