Bot Detection

TRACIO's bot detection system identifies automated browsers, headless tools, and scripted attacks using a two-layer architecture: client-side signal collection and server-side analysis. The system detects 27+ automation frameworks with near-zero false positives while automatically allowlisting legitimate search engine crawlers.

Detection Architecture

Client-Side Collection

The browser agent collects 15 bot-specific signals plus 30 cross-validation signals that feed into server-side decisions:

Server-Side Analysis

The server runs 14 independent detectors in priority order. The first matching detector determines the verdict. Each detector resolves to a bot_result plus, for bot verdicts, a free-form bot_type label:

Priority   Detector               Verdict
────────   ─────────────────      ──────────────────────────
1          Webdriver flag         bot          (type: webdriver)
2          Composite bot          bot          (type: {framework})
3          Verified good bot      human         (search-engine crawler)
4          Headless (11 markers)  bot          (type: headless)
5          Eval length anomaly    bot          (type: unknown)
6          Bad bot UA pattern     bot          (type: {label})
7          Automation framework   bot          (type: {framework})
8          VM detection           (informational)
9          Emulator detection     (informational)
10         Frida detection        (informational)
11         DevTools detection     (informational)
12         Privacy browser        (informational)
13         Cloned app             (informational)
14         Behavioral analysis    bot          (type: rateBot)

Result Format

Bot detection writes a bot_result field on every event (and bot.result in the webhook payload).

Result Values

bot_result is one of three canonical values:

This maps to the business decision field (real, fake, or suspicious) used across the dashboard. See the Server API Reference for the full event schema.

Bot Types (when result is "bot")

bot_type is a free-form string. The values below are illustrative examples of what the detectors emit, not an exhaustive enum:

Detection Methods Explained

1. Webdriver Flag

The most direct detection. All major automation frameworks set navigator.webdriver = true per the WebDriver specification. This is checked in both the main frame (s300) and a hidden iframe (s158) to catch tools that patch only the main frame.

2. Automation Framework Scanning

Comprehensive scanning of window and document properties for framework-specific artifacts:

The scan also uses a regex pattern /^([a-z]){3}_.*_(Array|Promise|Symbol)$/ to detect Selenium's injected helper globals.

3. Headless Browser Detection

11 markers are evaluated, with a threshold of 2 or more for classification:

4. Good Bot Verification

22 good bot types are recognized by User-Agent pattern. Each is verified via reverse DNS to prevent spoofing:

1. Reverse DNS lookup on the connecting IP to get hostname
2. Check hostname suffix against allowed domains (e.g., .googlebot.com)
3. Forward DNS lookup on hostname to verify IP matches

If a request claims to be Googlebot but the IP does not resolve to *.googlebot.com, it is classified as bot with type googleFakeBot.

5. Behavioral Analysis

Rate-based detection with entropy scoring:

Additional rule: No mouse/keyboard events after 30+ seconds session age classifies the visit as bot with type noInteraction.

6. Eval Length Analysis

eval.toString().length produces consistent values per engine:

• 33: Chrome, Edge (V8)
• 37: Firefox (SpiderMonkey), Safari (JavaScriptCore)

Any other value indicates the eval function has been hooked by an automation framework, classifying the visit as bot with type unknown.

Integration Examples

Blocking Bots at Login (client)

The client SDK exposes a convenience boolean, result.bot.detected:

const result = await tracio.getResult()

if (result.bot.detected) {
  // Log and block
  console.warn(`Bot detected (confidence ${result.bot.confidence})`)
  showCaptcha()
  return
}

// Proceed with login
await login(credentials)

Server-Side Bot Check

On your server, fetch the event from the Server API. The event is a flat object — bot detection lives in the bot_result and bot_type fields:

// `data` is the event object from GET /subscriptions/:id/events/:requestId
const { data: event } = await fetchEvent(requestId)

if (event.bot_result === "bot") {
  await db.blockedRequests.insert({
    visitorId: event.visitor_id,
    botType: event.bot_type,
    ip: event.ip,
    timestamp: new Date(),
  })

  return res.status(403).json({ error: "Automated access detected" })
}

False Positive Handling

TRACIO's bot detection is designed for near-zero false positives. However, edge cases can occur:

If you encounter false positives, review the bot.type field to understand which detector was triggered and adjust your policy accordingly.