Rules Engine for Firewall

A rule in Rules Engine for Firewall pairs criteria, which decide whether a request matches, with behaviors, which act on each request that matches. A rule whose criteria do not match applies nothing. To follow a request through the rules of a firewall, refer to How Firewall works.

A firewall rule decides whether a request reaches the application at all, because the firewall takes each request before the application does. A rule that chooses how the application serves an allowed request, such as its connector or cache setting, belongs to Rules Engine for Applications.

Rule fields

Each firewall holds its own list of rules. Azion Console shows them in the firewall’s Rules Engine tab, where Rule opens the Create Rule drawer. The API serves them under /v4/workspace/firewalls/<firewall-id>/request_rules. A rule carries ten fields: five that a request sets, and five that the platform sets and returns.

The platform assigns order in creation order: the first rule on a firewall carries 0, and the eleventh carries 10. The Console rule list lets you reorder rules.

Criteria

Criteria decide which requests a rule acts on. Each criterion names a variable, a comparison operator, and, for most operators, an argument to compare the variable with. The Create Rule drawer opens with one criterion already set to Request Uri and starts with, and ${request_uri} starts_with / matches every request the workload receives.

The table lists the variables in Console order. Nine of them require Web Application Firewall (WAF) enabled on the firewall, Network requires Network Shield, and the other five need no Product.

When the firewall lacks the Product a variable requires, the Console still lists the variable but does not let you select it. The label then carries a suffix, such as Header Accept - required WAF or Network - required Network Shield. The API refuses a rule that uses ${network} on a firewall without Network Shield, with 400 and code 25047.

Network compares the client IP address with a Network List. In the Console, the argument becomes the Select a Network list, which shows every Network List in the account and closes with Create Network List. In the API, the argument is the list ID sent as a JSON integer. For example, 2 is the Tor exit node list Azion provides, and any rule can reference it. The same ID sent as a string is refused with 400 and code 25042.

Once a rule on the firewall uses ${network}, Network Shield cannot be turned off on that firewall. The API answers 400 with code 24005 and names the rules that hold it.

Request Args holds nothing when the request has no query string, and an empty variable does not match. For example, a rule on ${request_args} matches .* skips every POST that carries its payload in the body and none in the query string.

Ssl Verification Status takes one of three values, which the Console offers in the Select an SSL Status list:

Operators

A criterion compares its variable with its argument through an operator. The Console labels each operator in lowercase, and the API sends the value in the second column as operator.

The Console hides the argument field for exists and does not exist, and replaces it with a list for Network and Ssl Verification Status.

Network is the exception to the table. Its matches and does not match carry the API values is_in_list and is_not_in_list, and both compare the client IP address with the Network List the argument names. The API refuses matches on ${network} with 400 and code 25039.

Each variable offers only some of the operators:

Conditionals

Criteria combine inside blocks, and a rule holds from 1 to 5 blocks of 1 to 10 criteria each. Inside a block, the first criterion carries the conditional if, and each later criterion carries and or or. Blocks are joined by And, which the Console prints between them, so a request matches the rule only when it matches every block.

In the Console, And and Or add a criterion to a block, and Add Criteria adds a block. The Console disables And and Or at 10 criteria in a block, and Add Criteria at 5 blocks. The dividers between criteria show the conditional as If, And, or Or.

In the API, criteria is a list of blocks, and each block is a list of criterion objects. The rule in this example holds one block of two criteria. It denies a request only when the client IP address is in the Network List and the URI starts with /ip-deny:

The <network-list-id> placeholder stands for an integer with no quotes around it.

Behaviors

Behaviors are what a rule does to a request that matches its criteria. The Console labels the first behavior row Then and each later row And, and Add Behavior adds a row. In the API, each behavior is an object with a type, and the behaviors that take settings carry them in attributes.

The Requires column names the Product the firewall must have enabled for the Console to offer the behavior. When it is off, the Console shows Set WAF - required WAF or Run Function - required Functions and does not let you select it. None of the six behaviors requires Network Shield.

The Console also limits how behaviors combine. Only Run Function and Set WAF can be followed by another behavior, and each appears at most once in a rule. Choosing Deny (403 Forbidden), Drop (Close Without Response), Set Rate Limit, or Set Custom Response removes every behavior row after it.

Deny (403 Forbidden)

Deny (403 Forbidden) refuses the request with 403 and takes no attributes. The body is Azion’s default error page titled Forbidden, about 10.6 KB of HTML, which shows the client IP address and the request ID. No response header names the firewall or the rule. In the API, the behavior is { "type": "deny" }.

Drop (Close Without Response)

Drop (Close Without Response) closes the request without answering it and takes no attributes. The client receives no status line and no body, immediately. A script that reads the status code sees 000, and a browser shows a connection error. In the API, the behavior is { "type": "drop" }.

Over HTTP/2, curl reports the reset stream and exits with code 92:

Over HTTP/1.1 and plain HTTP, curl exits with code 52:

Set Rate Limit

Set Rate Limit caps the rate of the requests the rule matches. A request the rate and the burst do not admit receives 429, with the default error page titled Too Many Requests. No response carries a rate-limit header, such as retry-after or an x-ratelimit- header.

A rate limit of 10 requests per second per client IP address, with a burst of 10:

For how the rate and the burst admit requests, refer to How Firewall works.

Set WAF

Set WAF applies a WAF rule set to the requests the rule matches, and requires WAF enabled on the firewall. A rule set runs only when a rule carries this behavior, and a rule carries at most one. Rule sets live in Azion Console under Edge Libraries > WAF Rules.

In blocking mode, a request the rule set blocks receives 400 with the default error page titled Bad Request, and no response header names WAF. In logging mode, WAF does not refuse the request. The API refuses a set_waf behavior with no mode, and any mode other than logging or blocking, including learning.

A behavior that applies a rule set in blocking mode:

Run Function

Run Function runs a function instance of the firewall on the requests the rule matches, and requires Functions enabled on the firewall. A firewall created through the API, the CLI, or the Console create page has Functions on, and the Console create drawer starts it off.

The attribute value holds the ID of the function instance, not of the function. Instances live in the firewall’s Functions Instances tab. In the Console, Select a Function lists the active instances of this firewall, and Create Function Instance creates one from that list. A rule carries at most one Run Function behavior. To create an instance, refer to Instantiate a function on a firewall.

A behavior that runs one function instance:

For the code a firewall function runs, refer to Functions for Firewall.

Set Custom Response

Set Custom Response answers the request with the status code, content type, and body it sets, and requires no Product. The three settings go in attributes, as with every behavior that takes settings.

API

Every rule operation is authenticated and sits under https://api.azion.com/v4/workspace/firewalls/<firewall-id>/request_rules. A request carries a personal token in the Authorization header under the Token scheme, and a request with a body also carries Content-Type: application/json.

A create and a delete answer 202, and a read answers 200.

This call creates a rule that denies every request whose URI starts with /deny-test:

The response carries 202 and a state of pending. The response excerpt keeps the fields the platform added:

The platform adds description, an empty string when the create sends none, and order, the rule’s position on the firewall. The id in data is the handle every later call on the rule uses.

CLI

Azion CLI manages rules under the firewall-rule noun. azion create firewall-rule takes only --firewall-id and --file, so the criteria and behaviors of a rule live in the same JSON body the API takes.

This file describes a rule that denies requests from the countries in a Network List on /cli-rule:

Save it as rule.json, replace <network-list-id> with the list ID as an integer, and create the rule:

Errors

A rejected rule returns an errors array. Each entry carries a code, a title, a detail, the status, and a source pointer naming the field, and some entries add a meta object:

Two CLI rejections carry no code. A rule whose run_function behavior names a function instance that does not exist fails with Error: failed to create the Firewall Rule: ["Function Instance '99999999' not found."], with the ID the file sent. A behavior written with name instead of type fails with Error: Failed to decode the given 'json' file. Verify if the file format is JSON or fix its content according to the JSON format specification at https://www.json.org/json-en.html, although the file is valid JSON: the key the platform reads is type.

Related resources