Actions¶

Each Rule needs to have a single action assigned to it in order to be loaded.

There are a total of 6 actions you can choose from, some of which are so-called terminal actions and some of which are non-terminal actions.

Terminal Actions¶

A terminal action is an action that immediately stops further rule processing.

Except for the ALLOW action, there are further optional parameters that can be passed alongside the action to further customize what happens.

DENY¶

When a request is immediately denied, the customer will receive the globally configured default response for denied requests that are defined in the configuration file.

[...]
policy:
  defaults:
    deny:
      status_code: 403
      body_file: /path/to/response.html # or `plain_text_body`

You can however override this default deny response by setting a custom configuration within the rule itself. These definitions will the take precedence over the global configuration.

- name: block-post-requests
  action: DENY
  response:
    status_code: 405
    plain_text_body: Unsupported Method
    headers:
      X-Custom-Header: Custom Value

You don't need to provide all fields, you can just override the ones you want to change.

CHALLENGE¶

As there are different types of challenges available, you can override which challenge and which difficulty level you want to use for a specific rule.

Due to the nature of how challenges are processed, this might not always challenge the user to complete a new challenge, if they already have completed one beforehand that is sufficient to satisfy the rule. This is the case when the user has either completed a "higher tier" challenge or when the user has completed the same challenge but with a higher or equal difficulty level as requested by the rule.

If no overrides are defined, the globally configured default challenge will be used.

[...]
policy:
  defaults:
    challenge:
      algorithm: pow
      difficulty: 4

In order to override the challenge you can define a challenge field within the rule itself.

- name: basic-challenge-for-all-users
  action: CHALLENGE
  challenge:
    algorithm: metarefresh
    difficulty: 5

Non-Terminal Actions¶

A non-terminal action is an action that will continue processing further rules until either a terminal action is reached or all rules have been processed.

There are again further optional parameters that can be passed alongside the action to further customize what happens.

LOG¶

This action is particularly useful to find out what requests would be affected, if you were to change the action of the rule. By default, the log level of a LOG action is INFO. In case you have set the application's log level to a higher level, the log message will not appear. You can therefore change the log level by setting a severity in the level field.

- name: log-post-requests
  action: LOG
  level: ERROR

You can choose from the following log level (severities):

• DEBUG
• INFO (default)
• WARN
• ERROR

HIT¶

This action is related to the IP Blocking feature. It allows you to add or subtract reputation points for the visitor's IP address.

While there's a default value for the amount of negative reputation points to add or subtract, you should override this by setting a custom value in the amount field. It can be either a positive or negative integer.

- name: head-to-api
  action: HIT
  expression:
    all:
      - "method == 'HEAD'"
      - path.starts_with("/api")
  amount: 20

Or to lower the amount of negative reputation points:

- name: internal-requests
  action: HIT
  expression: "address in ip_list('rfc1918')"
  amount: -10

If you don't have the IP Blocking feature enabled, you must not have any rule within your policy that uses the HIT action, otherwise the application will fail to start.

WEIGH¶

This action is related to the Auto Challenge feature. It allows you to add or subtract weight for the request.

As well as with the HIT action, there's a default value for the amount of weight to add or subtract, but usually you should override this by amount in the weight field. It can be either a positive or negative integer.

- name: headless-browser
  action: WEIGH
  user_agent_regex: "headless"
  weight: 30

Subtracting weight works the same as with negative reputation points (see above).