Bot Manager

Bot management tells automated clients from people. A script and a person reach an application the same way, over HTTP, so the request is all there is to judge. The check weighs what one request carries, such as its headers, its address, and its session, and each finding adds points to one score. When the score reaches a figure you set, the request is acted on, and below it the application receives the request unchanged.

Bot Manager scores each request that a firewall rule hands it for signs of automation, and runs the action you configure when the score reaches your threshold. It runs as a function instance on the firewall, invoked by a rule with the Run Function behavior, so the firewall needs Functions on. Use Bot Manager to refuse, delay, or challenge automation such as credential stuffing, vulnerability scanning, inventory scraping, or checkout abuse on an application that also serves people.

Function instance structure

Bot Manager acts through a function instance, which carries the arguments the installed function runs on. This instance runs Bot Manager Lite at the threshold and the action that edition ships, sent as the body of POST /v4/workspace/firewalls/<firewall-id>/functions:

• threshold and action decide the outcome: the function applies action to a request whose score is equal to or higher than threshold. Bot Manager Lite ships 30 with deny, and Bot Manager documents a threshold of 18 as the value to start from.
• internal_logs at 2 writes a report line for every request, even one that scores 0, and log_tag names this instance in those lines.
• function is the ID of the installed function. Nothing validates args: a misspelled key is stored and ignored, and the function runs on its default.
• An instance scores nothing until a firewall rule runs it with a Run Function behavior, { "type": "run_function", "attributes": { "value": <instance-id> } }, which names the instance, never the function. Azion Console lists instances on the firewall’s Functions Instances tab, and Azion API and Azion CLI carry the arguments as args.

Request path

An installed Bot Manager function scores nothing on its own. Five objects put a request under inspection:

• The installed Bot Manager function.
• A firewall with Functions enabled.
• A function instance on that firewall, carrying the arguments.
• A rule on that firewall whose Run Function behavior names the instance.
• A workload bound to the firewall through its deployment.

This diagram follows a request from the rule that matches it to the Bot Manager decision:

1. A rule on the firewall matches the request, and its Run Function behavior runs one Bot Manager instance, with the arguments that instance carries.
2. Bot Manager reads the data the request carries, including its device, browser, and network data, and derives the fingerprint of the client behind it.
3. Bot Manager scores the request against its rules and compares the score with the instance’s threshold.
4. When the score is equal to or higher than the threshold, the instance runs the configured action. Otherwise the request continues to the application.

For how Bot Manager builds a score and acts on it, and how fingerprints, session cookies, and modes shape it, refer to Bot scoring.

Scope and limits

• Firewall: Bot Manager has no switch in Modules and no key in the firewall’s modules object. It needs the firewall’s Functions switch on, which a firewall created through the API, the CLI, or the Create Firewall page has. A firewall created from a Console drawer starts with Functions off.
• Editions: Bot Manager Lite is the self-serve edition, installed from Azion Marketplace, and scores each request against 26 static rules. The full edition, Bot Manager, also runs a dynamic score, which compares the behavioral history of a device fingerprint with the overall traffic pattern of the host. It is a Preview product that is not enabled on an account by default, and Azion enables it on request. To request it, refer to Support guidelines. Both editions are configured through an instance’s arguments, but their keys and three of their defaults differ, as Arguments lists.
• Actions: seven actions answer a request whose score reaches the threshold. allow, deny, and drop decide it, random_delay and hold_connection delay the answer, and redirect and custom_html replace the response. deny answers 403 with Azion’s default error page. For why a first instance scores with action set to allow, refer to Firewall best practices.
• Modes and sessions: Bot Manager Lite asks a client to carry a session. At its shipped threshold of 30, a request without a browser’s headers, such as one sent by curl, receives a 204, no body, and two session cookies. A client that keeps no cookies, such as a monitor or an API consumer, receives that 204 indefinitely. Bot Manager runs in web mode by default, and its api mode sets no cookie and ignores every rule that reads the session pair.
• Limits: an instance name takes up to 100 characters, and its arguments payload holds up to 100,000 bytes. For every bound, the answer past it, and what each plan includes, refer to Firewall limits, and for the rates, to Pricing.
• Interfaces: Bot Manager Lite installs from Azion Marketplace in Azion Console. You create its instance on the firewall’s Functions Instances tab, through the API at /v4/workspace/firewalls/<firewall-id>/functions, or with azion create firewall-instance. azion.config.js (a firewall’s functionsInstances) and Azion Terraform Provider (azion_firewall_functions_instance) create it like any firewall function instance. The Run Function behavior belongs to a firewall rule, created with azion create firewall-rule or at /v4/workspace/firewalls/<firewall-id>/request_rules.
• Observability: a report line reaches Real-Time Events in the functionConsoleEvents dataset, and Data Stream forwards it from the Functions data source. The Bot Manager tab of Real-Time Metrics charts how requests were classified and which action ran. It shows data only when the account is subscribed to Bot Manager. Azion CLI prints none of these lines, so an empty azion logs result does not show a silent function. For every field of a report line, refer to Logs.
• Neighbors: Bot Manager does not inspect a request for application vulnerabilities. That is WAF, and the two run on the same firewall. To block a request by where it comes from, use Network Shield.
• Terms: the Firewall glossary defines the words the Bot Manager pages give a specific meaning, such as fingerprint, threshold, static rule, and under evaluation.

Next steps