Arguments
Look up every argument a Bot Manager function instance accepts, with its type, its default, and the values it takes.
A Bot Manager function instance takes its whole configuration from one JSON object. The object sets the score at which the function acts, the action it takes, the headers it writes to the report log, and the rules it stops scoring. Azion Console renders it as the Arguments section of a function instance, under the firewall’s Functions Instances tab. The Azion API and the Azion CLI carry the same object as args.
Bot Manager and Bot Manager Lite are configured through this object, and no argument is required. The installed Bot Manager Lite function carries no argument schema, so the Arguments editor has no form to build from it and the object is written as raw JSON.
This page lists the arguments an instance carries, with their types and defaults, the values action, mode, and engine_version accept, the four arguments that configure the dynamic rules, and the recommended object to start from.
Fields
The arguments object is free-form, and nothing validates it. Every key sent is stored and returned unchanged, whether or not the function reads it. For example, a key the function never reads, such as totally_bogus_key_xyz, is stored and returned byte for byte.
A misspelled argument is therefore accepted and kept. Sending thresold: 5 stores a key the function never reads, leaves the threshold at its default, and raises no error in any interface. An argument takes effect only under the exact name the function reads.
An instance does not copy the function’s defaults into its own record either. An instance created with an empty object stores {}, and the defaults below are applied when the function runs. Reading an instance therefore shows which arguments the instance sets, not the values the function runs at.
Bot Manager Lite v0.2.0 ships a default for eight arguments. An instance that sets none of them runs on the values below.
| Argument | Type | Default | What it does |
|---|---|---|---|
action | string | deny | What the function does with a request whose score reaches the threshold. The values are listed in Action |
bad_fingerprint_list | array of strings | [] | The fingerprints the function treats as bad |
disabled_rules | array of numbers | [] | The rule IDs the function skips |
good_fingerprint_list | array of strings | [] | The fingerprints the function lets through |
internal_logs | number | 0 | Which requests the function writes a log line for |
log_headers | array of strings | The nine headers listed in Log headers | The request headers the function writes into the report log |
log_tag | string | bot-manager-instance | The tag that identifies the instance a log line came from |
threshold | number | 30 | The score a request reaches before action fires |
All eight ship with the Bot Manager Lite function, and Bot Manager documents action, log_headers, log_tag, and threshold as well. Three of those defaults differ by edition, and each is covered in its own section below: action ships deny on Bot Manager Lite against a documented allow on Bot Manager, so an instance that sets neither refuses requests on one edition and passes them on the other; threshold ships 30 against a documented Infinity; and log_tag, unset on Bot Manager, takes the host header the request carried. Two instances that both keep the shipped bot-manager-instance are indistinguishable in the logs.
The arguments below carry no shipped default. Documented for names the edition whose reference carries the argument, and Documented default is the value that reference states.
| Argument | Type | Documented default | Documented for | What it does |
|---|---|---|---|---|
block_ai_bots | boolean | false | Bot Manager Lite | Blocks a request from a known AI user agent, without running the other analysis rules |
custom_html | string | — | Both editions | The HTML the custom_html action returns. With no value, or an invalid one, the function runs allow |
custom_status_code | number | 200 | Both editions | The status code of the custom_html response |
disable_dynamic_rules | boolean | false | Bot Manager | Turns the dynamic rules method off |
disabled_static_rules | array of numbers | [] | Bot Manager | The rule IDs that still run and stop adding to the score |
dynamic_rules_baseline | number | 0 | Bot Manager | A percentage multiplier on the calculated baseline |
dynamic_rules_logs_enabled | boolean | false | Bot Manager | Writes the debugging logs of the dynamic rules |
dynamic_rules_tolerance | string | soft | Bot Manager | How strict the dynamic rules method is. The values are listed in Dynamic rules |
engine_version | number | 1 | Bot Manager | The engine that identifies the client. The values are listed in Engine version |
mode | string | web | Bot Manager | The kind of client the function is scoring. The values are listed in Mode |
redirect_to | string (URI) | — | Both editions | The URL or relative path the redirect action sends the request to. With no value, or an invalid one, the function runs allow |
reputation_network_lists | array of numbers | [] on Bot Manager Lite, the account’s Azion-managed Network Lists on Bot Manager | Both editions | The Network Lists the request IP is checked against. A match raises the score, once for each list the IP is found in |
session_signature_key | string | az on Bot Manager Lite, azion on Bot Manager | Both editions | Signs the value of the az_asm session cookie |
should_write_warning_logs | boolean | false | Bot Manager Lite | Whether the function writes warning logs to Real-Time Events |
The object as a whole is bounded by size, and an instance name by length. For more information, refer to Firewall limits.
Threshold
threshold is the score a request reaches before Bot Manager takes the configured action. A request at or above it is acted on, and a request below it continues. The score comes from the rules the function runs against the request. For more information, refer to Bot scoring.
Bot Manager Lite v0.2.0 ships a threshold of 30. Bot Manager documents a default of Infinity: an instance that sets no threshold never reaches one, so every request passes.
At 0 every request is at or above the threshold, so the configured action fires on every request. What that means depends on the action: with action set to deny every request is refused, and with action set to allow nothing is blocked. Bot Manager documents one exception at 0, a user who has already solved an ALTCHA challenge, where ALTCHA is in use.
Action
action names what the function does with a request whose score is at or above the threshold. Bot Manager Lite v0.2.0 ships deny, and the documented default on Bot Manager is allow. A value outside the seven below is read as allow.
| Value | What the function does |
|---|---|
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 a 403 response carrying 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 |
Two of the seven need a second argument: custom_html carries the HTML to return, and redirect_to the location to send the request to. When that second argument is absent or is not a string, the function runs allow instead, and a custom_status_code that is absent or is not a number is read as 200.
Mode
mode tells the function what kind of client it is scoring. Bot Manager documents it with a default of web.
| Value | What it is for |
|---|---|
api | Web services and API traffic that does not carry cookies |
web | Cookie-compatible HTTP clients, such as browsers |
The comparison is case-sensitive and lowercase. Any value other than api is read as web, so API and Api both select the web mode.
Engine version
engine_version selects the engine that identifies the client behind a request. Its documented default on Bot Manager is 1.
| Value | The engine |
|---|---|
1 | The default, and the fallback when engine_version is absent or invalid |
2 | A JA4H session-based method, which produces fewer collisions between devices than 1 |
A collision is two distinct users or devices that share one fingerprint and are scored as one identity.
Dynamic rules
Four arguments configure the dynamic rules method, and Bot Manager documents all four. disable_dynamic_rules set to true turns the method off. dynamic_rules_logs_enabled set to true writes the debugging logs of the method, which Bot Manager documents for debugging alone.
dynamic_rules_tolerance sets how strict the method is:
| Value | How strict it is |
|---|---|
soft | The least strict, and the default. An invalid value is read as soft |
medium | Between soft and hard |
hard | The most strict |
dynamic_rules_baseline adjusts the baseline the method compares a request against. It is a percentage multiplier, and a lower baseline detects more strictly: 0.1 raises the baseline by 10%, and -0.234 lowers it by 23.4%. The documented default is 0.
Disabled rules
Two arguments stop a rule from raising a request’s score. disabled_rules carries the rule IDs for Bot Manager Lite and ships as an empty array. disabled_static_rules carries them for Bot Manager, with an empty array as its documented default.
A rule named in disabled_static_rules still runs. Each time a request matches it, the rule ID lands in the disabled_matched_rules field of the report log and the rule adds nothing to the score. A rule disabled this way is therefore still counted, and its matches stay visible after it stops raising the score.
The IDs come from your own logs, where the report log names every rule a request matched. For more information, refer to Logs. The rules Bot Manager Lite runs, each with its ID and the score it adds, are listed in Bot Manager Lite.
Log headers
log_headers names the request headers the function writes into its report log. Bot Manager Lite v0.2.0 ships nine of them: accept, accept-encoding, accept-language, content-type, host, referer, user-agent, x-forwarded-for, and x-request-id.
Seven headers are forbidden and cannot be logged, whatever the array carries: authorization, cookie, proxy-authorization, set-cookie, x-csrf-token, x-api-key, and x-amz-security-token.
Header values are written base64-encoded. A value read out of the log is decoded before it is compared with the value the client sent.
Recommended arguments
Bot Manager documents one arguments object as the starting point for a new instance:
Its threshold of 18 sits below the 30 Bot Manager Lite ships, so the action fires on more requests than the shipped default does. Four of its keys, mode, reputation_network_lists, disabled_static_rules, and dynamic_rules_tolerance, are not among the eight arguments Bot Manager Lite ships a default for.
The threshold and the action are the two values to calibrate against your own traffic. For more information, refer to Firewall best practices.