# Network Lists A network list is a named set of IP addresses and CIDR ranges, Autonomous System Numbers (ASNs), or countries. A [firewall](/en/documentation/platform/firewall/) rule matches the address of a request's client against the list through the *Network* criterion, which [Network Shield](/en/documentation/platform/firewall/#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](/en/documentation/platform/workloads/) 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. | Field | Console label | Type | Required | Default | Description | | --------------- | ---------------------------------------------- | ------------------------------------------------------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `name` | **Name** | string, 1 to 250 characters | Yes | — | The list name. It is the option a rule's **Select a Network** dropdown shows, and it can change at any time. | | `type` | *ASN*, *IP/CIDR*, or *Countries* | string: `ip_cidr`, `asn`, or `countries` | Yes | — | What the items are. List types gives the item format of each type. The Console preselects *ASN*. | | `items` | **List**, or **Countries** on a countries list | array of 1 to 20,000 strings, each 1 to 250 characters | Yes | — | The entries a rule matches. Exact duplicates are removed, and the rest are stored in the order sent. | | `active` | None | boolean | No | `true` | Whether a rule can reference the list. The Console has no control for it. | | `id` | None | integer | Read-only | — | The identifier a rule carries as its `${network}` argument. | | `last_editor` | **Last Editor** | string | Read-only | — | The email of the account that last changed the list, or `Azion` on an Azion-maintained list. | | `last_modified` | **Last Modified** | date-time | Read-only | — | When the list last changed. | | `created_at` | None | date-time | Read-only | — | When the list was created. It is `null` on an Azion-maintained list. | 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](/en/documentation/platform/firewall/network-shield/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. | Type | Console label | Item format | Example | Annotations | | ----------- | ------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------ | | `ip_cidr` | *IP/CIDR* | An IPv4 or IPv6 address, with or without a prefix length. | `192.0.2.10`, `198.51.100.0/24`, `2001:db8::/32` | A due date and a comment, per Item annotations. | | `asn` | *ASN* | An Autonomous System Number, digits only. `AS64496` is refused with `22011`. | `64496`, from the range reserved for documentation. Azion's own ASN is `52580`. | None. An annotated item is refused with `22011`. | | `countries` | *Countries* | An ISO 3166-1 alpha-2 country code in two uppercase letters. `br`, `Brazil`, and `XX` are refused with `22015`. | `BR` | None. An annotated item is refused with `22015`. | 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: ```text [ --LTYYYY-MM-DDTHH:MM:SSZ][ #comment] ``` The platform accepts these items and stores them exactly as sent: ```text 192.0.2.1 #comment 192.0.2.2 --LT2030-01-01T00:00:00Z 192.0.2.5/32 --LT2030-01-01T00:00:00Z #both 2001:db8::1 --LT2030-01-01T00:00:00Z 192.0.2.9 #a comment with spaces ``` | Part | Syntax | Constraints | | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Due date | `--LT` and a UTC date and time, `YYYY-MM-DDTHH:MM:SSZ` | A space before `--LT`, the marker in uppercase, whole seconds, and a trailing `Z`. A date with no time or with fractional seconds is refused with `22007`, and a lowercase `--lt` makes the item invalid (`22005`). | | Comment | `#` and any text | Last on the line, after the due date when the item carries both. `--LT` cannot appear inside a comment. A line that starts with `#` is an invalid item (`22005`), not a disabled line. | 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](/en/documentation/platform/firewall/network-shield/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. | ID | Name | Type | Maintained by | | --- | ------------------------- | --------- | ------------- | | `2` | `Azion IP Tor Exit Nodes` | `ip_cidr` | Azion | 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](/en/documentation/guides/application-security/bots-and-network/block-tor-networks/). Any write to an Azion-maintained list is refused with `22004`, even a write that changes nothing. Accounts with [Origin Shield](/en/documentation/platform/connectors/#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: | Part | API | Azion Console | What it does | | ----------- | -------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Variable | `${network}` | *Network* | Compares the address of the client that sent the request, or the ASN or country of that address, with the list. | | Operator | `is_in_list` | *matches* | Is true when the client is in the list. | | Operator | `is_not_in_list` | *does not match* | Is true when the client is not in the list. | | Argument | The list `id`, as a JSON integer | The list name, picked in **Select a Network** | Names the list. An `id` sent as a string is refused with `25042`. | | Requirement | `modules.network_protection.enabled` set to `true` | **Main Settings** > **Modules** > **Network Shield** | The firewall must have Network Shield on, and a new firewall has it on by default. Otherwise the rule is refused with `25047`, and the Console shows the variable as *Network - required Network Shield*. Only the variable needs Network Shield; the behaviors a rule runs do not. | 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: ```json { "name": "Deny listed addresses", "active": true, "criteria": [ [ { "variable": "${network}", "conditional": "if", "operator": "is_in_list", "argument": } ] ], "behaviors": [ { "type": "deny" } ] } ``` For the other criteria a rule can chain with `${network}` and the behaviors a matched rule runs, refer to [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine/#criteria). For the counting window and key of a rate limit, refer to [Set Rate Limit](/en/documentation/platform/firewall/rules-engine/#set-rate-limit). --- ## API Every operation sits under `https://api.azion.com/v4` and carries a token from [Personal Tokens](/en/documentation/fundamentals/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](/en/documentation/devtools/api/). | Method | Path | Does | | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v4/workspace/network_lists` | Lists the network lists in the account, Azion-maintained lists included, without their `items`. Answers `200`. | | `POST` | `/v4/workspace/network_lists` | Creates a list. Answers `201` with a `state` of `executed`. | | `GET` | `/v4/workspace/network_lists/{network_list_id}` | Returns one list with its `items`. Answers `200` with no `state` key. | | `PUT` | `/v4/workspace/network_lists/{network_list_id}` | Replaces a list, and needs `name`, `type`, and `items`. Answers `200`. | | `PATCH` | `/v4/workspace/network_lists/{network_list_id}` | Changes the fields it sends. Answers `200`. | | `DELETE` | `/v4/workspace/network_lists/{network_list_id}` | Deletes a list. Answers `200` with a `state` of `executed`, or `400` with `22018` while a rule references the list. | 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`: | Parameter | What it does | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `id` | Filters by id. Accepts comma-separated values. | | `name` | Filters by name, with a case-insensitive partial match. | | `last_editor` | Filters by last editor, with a case-insensitive partial match. | | `last_modified__gte`, `last_modified__lte` | Filters by a last-modified date at or after, or at or before, the value. | | `list_type__in` | Filters by type. Accepts comma-separated values. The parameter keeps the `list_type` name, although the field is `type`. | | `search` | Filters by a search term. | | `ordering` | Names the field that orders the results. | | `fields` | Names the fields to return, comma-separated. | | `page` | Selects a page of results. | | `page_size` | Sets the lists per page, from 1 to 100. The default is 10. | `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: ```bash curl -X POST https://api.azion.com/v4/workspace/network_lists \ -H "Authorization: Token [TOKEN VALUE]" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"name":"Blocked addresses","type":"ip_cidr","items":["192.0.2.10","198.51.100.0/24","2001:db8::/32","192.0.2.10"]}' ``` The response carries `201` and stores the repeated address once: ```json { "state": "executed", "data": { "id": , "name": "Blocked addresses", "type": "ip_cidr", "items": ["192.0.2.10", "198.51.100.0/24", "2001:db8::/32"], "last_editor": "", "last_modified": "2026-01-01T12:00:00.000000Z", "created_at": "2026-01-01T12:00:00.000000Z", "active": true, "version_id": null, "version_state": null, "is_versioned": false, "version": null } } ``` ## Azion CLI [Azion CLI](/en/documentation/devtools/cli/) manages network lists under the `network-list` noun. The table lists the flags of Azion CLI 4.23.0. | Command | Does | Key flags | | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- | | `azion create network-list` | Creates a list. | `--name`, `--type`, `--items`, `--active`, `--file` | | `azion list network-list` | Lists the network lists in the account. | `--details`, `--filter`, `--order-by`, `--page` (default `1`), `--page-size` (default `50`) | | `azion describe network-list` | Returns one list. | `--network-list-id`, `--format json` | | `azion update network-list` | Changes a list. | `--network-list-id`, `--name`, `--items`, `--add-item`, `--remove-item`, `--active`, `--file` | | `azion delete network-list` | Deletes a list. | `--network-list-id` | `--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 `. `--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: ```bash azion create network-list --name "Blocked countries" --type countries --items "BR,US" ``` ```text Created Network List with ID ``` An item added to an existing list keeps the items already there: ```bash azion update network-list --network-list-id --add-item "192.0.2.72" ``` ```text Updated Network List with ID ``` A delete prints `Network List 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. | Interface | What it covers | Reference | | ----------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Terraform | The `azion_network_list` resource. | [Terraform security resources](/en/documentation/devtools/terraform/security/) | | Azion Lib | The `networkList` entry of a configuration. | [Azion Lib configuration](/en/documentation/devtools/azion-lib/config/) | | Azion IaC | The `networkList` entry of `azion.config.js`. | [Azion IaC](/en/documentation/devtools/cli/azion-config-js/) | | Runtime API | `Azion.networkList.contains()`, which checks an address against a list from a function on a firewall. | [Network List interface](/en/documentation/devtools/runtime/api-reference/network-list/) | 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: | Permission | Grants | | ---------------------- | ------------------------------------------------------------------------------------------------- | | **View Network Lists** | Viewing network lists, without creating, changing, or deleting them. | | **Edit Network Lists** | Viewing, creating, changing, and deleting network lists. It also requires **View 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](/en/documentation/fundamentals/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: ```json { "errors": [ { "code": "22005", "title": "Invalid IP CIDR", "detail": "IP CIDR is invalid.", "status": "400", "source": { "pointer": "/data/items" }, "meta": { "index": 1, "value": "abc" } } ] } ``` `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`. | Code | Title | Cause | Fix | | ------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `10004` | Not Found | The list id does not exist in the account, or the list was deleted. | Read the ids with `GET /v4/workspace/network_lists`. | | `10039` | Invalid Choice | A `type` other than `ip_cidr`, `asn`, or `countries`, such as `geo`. In a rule, the variable spelled `$(network)`. | Send one of the three types, and write the variable as `${network}`. | | `10046` | Max Length | A `name` or an item longer than 250 characters, annotations included. | Shorten the value the `source` pointer names. | | `10049` | Min Length List Field | An empty `items` array. | Send at least one item. | | `10059` | Required Field | A required field is absent, such as `type` on a create or `type` and `items` on a `PUT`. A body that uses the v3 names `list_type` and `ip_list` gets it twice, for `type` and `items`. | Send `name`, `type`, and `items`. | | `10065` | List Field Max Length | More than 20,000 items. | Send 20,000 items or fewer. | | `10097` | Invalid Page Size | A `page_size` above 100, or `0`, on the list operation. The message allows 0, and the API refuses it. | Ask for 1 to 100 lists per page. | | `22002` | Cannot Change Network List Type | An update that sends a `type` other than the list's own. The `detail` reads `You can not change the network list type.` | Create a list of the type you need, and point the rules at it. | | `22003` | Cannot Disable Network List In Use | `active: false` on a list that a rule references. The `detail` reads `You can not disable the network list in use by Edge Firewall(s).` | Change or delete the rules that reference the list. | | `22004` | Cannot Change Global Network List | Any write to an Azion-maintained list, even one that changes nothing. The `detail` reads `You can not change a global network list.` | Reference the list as it is, or create a list of your own. | | `22005` | Invalid IP CIDR | An `ip_cidr` item that is not an IPv4 or IPv6 address or range, including a line that starts with `#` and a lowercase `--lt`. | Correct the item that `meta.index` and `meta.value` name. | | `22007` | Due Date Invalid Format | A due date with no time, or with fractional seconds. The `detail` reads `Due date with invalid format, needs to start with --LT and end with Z.` | Write the date as `--LTYYYY-MM-DDTHH:MM:SSZ`. | | `22011` | Invalid ASN Number | An `asn` item that is not digits only, such as `abc`, `AS64496`, or an item with a comment. The `detail` reads `This ASN Number is not valid.` | Send the number alone. | | `22015` | Invalid Country | A `countries` item that is not two uppercase ISO 3166-1 alpha-2 letters, such as `br`, `Brazil`, or `XX`, or an item with a due date. The `detail` reads `This country is not valid.` | Send the two-letter code alone. | | `22018` | Cannot Delete In Use Network List | A `DELETE` on a list that a rule references. The `detail`, `You can not delete the network list in use by Edge Firewall(s).`, names neither the firewall nor the rules. | Delete the referencing rules, or point them at another list, then delete the list again. The check clears as soon as the rule delete is accepted: a list delete went through 3 seconds after the last rule delete. | | `22019` | All Network Items Are Expired | Every item carries a due date that has passed. The `detail` reads `All items in the network items are past their expiration date.` | Send at least one item with no due date or a future one. | | `24005` | Cannot Disable Firewall Network Protection Module | Turning off Network Shield on a firewall that has `${network}` rules. The `detail` lists the rule ids. | Delete or change the rules the `detail` names, then turn Network Shield off. | | `25030` | Entity Not Found | A `${network}` argument that names a list the account does not hold. | Send the id of a list in the account. | | `25031` | Entity Not Active | A `${network}` argument that names a list with `active: false`. | Set the list's `active` to `true`, then create the rule. | | `25039` | Invalid Operator | `matches`, the Console label, sent as the `${network}` operator. | Send `is_in_list` or `is_not_in_list`. | | `25042` | Invalid Operator Argument Type | A `${network}` argument sent as a JSON string. | Send the list id as a JSON integer. | | `25047` | Missing Required Modules | A `${network}` rule on a firewall whose Network Shield is off. | Turn on Network Shield for the firewall, then create the rule. | ## 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](/en/documentation/platform/firewall/limits/#network-shield). --- ## Related resources - [List matching](/en/documentation/platform/firewall/network-shield/list-matching.md): How a rule matches a client address against a list, and how long a change to a list takes to reach traffic. - [Network Shield quickstart](/en/documentation/platform/firewall/network-shield/quickstart.md): The first list and the rule that blocks it, from creation to a refused request. - [Block requests by IP, ASN, or country](/en/documentation/guides/application-security/bots-and-network/blocklists-ip-addresses-edge.md): The procedure that builds a blocklist or an allowlist and applies it to a firewall. - [Troubleshoot Firewall](/en/documentation/platform/firewall/troubleshooting.md#network-shield): What to check when a list does not block a client, or blocks one it should not.