Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

5.2 KB
Raw Blame
import { HogFunctionTemplate } from '~/cdp/types'

export const template: HogFunctionTemplate = {
    free: true,
    status: 'stable',
    type: 'transformation',
    id: 'template-bot-detection',
    name: 'Filter Bot Events',
    description:
        'Filters out events from known bot user agents. This transformation will drop the event if a bot is detected.',
    icon_url: 'https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/builder_hog_01_955c082cad.png',
    category: ['Custom'],
    code_language: 'hog',
    code: `
// PostHog's curated bot UA and IP lists are tuned for browser traffic. Server-side
// SDKs (posthog-python, posthog-node, ...) send HTTP-client UAs like 'python-httpx'
// and backend IPs that match those lists but are not bots. Treat anything other than
// the browser SDKs ($lib in {web, js}) as non-browser and skip the curated checks.
// Customer-configured customBotPatterns and customIpPrefixes still apply regardless.
let lib := event.properties['$lib']
let is_browser_traffic := empty(lib) or lib == 'web' or lib == 'js'

// Get the user agent value
let user_agent := event.properties[inputs.userAgent]

// Check if user agent property exists in event
if (empty(user_agent) and inputs.keepUndefinedUseragent == 'No') {
    return null
}

if (is_browser_traffic and inputs.filterKnownBotUserAgents and isKnownBotUserAgent(user_agent)) {
    return null
}

// Modern Chrome never ships a 4-digit patch version. Scraper fleets that randomize the version
// emit one on stock device UAs ending in "Safari/537.36". The end anchor skips Chromium forks
// that put their own build there (Yandex, Opera Mobile), since their UAs end differently.
// Mirrors the "Impossible Chrome patch version" rule in web analytics' bot_definitions.py.
if (is_browser_traffic and inputs.filterKnownBotUserAgents and notEmpty(user_agent)
    and match(user_agent, 'Chrome/[0-9]+[.][0-9]+[.][0-9]+[.][0-9]{4,} (Mobile )?Safari/537[.]36$')) {
    return null
}

let bot_list := []

if (notEmpty(inputs.customBotPatterns)) {
    let custom_patterns := splitByString(',', inputs.customBotPatterns)
    // Add each custom pattern to the list
    for (let pattern in custom_patterns) {
        bot_list := arrayPushBack(bot_list, trim(pattern))
    }
}

// If bot is detected, return null to filter out the event
for (let bot_name in bot_list) {
    if (user_agent =~* bot_name) {
        return null
    }
}

let ip := event.properties['$ip']
if (empty(ip)) {
    return event
}

if (is_browser_traffic and inputs.filterKnownBotIps and isKnownBotIp(ip)) {
    return null
}

let bot_ip_prefixes := []

if (inputs.customIpPrefixes and notEmpty(inputs.customIpPrefixes)) {
    let custom_prefixes := splitByString(',', inputs.customIpPrefixes)
    // Add each custom prefix to the list
    for (let prefix in custom_prefixes) {
        if (isIPAddressInRange(ip, trim(prefix))) {
            return null
        }
    }
}

return event
    `,
    inputs_schema: [
        {
            key: 'userAgent',
            type: 'string',
            label: 'User Agent Property',
            description: 'The property that contains the user agent string (e.g. $raw_user_agent, $useragent)',
            default: '$raw_user_agent',
            secret: false,
            required: true,
        },
        {
            key: 'filterKnownBotUserAgents',
            type: 'boolean',
            label: 'Filter out known bot user agents',
            description:
                "Filter out known bot user agents using PostHog's known bot user agents list. This is kept up to date dynamically.",
            default: true,
            secret: false,
            required: true,
        },
        {
            key: 'customBotPatterns',
            type: 'string',
            label: 'Custom Bot Patterns',
            description: 'Additional bot patterns to detect, separated by commas (e.g. mybot,customcrawler)',
            default: '',
            secret: false,
            required: false,
        },
        {
            key: 'filterKnownBotIps',
            type: 'boolean',
            label: 'Filter out known bot ips',
            description:
                "Filter out known bot ips using PostHog's known bot ips list. This is kept up to date dynamically.",
            default: true,
            secret: false,
            required: true,
        },
        {
            key: 'customIpPrefixes',
            type: 'string',
            label: 'Custom IP Prefixes',
            description:
                'Additional IPv4 or IPv6 prefixes in CIDR notation to block, separated by commas (e.g. 198.51.100.14/24,2001:db8::/48)',
            default: '',
            secret: false,
            required: false,
        },
        {
            key: 'keepUndefinedUseragent',
            type: 'choice',
            label: 'Keep events where the useragent is not set?',
            description:
                'Some events such as server-side events may not have a useragent property, choose if you want to keep these events',
            default: 'Yes',
            secret: false,
            required: false,
            choices: [
                { value: 'Yes', label: 'Yes' },
                { value: 'No', label: 'No' },
            ],
        },
    ],
}