Session Classifications

BotSigged classifies sessions into three categories based on user agent, behavior, and automation signals.

Classification Dimensions

Each session is evaluated across multiple dimensions:

1. UA Category

Derived from the User-Agent string:

• browser - Standard web browsers (Chrome, Firefox, Safari, etc.)
• search_engine - Search engine crawlers (Googlebot, Bingbot, etc.)
• ai_agent - AI/LLM crawlers (GPTBot, ClaudeBot, etc.)
• fetch_tool - HTTP clients (curl, wget, Python requests, etc.)
• unknown - Unrecognized or empty user agents

2. Behavior Presence

Based on SDK signals received:

• interactive - Has mouse activity, form interactions, or clicks
• passive - Has scroll or page view events only
• none - No behavioral signals received

3. Automation Score

Derived from behavioral analysis (0-100 score):

• human - Score < 40
• suspicious - Score 40-69
• bot - Score >= 70

4. Automation Detection

Based on environment analysis:

• WebDriver property detection
• Headless browser indicators
• Automation framework signatures

Final Classifications

The dimensions combine into one of 3 final classifications:

Classification Flow

User Agent Analysis
       │
       ▼
┌──────────────────┐
│ search_engine?   │──yes──▶ human
└────────┬─────────┘
         │ no
         ▼
┌──────────────────┐
│ ai_agent?        │──yes──▶ human
└────────┬─────────┘
         │ no
         ▼
┌──────────────────┐
│ fetch_tool?      │──yes──▶ suspicious
└────────┬─────────┘
         │ no
         ▼
┌──────────────────┐
│ no behavior?     │──yes──▶ suspicious
└────────┬─────────┘
         │ has behavior
         ▼
┌──────────────────┐
│ automation=bot?  │──yes──▶ bot
└────────┬─────────┘
         │ no
         ▼
┌──────────────────┐
│ automation=      │──yes──▶ suspicious
│ suspicious?      │
└────────┬─────────┘
         │ no (human-like)
         ▼
      human

Responding to Classifications

In the SDK

botsigged.onScoreUpdate((data) => {
  switch (data.classification) {
    case 'human':
      // Trusted - allow normally
      break;

    case 'suspicious':
      // Uncertain - consider rate limiting or challenges
      showCaptcha();
      break;

    case 'bot':
      // Detected bot - block or heavily restrict
      blockAccess();
      break;
  }
});

Server-Side Verification

Always verify classifications server-side for sensitive operations:

// API endpoint
app.post('/api/checkout', async (req, res) => {
  const session = await botsigged.getSession(req.body.sessionId);

  if (session.classification === 'bot') {
    return res.status(403).json({ error: 'Access denied' });
  }

  if (session.classification === 'suspicious') {
    // Require additional verification
    return res.status(403).json({ error: 'Challenge required' });
  }

  // Process checkout...
});

Classification Changes

Classifications can change during a session based on:

1. Behavioral signals - As more interactions occur, the automation score updates
2. Automation detection - If automation frameworks are detected mid-session

Explorer Filtering

In the BotSigged Explorer, you can filter sessions by classification:

• Use the Classification toggles to show Human, Suspicious, or Bot sessions
• Combine with score ranges and date filters for detailed analysis