|
| 1 | +--- |
| 2 | +title: Azion Bot Manager Lite |
| 3 | +description: >- |
| 4 | + Protect your applications against automated attacks such as bad bot signatures |
| 5 | + or scripted bots with a simplified version of the Bot Manager. |
| 6 | +meta_tags: 'bot, protection, cybersecurity, edge computing' |
| 7 | +namespace: docs_bot_manager__lite_reference |
| 8 | +permalink: /documentation/products/secure/edge-firewall/bot-manager-lite/ |
| 9 | +--- |
| 10 | + |
| 11 | +import LinkButton from 'azion-webkit/linkbutton'; |
| 12 | + |
| 13 | +# Overview |
| 14 | +Azion Bot Manager Lite v0.1.9 is a serverless integration available on the Azion Marketplace, built with an edge function in the Edge Firewall. It analyzes requests and assigns a score, declining or canceling requests that exceed a pre-set limit, or allowing them by default. Available actions include allow, deny, drop, redirect, custom HTML, random delay, and hold the connection. The integration detects suspicious traffic and malicious bots such as web scraping and brute force attacks. |
| 15 | + |
| 16 | +## Solution Details |
| 17 | + |
| 18 | +This edge function evaluates requests and assigns a score based on a set of predefined rules. The action taken is configured by the customer and can be allow, deny, drop, redirect, custom HTML, random delay, or hold the connection if the score exceeds a limit defined in the JSON Args. Otherwise, the Edge Firewall rules continue to execute as normal. |
| 19 | + |
| 20 | +## Rules |
| 21 | + |
| 22 | +Currently, Bot Manager Lite features a rules system, with each rule incrementing the request score based on different conditions, such as specific HTTP headers or bot behavior patterns. |
| 23 | + |
| 24 | +## Edge Function Details |
| 25 | + |
| 26 | +The edge function is implemented in JavaScript and integrates into the Edge Firewall. Key configurable parameters include the action taken, the score threshold to trigger actions, and detailed logs transmitted via Data Stream/Real-Time Events. |
| 27 | + |
| 28 | +## Logs and Integration |
| 29 | + |
| 30 | +The log records can be configured to capture a wide range of request data, excluding sensitive headers listed below. The solution also validates IP addresses using reputation lists defined in the JSON Args, increasing the threat score of the request. |
| 31 | + |
| 32 | +### Setting up the function |
| 33 | + |
| 34 | +The function accepts the following arguments: |
| 35 | + |
| 36 | +| Variable | Type | Required | Description | |
| 37 | +|---|---|---|---| |
| 38 | +| `action` | String | Yes | The action to be taken by the function whenever the request's score is greater or equals the defined threshold. Possible values: `allow`, `deny`, `redirect`, `custom_html`, `drop`, `random_delay`, and `hold_connection`. Read more about [configuring actions](#configuring-actions) | |
| 39 | +| `threshold` | Number | Yes | The maximum score that the request can reach before the function takes an action. If it has no value, the function won't take action | |
| 40 | +| `disabled_rules` | Array of numbers | No | The rules to be disabled. If a rule is disabled, it won't be processed nor increment the request score | |
| 41 | +| `internal_logs` | String | No | The *Logging Class* that the function will use. Possible values:<br/>`0`: write logs if the request score is greater than 0.<br/>`1`: only write logs if the request score is greater than 0, or if the request is classified as "Good Bot".<br/>`2`: always write logs.<br/>`3`: never write logs.<br/>Default value: `0`. When this field has no value or has an invalid value, the function will use the default value | |
| 42 | +| `log_headers` | Array of strings | No | Defines which request headers should be included in the function's report log. For security reasons, the following headers are forbidden: <br> `authorization`, `cookie`, `proxy-authorization`, `set-cookie`, `x-csrf-token`, `x-api-key`, `x-amz-security-token`. </br> **Note**: the headers' values are going to be stored with base64 encode | |
| 43 | +| `log_tag` | String | No | A tag to identify the function instance that generated the request in the logs. It's recommended to use customized and unique tags | |
| 44 | +| `session_signature_key` | String | No | This string is used to sign, as encrypted data, the signed bot session cookie. This validation protects against cookie tampering. If this field has no value or an invalid value, the function will use the default value `az` | |
| 45 | +| `should_write_warning_logs` | Boolean | No | Defines whether the function will write warning logs to Real-Time Events. Default value: `false`| |
| 46 | + |
| 47 | +### Configuring actions |
| 48 | + |
| 49 | +Azion **Bot Manager Lite** can execute **7 different actions** whenever the request's score equals or exceeds the defined threshold. Read more about each one below: |
| 50 | + |
| 51 | +1. `allow`: allows the continuation of the request. To enable this action, you must declare it as follows: |
| 52 | + |
| 53 | +```json |
| 54 | + "action": "allow" |
| 55 | +``` |
| 56 | + |
| 57 | +This action doesn't require any additional arguments. |
| 58 | + |
| 59 | +If the score is less than the predetermined threshold, the request is processed, being *allow* the default action. |
| 60 | + |
| 61 | +2. `deny`: delivers a standard *Status Code 403* response. To enable this action, you must declare it as follows: |
| 62 | + |
| 63 | +```json |
| 64 | + "action": "deny" |
| 65 | +``` |
| 66 | + |
| 67 | +This action doesn't require any additional arguments. |
| 68 | + |
| 69 | +3. `drop`: terminates the request without a response to the user. To enable this action, you must declare it as follows: |
| 70 | + |
| 71 | +```json |
| 72 | + "action": "drop" |
| 73 | +``` |
| 74 | + |
| 75 | +This action doesn't require any additional arguments. |
| 76 | + |
| 77 | +4. `redirect`: allows the request to be redirected to a new URL/location when the security threshold is reached. To enable this action, you must declare the variables as in the example: |
| 78 | + |
| 79 | +```json |
| 80 | + "action": "redirect", |
| 81 | + "redirect_to": "http://xxxxxxxxxx.map.azionedge.net/" |
| 82 | +``` |
| 83 | + |
| 84 | +Where `redirect_to`: defines the new URL/location to redirect the requests. If this field isn't filled or filled with a value that isn't a *string*, the function will behave as if the `allow` action was enabled. |
| 85 | + |
| 86 | +5. `custom_html`: allows customized HTML content to be delivered to the user in case of a threshold violation. To enable this action, you must declare the variables as in the example: |
| 87 | + |
| 88 | +```json |
| 89 | + "action": "custom_html", |
| 90 | + "custom_html": "This should be the custom HTML content", |
| 91 | + "custom_status_code": 418, |
| 92 | +``` |
| 93 | + |
| 94 | +Where `custom_html` defines the HTML content to be delivered and `custom_status_code` is the status code to be delivered. |
| 95 | + |
| 96 | +- If `custom_html` isn't filled or it's filled with a value that isn't a *string*, the function will behave as would happen with the `allow` action enabled. |
| 97 | +- If `custom_status_code` isn't filled or it's filled with a value that isn't a *number*, the default value will be a *Status Code 200*. |
| 98 | + |
| 99 | +6. `random_delay`: makes the function wait for a random period between *1* and *10* seconds before allowing the request to proceed. To enable this action, you must declare it as follows: |
| 100 | + |
| 101 | +```json |
| 102 | + "action": "random_delay" |
| 103 | +``` |
| 104 | + |
| 105 | +This action doesn't require any additional arguments. |
| 106 | + |
| 107 | +7. `hold_connection`: holds the request, keeping the connection open for *1 minute* before dropping it. To enable this action, you must declare it as follows: |
| 108 | + |
| 109 | +```json |
| 110 | + "action": "hold_connection" |
| 111 | +``` |
| 112 | + |
| 113 | +This action doesn't require any additional arguments. |
| 114 | + |
| 115 | +:::note |
| 116 | +By using any value different from `allow`, `deny`, `redirect`, `custom_html`, `drop`, `random_delay`, or `hold_connection` for the `action` variable, the function will execute the default action, which is `allow`. |
| 117 | +::: |
| 118 | + |
| 119 | +<LinkButton link="/en/documentation/products/guides/bot-manager-lite/" label="Go to How to install Azion Bot Manager Lite from Azion Marketplace guide" severity="secondary" /> |
| 120 | + |
| 121 | +<LinkButton link="/en/documentation/products/guides/bot-manager-lite-starter-kit/" label="Go to the How to test Bot Manager Lite using a template guide" severity="secondary" /> |
| 122 | + |
| 123 | +<LinkButton link="/en/documentation/products/guides/bot-manager-lite-integration-kit/" label="Go to the How to add Bot Manager Lite to an existent edge firewall with a template guide" severity="secondary" /> |
0 commit comments