Bot Detection
The Bot Detector plugin provides advanced protection against automated traffic and bot activity. It analyzes client-side data to identify suspicious patterns and behaviors commonly associated with bots, scrapers, and automated tools.
This plugin helps you:
- Detect headless browsers and automation tools
- Identify suspicious client behaviors
- Take configurable actions against detected bots
- Protect your APIs from scraping, credential stuffing, and other automated attacks
How It Works
The Bot Detector plugin works by analyzing client-side data collected through the TrustGate client library. This data includes:
- Automation detection signals - Identifies headless browsers and automation tools
- Browser inconsistencies - Detects mismatches in reported browser capabilities
- Storage capabilities - Checks for disabled cookies and storage
- Visual fingerprinting - Analyzes canvas and WebGL rendering characteristics
The plugin calculates a bot score based on these signals and takes action according to your configuration.
When malicious activity is detected, the plugin feeds metrics to the fingerprint tracking system, which can be used by the Contextual Security plugin to block users based on their fingerprint. This creates a powerful layered defense against persistent bad actors who might try to evade detection by changing their behavior.
Important: This plugin requires the frontend to use the trustgate-client npm package to collect and send client-side data.
Configuration Options
Option | Type | Description | Default |
---|---|---|---|
threshold | float | Bot score threshold (0.0-1.0) that triggers action | Required |
action | string | Action to take when bot is detected | Required |
retention_period | integer | Period in seconds to retain fingerprint data | 300 (5 minutes) |
Available Actions
Action | Description |
---|---|
alert_only | Logs the detection but allows the request to proceed |
throttle | Adds a delay to suspicious requests to discourage automated activity |
block | Blocks requests identified as bots with a 403 Forbidden response |
Example Configuration
Note: When
action
is set toblock
, requests identified as bots will be rejected with a 403 Forbidden status code.
Client Integration
To use the Bot Detector plugin, your frontend application must integrate with the TrustGate client library:
JavaScript Integration Example
Basic Usage
Wrapping an Existing HTTP Client
Using the Built-in HTTP Client
Configuration Options
The client library automatically collects browser fingerprinting data and sends it with each request, either in request headers or in the request body based on your configuration.
Bot Detection Signals
The plugin analyzes multiple signals to calculate a bot score:
Automation Detection
Signal | Weight | Description |
---|---|---|
WebDriver | High | Detects when a browser is controlled by WebDriver |
Chrome Headless | Very High | Identifies headless Chrome instances |
Automation Properties | Medium | Checks for properties exposed by automation tools |
Browser Inconsistencies
Signal | Weight | Description |
---|---|---|
Common Resolution | Low | Detects exact common resolutions often used by bots |
UTC Timezone | Low | Identifies browsers reporting UTC timezone (common in containers) |
Missing Hardware Info | Low | Detects missing hardware concurrency or device memory info |
Platform Inconsistency | Medium | Identifies mismatches between reported platform and behavior |
Storage Capabilities
Signal | Weight | Description |
---|---|---|
Cookies Disabled | Low | Detects when cookies are disabled |
LocalStorage Disabled | Low | Identifies when localStorage is unavailable |
SessionStorage Disabled | Low | Checks if sessionStorage is disabled |
Visual Fingerprinting
Signal | Weight | Description |
---|---|---|
Canvas Fingerprint | Low | Analyzes canvas rendering characteristics |
WebGL Support | Low | Checks WebGL support and rendering capabilities |
Best Practices
- Start with alert_only mode: Monitor bot detection before blocking to avoid false positives
- Adjust threshold based on your traffic: Lower thresholds catch more bots but may increase false positives
- Use with rate limiting: Combine with rate limiting for comprehensive protection
- Consider user experience: Use throttling instead of blocking for borderline cases
- Monitor logs: Watch for patterns in bot detection to refine your configuration