> For the complete documentation index, see [llms.txt](https://paracyberbellum.gitbook.io/pyrasp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://paracyberbellum.gitbook.io/pyrasp/6.-status-telemetry-configuration-and-blacklist-updates.md). # 6. Status, Telemetry, Configuration & Blacklist updates ## Configuration Agent can be configured to regularly send status, telemetry and new blacklist entries to a remote server. This feature is enabled by setting the `BEACON` configuration parameter to `true`.\ The `BEACON_URL` parameter **MUST** be set. It defines the URL to which beacon requests will be sent.\ The number of seconds between 2 beacon requests is defined by the `BEACON_DELAY` parameter. The default value is set to `30` seconds. If the `TELEMETRY_DATA` parameter is set to `true` cpu and memory average usage, as well as the count of succesfull, error and attack requests are sent to the remote server. If the `BLACKLIST_SHARE` paremeter is set to `true` new blacklist entries will be sent to the remote server. The parameters to be set in the configuration files are listed in the table below. | Parameter | Type | Values | Default | Usage | | ----------------- | ------- | ----------- | ------- | ---------------------------------------------------------------- | | `BEACON` | boolean | true, false | `false` | Enable status beacon to management server | | `BEACON_URL` | string | URL | `""` | URL to send status data | | `BEACON_DELAY` | integer | any | `30` | Number of seconds between each beacon | | `TELEMETRY_DATA` | boolean | true, false | `false` | Add telemetry data (cpu, memory, request count) to status beacon | | `BLACKLIST_SHARE` | boolean | true, false | `false` | Share blacklist entries with other agents (cloud only) | ## Request format Data is sent to the remote server as a `POST` request to the URL provided in the `BEACON_URL` configuration parameter. Body of the request is a JSON structure detailed below. 1. Default beacon request ```json { "key": "", "version": "", } ``` 2. Beacon request with telemetry > This request is sent to the remote server if the `TELEMETRY_DATA` parameter is set to `true` ```json { "key": "", "version": "", "telemetry": { "cpu": , "memory": , "requests": { "success": , "error": , "attacks": } } } ``` 3. Beacon request with blacklist updates > This request is sent to the remote server if the `BLACKLIST_SHARE` parameter is set to `true` ```json { "key": "", "version": "", "blacklist": [ [ "", ], ... ] } ``` ## Response format Response to beacon requests **MUST** be in an `application/json` format.\ The data structure **MUST** be a dictionary (`{}`) * If a configuration update is required, it **MUST** be located in the `config` key * If a Blacklist update is required, it **MUST** be located in the `blacklist` key ### Configuration updates Configuration updates **MUST** be provided in the `config` key of the response data structure, containing the new configuration. ```json { "config": { "HOSTS" : ["mysite.mydomain.com"], "APP_NAME" : "Web Server", "GTFO_MSG" : "

You have been blocked

", "DENY_STATUS_CODE": 403, ... } } ``` ### Blacklist updates Blacklist updates **MUST** be provided in a structure located in the `blacklist` key of the beacon response.\ The structure **MUST** contain 2 keys: * `new`: list of new IP addresses to be added to the blacklist * `remove`: list of IP addresses to be removed from the blacklist ```json { "blacklist": { "new": [ "", ... ], "remove": [ "", ... ] } } ```