Security Configuration

The security block contains security-related settings for your property configuration. Like most configuration blocks, it can occur at the property, domain, or path level.

You can set up conditional rules for blocking requests based on user agent, geographical location, or specific IP addresses.This is handled in a security_filter block within a security block. Security filters are basically a list of rules to match requests against (each of which can be either one of UA-, Geo-, or an IP-based rule), and how the service will respond to matches when they are found. You can also also specify exceptions, if any.

Note

In the current release, the rule array specification has the restriction that random ordering of the different filter types among multiple rules is not allowed. Specifically, UA filters must precede Geo filters, which must precede IP filters.

Configuration

The following fields and blocks can appear in a security_filter block:

Field and blocksDescription
enabled

Boolean flag specifying if this filter is enabled.

The default is false.

filter_rulesSpecifies a matching rule, exceptions, and how the service will respond for matched requests.

The filter_rules block has the following structure:

Field and blocksDescription
idString value identifying the filter.
matchSpecifies the matching rule. For user agents this is a list of one or more strings (exact or wildcard); for geographical locations this is a list of one or more key/value pairs for geo variables (typically COUNTRY_CODE with the desired code string), for IPs this is a list of one or more IP addresses or address blocks. See the examples below.
exceptSpecifies any exceptions to the matching rule. You can, for example, match for a range of IP address but then specify an exception for a couple of the addresses within that range.
response_handling

Specifies how the service will respond to requests that match. There is a on_filtered field whose value can be to either WARN (log in the access log) or BLOCK (block matching requests entirely). (The REDIRECT action is only supported for the WAF, not for blocking.) The default, when no reponse_handling block is present, is WARN. The security block in the access log will have the rule ID in the security_filter_alert field.

When BLOCK is specified, you can use the block_http_status field to specify a HTTP response code to send on matched requests

Examples

This example BLOCKs all IPs in the range 172.19.0.0/23 except for 172.19.0.2:

"security" : {
  "security_filter" : {
    "enabled" : true,
    "filter_rules" : [
      {
        "id" : "rule_ip_block",
        "match" : {
          "ips" : [ "172.19.0.0/23" ]
        },
        except: {
          "ips" : [ "172.19.0.2" ]
        },
        "response_handling": {
          "on_filtered": "BLOCK"
        }
      }
    ]
  }
}

This example BLOCKs all IPs except for 172.19.0.2 with a custom status code 401:

"security" : {
  "security_filter" : {
    "enabled" : true,
    "filter_rules" : [
      {
        "id" : "rule_ip_block_custom",
        "match" : {
          "ips" : [ "0.0.0.0/0" ]
        },
        "except" : {
          "ips" : [ "172.19.0.2" ]
        },
        "response_handling": {
          "on_filtered": "BLOCK",
          "block_http_status": 401
        }
      }
    ]
  }
}

This example blocks one IP range and whitelists some IPs in that range:

"security" : {
   "security_filter" : {
      "enabled" : true,
      "filter_rules" : [
         {
            "id" : "rule_ip_block",
            "match" : {
               "ips" : [ "172.19.0.0/23" ]
            },
            "except": {
               "ips" : [ "172.19.0.2", "172.19.0.12" ]
            },
            "response_handling": {
               "on_filtered": "BLOCK"
            }
         },
      ]
   }
}