--- name: azion-run-bot-manager-on-selected-paths description: >- Run a Bot Manager instance only on the paths that need it, such as a login or a checkout, with its own threshold, action, and log tag. --- # Run Bot Manager on selected paths You run a Bot Manager instance on the paths you choose, such as `/account/` and `/checkout/`, from Azion Console, the Azion CLI, or the API. To run one instance on every request a firewall receives, refer to [Run Bot Manager on every request](/en/documentation/guides/application-security/bots-and-network/run-on-every-request/). Bot Manager bills each request it scores, and a path that no rule matches is not scored. One instance carries one threshold and one action, so paths that differ in value, such as a catalog and a checkout, take an instance each, with its own rule. ```mermaid %%{init: {"layout": "dagre", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 12, "rankSpacing": 12, "padding": 6, "wrappingWidth": 70, "minNodeWidth": 40, "useMaxWidth": true}}}%% flowchart TD Req["A request reaches the firewall"] --> Path{"Does the URI start with a selected path?"} Path -->|"no"| Skip["Not scored"] Path -->|"yes"| Asset{"Is it a static asset?"} Asset -->|"yes"| Skip Asset -->|"no"| Score["The instance scores the request and writes a report line"] Score -->|"score at or above the threshold"| Action["The instance applies its action"] Score -->|"below the threshold"| App["The request continues"] ``` 1. The rule compares the request URI with the selected paths. A request to any other path is not scored. 2. A request for an image, a stylesheet, a script, or another static asset on those paths is not scored either. 3. The instance scores every other request and writes a report line tagged with its `log_tag`. 4. A request whose score reaches the threshold receives the instance's action, and a request below it continues. --- ## Prerequisites ### Console - A firewall bound to the workload that serves the paths, with Functions turned on in its main settings. Refer to the [Bot Manager quickstart](/en/documentation/platform/firewall/bot-manager/quickstart/). - Access to Azion Console. Refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). ### CLI - A firewall bound to the workload that serves the paths, with Functions turned on in its main settings. Refer to the [Bot Manager quickstart](/en/documentation/platform/firewall/bot-manager/quickstart/). - Bot Manager enabled on the account, or Bot Manager Lite installed from Azion Marketplace, and the ID of the installed function. To install Bot Manager Lite, refer to [Install Bot Manager Lite](/en/documentation/guides/application-development/integrations/bot-manager-lite/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/). - The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized. ### API - A firewall bound to the workload that serves the paths, with Functions turned on in its main settings. Refer to the [Bot Manager quickstart](/en/documentation/platform/firewall/bot-manager/quickstart/). - Bot Manager enabled on the account, or Bot Manager Lite installed from Azion Marketplace, and the ID of the installed function. To install Bot Manager Lite, refer to [Install Bot Manager Lite](/en/documentation/guides/application-development/integrations/bot-manager-lite/). - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/). The examples score `/account/` and `/checkout/` on `www.example.com`, with the instance `checkout-bots` on the firewall ``. Replace them with your paths, names, and firewall. --- ## Create an instance for the paths The instance takes one JSON arguments object, and nothing validates it: a misspelled key such as `thresold` is stored, and the function never reads it. Write `threshold` and `action` on every instance. Bot Manager Lite ships `deny` at `30`, and Bot Manager documents `allow` at `Infinity`, so an instance that sets neither refuses requests on one edition and passes them on the other. The object below starts in observation mode: `action` is `allow`, so nothing is refused, and `internal_logs` is `2`, so every request writes a report line. `log_tag` names this instance in those lines. ```json { "threshold": 15, "action": "allow", "internal_logs": 2, "log_tag": "checkout-bots" } ``` Run it for 24 to 72 hours, then set `threshold` in the gap between the scores of the clients you recognize and the automated ones, and choose one of the seven actions: | `action` | What the function does at the threshold | | ----------------- | ------------------------------------------------------------------------------- | | `allow` | Lets the request continue, whatever its score | | `custom_html` | Returns the HTML in `custom_html`, with the status code in `custom_status_code` | | `deny` | Returns `403` with Azion's default error page | | `drop` | Terminates the request without a response | | `hold_connection` | Holds the connection open for 1 minute, then drops the request | | `random_delay` | Waits a random period between 1 and 10 seconds, then lets the request continue | | `redirect` | Redirects the request to the location in `redirect_to` | A value outside the seven is read as `allow`, and so are `custom_html` and `redirect` without their second argument. On Bot Manager, `mode` set to `api` scores web services and API traffic that carries no cookies. For the starting threshold per kind of path, refer to [Run a stricter Bot Manager instance on a high-value path](/en/documentation/platform/firewall/best-practices/#run-a-stricter-bot-manager-instance-on-a-high-value-path). ### Console To create the instance in Azion Console: 1. **Open the firewall bound to your workload** Access [Azion Console](https://console.azion.com/) > **Firewalls**, then select the firewall. 2. **Select the Functions Instances tab** 3. **Select + Function** On a firewall that carries no instance yet, the button reads **+ Function Instance**. 4. **Name the instance** In the **General** section, enter `checkout-bots` as the **Name**. 5. **Select the Bot Manager function** In the **Function** section, select the installed Bot Manager or Bot Manager Lite function. 6. **Enter the arguments** In the **Arguments** section, enter the object. 7. **Select Save** The instance appears in the **Functions Instances** list, which shows its **Name**, **Function**, **Last Editor**, and **Last Modified**. ### CLI To create the instance with the Azion CLI, save the object as `bmargs.json`. The `--args` flag takes the path to that file, not inline JSON: ```bash azion create firewall-instance --name checkout-bots --firewall-id \ --function-id --args bmargs.json --active true ``` The command prints the ID of the instance: ```text Created Firewall Function Instance with ID ``` Keep that ID. The rule names the instance by it, never by the ID of the function. ### API To create the instance with the API, send the ID of the installed function and the arguments: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//functions \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "checkout-bots", "function": , "active": true, "args": { "threshold": 15, "action": "allow", "internal_logs": 2, "log_tag": "checkout-bots" } }' ``` The API answers `202` with a `state` of `pending`, and echoes `args` unchanged. Keep the instance's `id`: ```json {"state":"pending","data":{"id":,"name":"checkout-bots","args":{"threshold":15,"action":"allow","internal_logs":2,"log_tag":"checkout-bots"},...}} ``` The instance exists on the firewall and scores nothing until a rule runs it. In the [Protect web applications from OWASP Top 10 and zero-day attacks](/en/documentation/use-cases/secure-applications-and-networks/protect-web-applications-from-owasp-top-10-and-zero-day-attacks/) use case, this section takes these values: | Setting | Value | | --------- | ----------------------------------------------------------------------------------- | | Instance | `webapp-bot-observe` | | Arguments | `threshold` `18`, `action` `allow`, `internal_logs` `2`, `log_tag` `webapp-observe` | In the [Protect public APIs from abuse](/en/documentation/use-cases/secure-applications-and-networks/protect-public-apis-from-abuse/) use case, this section takes these values: | Setting | Value | | --------- | ---------------------------------------------------------------------------------------------- | | Instance | `api-bots` | | Arguments | `"mode": "api"`, `threshold` `15`, `action` `allow`, `internal_logs` `2`, `log_tag` `api-bots` | In the [Block account takeover on login and checkout flows](/en/documentation/use-cases/secure-applications-and-networks/block-account-takeover-on-login-and-checkout-flows/) use case, this section takes these values: | Setting | Value | | --------- | --------------------------------------------------------------------------------- | | Instance | `auth-observe` | | Arguments | `threshold` `10`, `action` `allow`, `internal_logs` `2`, `log_tag` `auth-observe` | --- ## Create the rule that runs it on the paths The rule holds two blocks of criteria, and a request matches it only when it matches both. The first block names the paths, each joined by `or`: `Request Uri` *starts with* `/account/`, or *starts with* `/checkout/`. The second block keeps static assets out, because none is a client and each is a request Bot Manager bills: `Request Uri` *does not match* this expression, which also matches an asset requested with a query string: ```text \.(png|jpg|jpeg|gif|ico|css|js|svg|woff|woff2|ttf|eot|otf|webp|avif|mp4|webm|pdf)(\?.*)?$ ``` The *Run Function* behavior names the instance, and a rule carries at most one, so a second instance on other paths takes a second rule. ### Console To create the rule in Azion Console: 1. **Open the firewall's Rules Engine tab** Access [Azion Console](https://console.azion.com/) > **Firewalls**, select the firewall, then select the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** Enter `checkout - score clients`. 4. **Set the first path** In the **Criteria** section, select the `Request Uri` variable, the *starts with* operator, and `/account/` as the argument. 5. **Add the second path** Select **Or**, then `Request Uri`, *starts with*, and `/checkout/`. 6. **Exclude static assets** Select **Add Criteria**. In the new block, select `Request Uri`, *does not match*, and the expression above. 7. **Add the Run Function behavior** In the **Behaviors** section, select **Run Function**, then `checkout-bots`. 8. **Select Save** ### CLI To create the rule with the Azion CLI, save it as `rule.json`, with the ID of the instance in `value`. Inside the JSON string, each backslash of the expression is escaped once more: ```json { "name": "checkout - score clients", "active": true, "criteria": [ [ { "variable": "${request_uri}", "conditional": "if", "operator": "starts_with", "argument": "/account/" }, { "variable": "${request_uri}", "conditional": "or", "operator": "starts_with", "argument": "/checkout/" } ], [ { "variable": "${request_uri}", "conditional": "if", "operator": "does_not_match", "argument": "\\.(png|jpg|jpeg|gif|ico|css|js|svg|woff|woff2|ttf|eot|otf|webp|avif|mp4|webm|pdf)(\\?.*)?$" } ] ], "behaviors": [ { "type": "run_function", "attributes": { "value": } } ] } ``` Then create the rule from the file: ```bash azion create firewall-rule --firewall-id --file rule.json ``` The command prints the ID of the new rule: ```text Created Firewall Rule with ID ``` ### API To create the rule with the API, send both blocks, with the ID of the instance in `value`. Inside the JSON string, each backslash of the expression is escaped once more: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//request_rules \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "checkout - score clients", "active": true, "criteria": [ [ { "variable": "${request_uri}", "conditional": "if", "operator": "starts_with", "argument": "/account/" }, { "variable": "${request_uri}", "conditional": "or", "operator": "starts_with", "argument": "/checkout/" } ], [ { "variable": "${request_uri}", "conditional": "if", "operator": "does_not_match", "argument": "\\.(png|jpg|jpeg|gif|ico|css|js|svg|woff|woff2|ttf|eot|otf|webp|avif|mp4|webm|pdf)(\\?.*)?$" } ] ], "behaviors": [{ "type": "run_function", "attributes": { "value": } }] }' ``` The API answers `202` with a `state` of `pending`, and adds the `order` the rule holds among the rules of the firewall. The instance scores every request to `/account/` and `/checkout/` except static assets, and no request to any other path. A format added to your site later is scored until you add it to the expression. In the [Protect web applications from OWASP Top 10 and zero-day attacks](/en/documentation/use-cases/secure-applications-and-networks/protect-web-applications-from-owasp-top-10-and-zero-day-attacks/) use case, this section takes these values: | Setting | Value | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Rule | `webapp - score page requests`, with one block of criteria: the static-asset exclusion, `Request Uri` *does not match* this section's expression. The rule carries no block of paths | | Behavior | *Run Function* with `webapp-bot-observe` | Every page request is scored and served, and each one writes a report line tagged `webapp-observe`. When the window closes, read the scores, set `threshold` in the gap between the legitimate and the automated clusters, and set `action` to `deny`. For the procedure, refer to [Monitor and calibrate Bot Manager](/en/documentation/guides/application-security/bots-and-network/monitor-and-calibrate-bot-manager/). In the [Protect public APIs from abuse](/en/documentation/use-cases/secure-applications-and-networks/protect-public-apis-from-abuse/) use case, this section takes these values: | Setting | Value | | -------- | ------------------------------------------------------------------------------------- | | Rule | `api - score clients`, with one block of criteria: `Request Uri` *starts with* `/v1/` | | Behavior | *Run Function* with `api-bots` | Every request to `/v1/` writes a report line tagged `api-bots`. After 24 to 72 hours, read the scores of the clients you recognize, set `threshold` in the gap between them and the automated clients, and set `action` to `deny`. A scored client at the threshold then receives `403`. An API client cannot answer a challenge, so `deny` fits these paths better than `redirect`. In the [Block account takeover on login and checkout flows](/en/documentation/use-cases/secure-applications-and-networks/block-account-takeover-on-login-and-checkout-flows/) use case, this section takes these values: | Setting | Value | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Rule | `auth - observe authentication paths` | | Criteria, one block joined by `or` | `Request Uri` *starts with* `/login`, `/signup`, or `/checkout`, sent in the API as `${request_uri}` `starts_with` | | Behavior | *Run Function* with `auth-observe` | Every request to the three paths is scored and served, and each one writes a line tagged `auth-observe`. Read `score` and `matched_rules` on requests you recognize as customers, because `classified` depends on the threshold in force. For the procedure, refer to [Run Bot Manager in observation mode](/en/documentation/guides/application-security/bots-and-network/observation-mode/). --- ## Confirm the instance scores only the paths A new rule reaches traffic 6 minutes 29 seconds to 9 minutes 18 seconds after you save it, and a change to an instance's arguments about 105 seconds after. Repeat each check until the answers agree. To confirm what the instance scores: 1. Send one request with no user agent to a selected path, and one to a path outside them: ```bash curl -A "" https://www.example.com/checkout/ curl -A "" https://www.example.com/ ``` 2. Query the `functionConsoleEvents` dataset for the report lines, with a `tsRange` that covers the requests: ```bash curl --request POST \ --url https://api.azion.com/v4/events/graphql \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{"query":"{ functionConsoleEvents(limit: 200, filter: { tsRange: { begin: \"2030-01-01T10:00:00\", end: \"2030-01-01T11:00:00\" } }, orderBy: [ts_ASC]) { ts line } }"}' ``` 3. Read the lines. The request to `/checkout/` has one, which opens with the instance's tag and carries `request_uri`, `score`, `matched_rules`, and `action`: ```text [Bot-Protection][checkout-bots] Report: {"request_id":"",…,"request_uri":"/checkout/",…,"score":,…,"action":"allow","matched_rules":[…]} ``` The request to `/` has no line, because the rule does not match it. The instance scores the selected paths and nothing else. Read `score` and `matched_rules` rather than `classified`, which depends on the threshold in force. For every field of a line, refer to [Logs](/en/documentation/platform/firewall/bot-manager/logs/), and to raise the action once the window closes, refer to [Refuse requests above the threshold](/en/documentation/guides/application-security/bots-and-network/refuse-above-threshold/). In the [Protect web applications from OWASP Top 10 and zero-day attacks](/en/documentation/use-cases/secure-applications-and-networks/protect-web-applications-from-owasp-top-10-and-zero-day-attacks/) use case, expect: - **Bot Manager scores page requests.** A request with no user agent, which is what a scripted client sends, is served, and the `functionConsoleEvents` dataset of Real-Time Events holds a line that opens with `[Bot-Protection][webapp-observe] Report:`, carrying its `score` and `matched_rules`. For the query, refer to the [Bot Manager quickstart](/en/documentation/platform/firewall/bot-manager/quickstart/). - **Static assets are not scored.** Request an asset, such as `https://www.example.com/styles/main.css`. No report line tagged `webapp-observe` appears for it. In the [Protect public APIs from abuse](/en/documentation/use-cases/secure-applications-and-networks/protect-public-apis-from-abuse/) use case, expect: - **Bot Manager scores API clients.** A request with a valid token and no user agent writes a line in the `functionConsoleEvents` dataset of Real-Time Events that opens with `[Bot-Protection][api-bots] Report:`, with the request's `score` and `matched_rules`. --- ## Challenge flagged clients on some paths and deny them on others One instance carries one action, so a challenge on some paths and a refusal on others take an instance and a rule each. The example starts from an instance in observation mode, `auth-observe`, and its rule `auth - observe authentication paths` on `/login`, `/signup`, and `/checkout`, created as the sections above describe. It sends a flagged client on `/login` and `/signup` to the challenge that [ALTCHA](/en/documentation/guides/application-development/functions-and-runtime/altcha/) serves at `/az-request-verify`, and refuses a flagged client on `/checkout`. Replace each value with your own. ### Console To create the two instances: 1. **Open the Functions Instances tab** Access [Azion Console](https://console.azion.com/) > **Firewalls**, select the firewall, then go to the **Functions Instances** tab. 2. **Create the challenge instance** Select **+ Function**, enter `auth-login-challenge`, select the Bot Manager function, enter these arguments, and select **Save**: ```json { "threshold": 10, "action": "redirect", "redirect_to": "/az-request-verify", "internal_logs": 2, "log_tag": "auth-login-challenge" } ``` 3. **Create the deny instance** Select **+ Function**, enter `auth-checkout-deny`, select the Bot Manager function, enter these arguments, and select **Save**: ```json { "threshold": 10, "action": "deny", "internal_logs": 2, "log_tag": "auth-checkout-deny" } ``` To point the rules at them: 1. **Edit the observation rule** In the **Rules Engine** tab, open `auth - observe authentication paths`. Remove the `/checkout` criterion, rename the rule `auth - challenge login and signup`, and select `auth-login-challenge` in **Run Function**. Select **Save**. 2. **Create the checkout rule** Select **+ Rule** and enter `auth - deny on checkout`. In the **Criteria** section, select `Request Uri`, *starts with*, and `/checkout`. In the **Behaviors** section, select **Run Function**, then `auth-checkout-deny`. Select **Save**. ### CLI This guide documents this task in Azion Console and in the API. Follow the [API procedure](?interface=api#challenge-flagged-clients-on-some-paths-and-deny-them-on-others). ### API To create the challenge instance: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//functions \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "auth-login-challenge", "function": , "active": true, "args": { "threshold": 10, "action": "redirect", "redirect_to": "/az-request-verify", "internal_logs": 2, "log_tag": "auth-login-challenge" } }' ``` To create the deny instance: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//functions \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "auth-checkout-deny", "function": , "active": true, "args": { "threshold": 10, "action": "deny", "internal_logs": 2, "log_tag": "auth-checkout-deny" } }' ``` Each call answers `202` with a `state` of `pending` and the instance's `id`. Then create one rule per instance. This one runs the challenge instance on `/login` and `/signup`: ```bash curl --request POST \ --url https://api.azion.com/v4/workspace/firewalls//request_rules \ --header 'Authorization: Token ' \ --header 'Content-Type: application/json' \ --data '{ "name": "auth - challenge login and signup", "active": true, "criteria": [ [ { "variable": "${request_uri}", "conditional": "if", "operator": "starts_with", "argument": "/login" }, { "variable": "${request_uri}", "conditional": "or", "operator": "starts_with", "argument": "/signup" } ] ], "behaviors": [{ "type": "run_function", "attributes": { "value": } }] }' ``` The checkout rule is the same body with the name `auth - deny on checkout`, one criterion `${request_uri}` `starts_with` `/checkout`, and `` in `value`. Each call answers `202` with a `state` of `pending`. Delete the observation rule afterward, with `DELETE /v4/workspace/firewalls//request_rules/`. A flagged client on `/login` and `/signup` is redirected to `/az-request-verify`, and a flagged client on `/checkout` receives `403`. An argument change reaches traffic about 105 seconds after it is saved, and a new rule 6 to 10 minutes after. To confirm both rules, request the home page and `/login`, then send a request with no user agent, which is what a scripted client sends, to `/checkout` and to `/login`: ```bash curl -s -o /dev/null https://www.example.com/ curl -s -o /dev/null https://www.example.com/login curl -s -o /dev/null -w '%{http_code}\n' -A "" https://www.example.com/checkout curl -s -o /dev/null -w '%{redirect_url}\n' -A "" https://www.example.com/login ``` A report line appears for `/login`, and none for `/`. When a request's score reaches `10`, the request to `/checkout` prints `403`, and the line tagged `auth-checkout-deny` reads `"action":"deny"`. The request to `/login` prints the address of `/az-request-verify`, and the line tagged `auth-login-challenge` reads `"action":"redirect"`. A line that reads `allow` at a score at the threshold means `redirect_to` is missing or invalid. To query the lines, refer to [Read the report log for one instance](/en/documentation/guides/application-security/bots-and-network/read-the-report-log/). The [Block account takeover on login and checkout flows](/en/documentation/use-cases/secure-applications-and-networks/block-account-takeover-on-login-and-checkout-flows/) use case uses the values of this example. These checks confirm the [Block account takeover on login and checkout flows](/en/documentation/use-cases/secure-applications-and-networks/block-account-takeover-on-login-and-checkout-flows/) use case. In the [Block account takeover on login and checkout flows](/en/documentation/use-cases/secure-applications-and-networks/block-account-takeover-on-login-and-checkout-flows/) use case, expect: - **A person passes the challenge.** Open `https://www.example.com/login` in a browser, from a client the instance flags, and solve the challenge. The login page loads, and later requests pass without a new challenge. --- ## Next steps - [Refuse requests above the threshold](/en/documentation/guides/application-security/bots-and-network/refuse-above-threshold.md): Move the instance from allow to an action that refuses automated clients. - [Read the report log for one instance](/en/documentation/guides/application-security/bots-and-network/read-the-report-log.md): Query the lines one instance wrote, with their scores and matched rules. - [Arguments](/en/documentation/platform/firewall/bot-manager/arguments.md): Every argument an instance accepts, with its type, its default, and the values it takes. - [Firewall best practices](/en/documentation/platform/firewall/best-practices.md#bot-manager): Thresholds per kind of path, observation windows, and static asset exclusion. - [Protect web applications from OWASP Top 10 and zero-day attacks](/en/documentation/use-cases/secure-applications-and-networks/protect-web-applications-from-owasp-top-10-and-zero-day-attacks.md): An instance that scores every page request of a web application, static assets excluded. - [Protect public APIs from abuse](/en/documentation/use-cases/secure-applications-and-networks/protect-public-apis-from-abuse.md): An instance in api mode that scores the clients of an API path. - [Block account takeover on login and checkout flows](/en/documentation/use-cases/secure-applications-and-networks/block-account-takeover-on-login-and-checkout-flows.md): One observation instance on login, signup, and checkout, then stricter instances per path. - [Run Bot Manager on every request](/en/documentation/guides/application-security/bots-and-network/run-on-every-request.md): The rule that hands every request a firewall receives to one instance.