User-defined browser control

This page describes the User-defined browser control feature for F5 WAF for NGINX.

It allows a user to define new custom browsers, and create a list of allowed or disallowed browsers (User-defined or predefined) inspected by F5 WAF for NGINX.

There are two primary uses for this feature:

1. Verifying that non-predefined (Factory) browsers are actually browsers using F5 WAF for NGINX’s anti-automation features
2. Blocking access to specific browsers and versions unsupported by an application protected by F5 WAF for NGINX

Configure user-defined browsers

User-defined browsers can be configured in the browser-definitions section of a policy.

These are the properties that can be configured for each user-defined browser:

• name: Must be unique to both pre-defined browsers and user-defined browers
• matchString: A string that should be present in the User-Agent header to trigger enforcement.
• matchRegex: A regex pattern that should be matched in the User-Agent header to trigger enforcement.
• description: A description of the custom browser agent element.

Note that matchString and matchRegex are mutually exclusive: either can be used, but not at the same time.

You can define list of allowed or disallowed browsers in the classes or browsers subsections in the bot-defense/mitigations section.

1. classes
   • name - name of class (in this case only browser and unknown are relevant).
   • action - detect / alarm / block.
2. browsers
   • name - name of the browser (pre-defined or user-defined).
   • action - detect / alarm / block.
   • minVersion (int) - minimum version of the browser for which the action is applicable (major browser version only).
   • maxVersion (int) - maximum version of the browser for which the action is applicable (major browser version only).

Note that:

• browser defines the default action for any browser that is not in the supported factory browsers list (the default action is detect).
• unknown defines the default action for unclassified clients that did not match any browser or bot type (the default action is alarm).
• minVersion and maxVersion are optional properties, and are available only for pre-defined browsers and refer to major browser version. Without them, it defaults to "any" version.

List of predefined browsers

The following table specifies supported predefined (Factory) browsers:

Enforcement flow

If the received request has no bot signatures, then the following enforcement sequence runs:

1. Parse the User-Agent header. If a known browser is identified, then enforce based on the action set in the browser subsection of the classes section.
2. If no pre-defined or user-defined browser is identified, then enforce based on the action set in the unknown subsection of the classes section.
3. If both predefined and user-defined browser is detected, then the user-defined one takes precedence and its action is executed according to point 1.
4. If more than one user-defined browser is detected, then the most severe action of the detected browsers is taken.

User-defined browser control is part of the bot-defense configuration in the policy, and can can take place only if isEnabled flag under bot-defense section is set to true (Enabled in the default policy).

Configuration examples

In this first example, the policy is configured to:

• Include some user-defined browsers
• Detect (allow) all browsers except for browsers with action set to block in browsers section (Based on minVersion/maxVersion field values)
• Trigger an alarm if no browser was detected

{
    "policy": {
        "applicationLanguage": "utf-8",
        "name": "example_1",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "browser-definitions": [
            {
                "name": "FunkyBrowserV3",
                "matchString": "FunkyBrowser/1.3.1",
            },
            {
                "name": "SmartBrowser4",
                "matchRegex": "smartbrowser/([\\d.]+)",
            }
        ],
        "bot-defense": {
            "settings" : {
                "isEnabled": true
            },
            "mitigations": {
                "classes": [
                    {
                        "name": "browser",
                        "action": "detect"
                    },
                    {
                        "name": "unknown",
                        "action": "alarm"
                    }
                ],
                "browsers": [
                    {
                        "name": "safari",
                        "action": "block"
                    },
                    {
                        "name": "chrome",
                        "minVersion": 77,
                        "action": "block"
                    },
                    {
                        "name": "firefox",
                        "minVersion": 45,
                        "maxVersion": 60,
                        "action": "block"
                    },
                    {
                        "name": "FunkyBrowserV3",
                        "action": "block"
                    }
                ]
            }
        }
    }
}

In this second example, the policy is configured to:

• Include some user-defined browsers
• Block all browsers except for browsers with action set to detect or alarm in browsers section (Based on minVersion/maxVersion field values).
• Block the request if no browser was detected.

{
    "policy": {
        "applicationLanguage": "utf-8",
        "name": "example_2",
        "template": {
            "name": "POLICY_TEMPLATE_NGINX_BASE"
        },
        "browser-definitions": [
            {
                "name": "FunkyBrowserV3",
                "matchString": "FunkyBrowser/1.3.1",
            },
            {
                "name": "SmartBrowser4",
                "matchRegex": "smartbrowser/([\\d.]+)",
            }
        ],
        "bot-defense": {
            "settings" : {
                "isEnabled": true
            },
            "mitigations": {
                "classes": [
                    {
                        "name": "browser",
                        "action": "block"
                    },
                    {
                        "name": "unknown",
                        "action": "block"
                    }
                ],
                "browsers": [
                    {
                        "name": "safari",
                        "action": "detect"
                    },
                    {
                        "name": "chrome",
                        "minVersion": 77,
                        "action": "alarm"
                    },
                    {
                        "name": "firefox",
                        "minVersion": 45,
                        "maxVersion": 60,
                        "action": "detect"
                    },
                    {
                        "name": "FunkyBrowserV3",
                        "action": "detect"
                    }
                ]
            }
        }
    }
}