Bot detection enrichment

Availability

This enrichment is available since version 6.9.0 of Enrich.

Multiple enrichments can independently detect bots: YAUAA, IAB, and the ASN lookup. In addition, the bot detection tracker plugin for web can detect automated browsers client-side.

The bot detection enrichment consolidates these indicators into a single entity. This lets you filter bot traffic in your data models, or drop bot events entirely using a JavaScript enrichment.

How bot indicators are combined

The enrichment uses "any positive = bot" logic. If any of the enabled sources flags the event as coming from a bot, the event is classified as a bot. A negative result from one source doesn't override a positive result from another. This is because none of the existing enrichments can produce a strong "not a bot" result.

Each source contributes an indicator as follows:

Source	Flagged as bot when
YAUAA	deviceClass is "Robot", "Robot Mobile", or "Robot Imitator", or agentClass is "Robot" or "Robot Mobile" in the YAUAA entity
IAB	spiderOrRobot is true in the IAB entity
ASN lookup	likelyBot is true in the ASN entity
Client-side detection	bot is true in the client-side bot detection entity

For example, if YAUAA detects a bot based on user agent but IAB doesn't, the event is still classified as a bot. Similarly, if the ASN lookup flags the event based on a known bad ASN, that result stands regardless of what YAUAA or IAB report.

Missing sources

It's safe to enable all sources - useYauaa, useIab, useAsnLookups, useClientSideDetection - even if some of the underlying enrichments or plugins aren't in use. If a contributing source isn't enabled or its entity isn't present, that source is silently skipped.

Configuration

The enrichment takes these parameters:

Parameter	Required	Description
useYauaa	✅	Whether to use YAUAA deviceClass/agentClass as a bot signal.
useIab	✅	Whether to use IAB spiders and robots as a bot signal.
useAsnLookups	✅	Whether to use ASN lookups as a bot signal.
useClientSideDetection	✅	Whether to use the client-side bot detection tracker plugin as a bot signal.

Console

Configure the parameters in the Console enrichment editor. For example:

json

{
  "useYauaa": true,
  "useIab": true,
  "useAsnLookups": true,
  "useClientSideDetection": true
}

Self-Hosted

For Self-Hosted, provide a complete JSON. For example:

json

{
  "schema": "iglu:com.snowplowanalytics.snowplow.enrichments/bot_detection_enrichment_config/jsonschema/1-0-1",
  "data": {
    "name": "bot_detection_enrichment_config",
    "vendor": "com.snowplowanalytics.snowplow.enrichments",
    "enabled": true,
    "parameters": {
      "useYauaa": true,
      "useIab": true,
      "useAsnLookups": true,
      "useClientSideDetection": true
    }
  }
}

Testing with Micro

Unsure if your enrichment configuration is correct or works as expected? You can easily test it using Snowplow Micro, either through Console or on your machine.

The useClientSideDetection parameter is available since Enrich 6.10.0.

Output

The enrichment produces a bot_detection entity that summarizes all bot indicators for the event. It adds this entity to all events, even when no bot is detected.

bot_detection

Entity

Schema for bot detection context generated by the Bot Detection enrichment

Schema URIiglu:com.snowplowanalytics.snowplow/bot_detection/jsonschema/1-0-1

Example data

json

{
  "bot": true,
  "indicators": [
    "yauaa",
    "clientSideDetection"
  ]
}

Properties and schema

Table

Property	Description
bot boolean	Required. Whether the event is classified as coming from a bot
indicators array	Required. List of sources that indicated bot activity

Complete JSON schema

json

{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for bot detection context generated by the Bot Detection enrichment",
  "self": {
    "vendor": "com.snowplowanalytics.snowplow",
    "name": "bot_detection",
    "format": "jsonschema",
    "version": "1-0-1"
  },
  "type": "object",
  "properties": {
    "bot": {
      "type": "boolean",
      "description": "Whether the event is classified as coming from a bot"
    },
    "indicators": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "yauaa",
          "iab",
          "asnLookups",
          "clientSideDetection"
        ]
      },
      "description": "List of sources that indicated bot activity"
    }
  },
  "required": [
    "bot",
    "indicators"
  ],
  "additionalProperties": false
}