- 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
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: Whenactionis 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
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