Run Bot Manager on selected paths
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.
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.
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.
- The rule compares the request URI with the selected paths. A request to any other path is not scored.
- A request for an image, a stylesheet, a script, or another static asset on those paths is not scored either.
- The instance scores every other request and writes a report line tagged with its
log_tag. - 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.
- Access to Azion Console. Refer to Access Azion Console.
The examples score /account/ and /checkout/ on www.example.com, with the instance checkout-bots on the firewall <firewall-id>. 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.
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.
Console
To create the instance in Azion Console:
Access Azion Console > Firewalls, then select the firewall.
On a firewall that carries no instance yet, the button reads + Function Instance.
In the General section, enter checkout-bots as the Name.
In the Function section, select the installed Bot Manager or Bot Manager Lite function.
In the Arguments section, enter the object.
The instance appears in the Functions Instances list, which shows its Name, Function, Last Editor, and Last Modified.
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 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 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 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:
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:
Access Azion Console > Firewalls, select the firewall, then select the Rules Engine tab.
Enter checkout - score clients.
In the Criteria section, select the Request Uri variable, the starts with operator, and /account/ as the argument.
Select Or, then Request Uri, starts with, and /checkout/.
Select Add Criteria. In the new block, select Request Uri, does not match, and the expression above.
In the Behaviors section, select Run Function, then checkout-bots.
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 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.
In the 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 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.
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:
-
Send one request with no user agent to a selected path, and one to a path outside them:
Shell -
Query the
functionConsoleEventsdataset for the report lines, with atsRangethat covers the requests:Shell -
Read the lines. The request to
/checkout/has one, which opens with the instance’s tag and carriesrequest_uri,score,matched_rules, andaction: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, and to raise the action once the window closes, refer to Refuse requests above the threshold.
In the 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
functionConsoleEventsdataset of Real-Time Events holds a line that opens with[Bot-Protection][webapp-observe] Report:, carrying itsscoreandmatched_rules. For the query, refer to the Bot Manager quickstart. - Static assets are not scored. Request an asset, such as
https://www.example.com/styles/main.css. No report line taggedwebapp-observeappears for it.
In the 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
functionConsoleEventsdataset of Real-Time Events that opens with[Bot-Protection][api-bots] Report:, with the request’sscoreandmatched_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 serves at /az-request-verify, and refuses a flagged client on /checkout. Replace each value with your own.
Console
To create the two instances:
Access Azion Console > Firewalls, select the firewall, then go to the Functions Instances tab.
Select + Function, enter auth-login-challenge, select the Bot Manager function, enter these arguments, and select Save:
Select + Function, enter auth-checkout-deny, select the Bot Manager function, enter these arguments, and select Save:
To point the rules at them:
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.
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.
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:
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.
The 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 use case.
In the Block account takeover on login and checkout flows use case, expect:
- A person passes the challenge. Open
https://www.example.com/loginin a browser, from a client the instance flags, and solve the challenge. The login page loads, and later requests pass without a new challenge.