# Arguments 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](/en/documentation/platform/firewall/bot-manager/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](/en/documentation/platform/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](/en/documentation/platform/firewall/limits/#bot-manager). --- ## 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](/en/documentation/platform/firewall/bot-manager/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](/en/documentation/platform/firewall/bot-manager/logs/). The rules Bot Manager Lite runs, each with its ID and the score it adds, are listed in [Bot Manager Lite](/en/documentation/platform/firewall/bot-manager/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: ```json { "threshold": 18, "action": "deny", "log_tag": "bot_manager", "mode": "web", "reputation_network_lists": [], "disabled_static_rules": [], "dynamic_rules_tolerance": "soft", "log_headers": [ "accept", "accept-encoding", "accept-language", "content-type", "host", "referer", "user-agent", "x-forwarded-for", "x-request-id" ] } ``` 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](/en/documentation/platform/firewall/best-practices/#bot-manager). --- ## Related resources - [Bot scoring](/en/documentation/platform/firewall/bot-manager/bot-scoring.md): The scoring the threshold is compared against, and the path a request takes through the function. - [Logs](/en/documentation/platform/firewall/bot-manager/logs.md): The report log these arguments write to, field by field. - [Network Lists](/en/documentation/platform/firewall/network-shield/network-lists.md): The lists `reputation_network_lists` checks a request IP against, and how to create one. - [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine.md): The rule that runs the function instance these arguments configure.