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

{ 
    "key": "<agent-key>", 
    "version": "<agent-version>",
}

  1. Beacon request with telemetry

This request is sent to the remote server if the TELEMETRY_DATA parameter is set to true

{ 
    "key": "<agent-key>", 
    "version": "<agent-version>",
    "telemetry": {
        "cpu": <cpu_usage_percent>, 
        "memory": <memory_usage_percent>,
        "requests": {
            "success": <successful_requests_count>,
            "error": <error_requests_count>,
            "attacks": <attacks_requests_count>
        }
    }
}

  1. Beacon request with blacklist updates

This request is sent to the remote server if the BLACKLIST_SHARE parameter is set to true

{ 
    "key": "<agent-key>", 
    "version": "<agent-version>",
    "blacklist": [
        [ "<ip_address>", <detection_epoch_time> ],
        ...
    ]
}

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.

{
    "config": {
        "HOSTS" : ["mysite.mydomain.com"],
        "APP_NAME" : "Web Server",
        "GTFO_MSG" : "<html><head /><body><h1>You have been blocked</h1></body></html>",
        "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

{
    "blacklist": {
        "new": [ "<ip_address>", ... ],
        "remove": [ "<ip_address>", ... ]
    }
}
Previous5. Cloud OperationsNext7. API

Last updated