Network Lists

A network list is a named set of IP addresses and CIDR ranges, Autonomous System Numbers (ASNs), or countries. A firewall rule matches the address of a request’s client against the list through the Network criterion, which Network Shield makes available on the firewall. Creating a list needs no firewall, and a list matches nothing until a rule on a firewall bound to a workload references it.

Network list fields

A network list carries four fields that a request sets and four that the platform sets and returns. A create and a PUT must send name, type, and items, while a PATCH sends only the fields it changes.

The type never changes after creation. An update that sends another type is refused with 22002, even when its items fit the new type, and the Console locks the type with the tag The type cannot be changed after the network list is created. To match another kind of entry, create a list of that type.

Setting active to false never pauses a rule that is matching. A list that a rule references cannot be set to false (22003), and a rule cannot reference a list set to false (25031). To stop a list from matching, change or delete the rules that reference it.

A response also carries version_id, version_state, is_versioned, and version, which a request does not set.

One list can be referenced by many rules on many firewalls. A change to its items changes what every one of those rules matches, with no redeploy. The API stores the write at once, and the change then reaches traffic as it propagates. For how long that takes, refer to List matching.

List types

The type of a list sets the format of every item in it. Each type has one API value and one Console label.

In Azion Console, the List field takes one entry per line for IP/CIDR and ASN. It accepts IPv4 prefixes from /0 to /32 and IPv6 prefixes up to /128, and its help text also accepts an ASN written as AS13335. The field checks every line before saving and names each one it rejects, with messages such as --LT must be a valid UTC date and time in the format YYYY-MM-DDTHH:MM:SSZ, add a space before --LT, and the --LT date must be in the future. The Countries field is a multiselect by country name, and the Console sends the two-letter code of each country picked.

Item annotations

An ip_cidr item can carry a due date, a comment, or both, after the address. asn and countries items accept neither. An annotated item follows this grammar:

The platform accepts these items and stores them exactly as sent:

Annotations count toward the 250 characters an item can hold. Each time a request writes items, on a create or an update, the platform processes them before it stores them:

• Exact duplicates are removed without a warning. Equivalent notations are not duplicates, so 192.0.2.80 and 192.0.2.80/32 are both kept.
• An item whose due date has already passed is dropped without a warning. When every item is past due, the write is refused with 22019.
• The items that remain are stored as sent, annotations included, in the order sent.

The platform does not remove an item when its due date passes after the write. The item stays stored and keeps matching until a later write of items, or azion update network-list --remove-item, removes it. For how a due date reaches traffic, refer to List matching.

Azion-maintained lists

Azion maintains lists that a rule in any account can reference and that no account can change. The Network Lists page in Azion Console and GET /v4/workspace/network_lists return them beside the lists you create.

List 2 holds the IP addresses of Tor exit nodes, and Azion provides it to every account. Its last_editor reads Azion, and its last_modified changes when Azion refreshes the items. A rule references it like any list you create, with 2 as the ${network} argument. For a rule that uses it, refer to Block Tor exit nodes.

Any write to an Azion-maintained list is refused with 22004, even a write that changes nothing.

Accounts with Origin Shield also receive the Azion Origin Shield list, which holds the IPv4 and IPv6 prefixes that Azion’s infrastructure uses to connect to origins. The Origin Shield page documents that list and how Azion announces its updates.

The Network criterion

A firewall rule references a network list through the ${network} criterion. The table names its variable, its two operators, its argument, and the firewall setting it requires:

A list acts as a blocklist with matches and Deny (403 Forbidden), and as an allowlist with does not match and the same behavior. In a request body for /v4/workspace/firewalls/{firewall_id}/request_rules, the criterion is one entry of a criteria block:

For the other criteria a rule can chain with ${network} and the behaviors a matched rule runs, refer to Rules Engine for Firewall. For the counting window and key of a rate limit, refer to Set Rate Limit.

API

Every operation sits under https://api.azion.com/v4 and carries a token from Personal Tokens in an Authorization: Token [TOKEN VALUE] header. A request with a body also sends Content-Type: application/json. For more information, refer to Get started with Azion API.

A PATCH that sends items replaces the whole array instead of adding to it, so an update sends every item the list keeps. To add or remove single items without resending the list, use --add-item and --remove-item in Azion CLI.

GET /v4/workspace/network_lists accepts these query parameters, and its response carries count, total_pages, page, page_size, next, previous, and results:

GET /v4/workspace/network_lists/{network_list_id} accepts fields too. On an ip_cidr list, ipv4=true returns only the IPv4 items and ipv6=true only the IPv6 items.

This request creates an ip_cidr list and sends 192.0.2.10 twice:

The response carries 201 and stores the repeated address once:

Azion CLI

Azion CLI manages network lists under the network-list noun. The table lists the flags of Azion CLI 4.23.0.

--type takes asn, countries, or ip_cidr, and --items, --add-item, and --remove-item take comma-separated values. --items replaces every item, as a PATCH does, while --add-item and --remove-item read the list first and change only the items they name. --remove-item matches an item exactly as it is stored, its --LT due date and # comment included. Given only the address of an annotated item, it changes nothing and still prints Updated Network List with ID <network-list-id>. --file takes a JSON file with the fields of Network list fields. azion update network-list also takes --type, which the API refuses with 22002 because a type never changes.

The id flag is --network-list-id, and --id is refused as an unknown flag. With neither --items nor --file, azion create network-list prompts for the items and fails when no terminal answers, so a script always passes one of them. azion list network-list --format json prints the table columns, not the records. The help of azion describe network-list lists a --with-code flag, which the command refuses as unknown.

A create from the command line prints the new id:

An item added to an existing list keeps the items already there:

A delete prints Network List <network-list-id> was successfully deleted. When the API refuses a command, the CLI prints the API’s detail. A delete of a list in use prints Error: Failed to delete Network List: ["You can not delete the network list in use by Edge Firewall(s)."].

Other interfaces

These interfaces manage or read network lists too, and each one’s own page documents it.

A rule with the Network criterion matches a list with no code. A function on a firewall calls Azion.networkList.contains() instead when the match feeds logic of its own, and the call returns true when the address is in the list.

Permissions

Two team permissions govern network lists:

The firewall whose rules reference a list has its own pair, View Firewall and Edit Firewall. For more information, refer to Teams Permissions.

Errors

A refused request returns an errors array. Each entry carries a code, a title, a detail, the status, and a source pointer naming the field. An item error adds meta.index and meta.value, and it names only the first invalid item. This body answers a create whose items are 192.0.2.1, abc, and 198.51.100.300, and it reports abc alone:

meta.index counts the items that remain after past-dated items are dropped, so it can be lower than the item’s position in the request. Every error below answers 400, except 10004, which answers 404.

Limits

A network list holds 1 to 20,000 items of up to 250 characters each, under a name of 1 to 250 characters, and a list request returns up to 100 lists per page. For every bound and what happens past it, refer to Firewall limits.

Related resources