# Network Shield quickstart

This guide instructs you through blocking your first request with a network list in [Network Shield](/en/documentation/platform/firewall/#network-shield).

- Create a network list that holds your own public IP address.
- Deny that list on one test path with a firewall rule.
- Send a request to the test path and read the refusal.

Four objects take part in the block, and each one links to the next:

1. A [network list](/en/documentation/platform/firewall/network-shield/network-lists/) holds the addresses to match. In this guide, it holds your own public IP address.
2. A rule in the [Rules Engine](/en/documentation/platform/firewall/rules-engine/) of a [firewall](/en/documentation/platform/firewall/) matches that list with the *Network* criterion and denies the request. A second criterion limits the rule to the `/network-shield-test` path, so the rest of your application keeps answering you.
3. The firewall carries the rule, and it must have Network Shield on. A firewall has Network Shield on by default.
4. The [workload](/en/documentation/platform/workloads/) that serves your application is bound to that firewall, so its requests pass through the rule.

A network list blocks nothing by itself. Until a rule on a firewall bound to a workload references it, the list matches no request.

---

Select an interface for this guide. The prerequisites and each stage switch to the interface you select.

## Prerequisites

- An Azion account. To create one, refer to [How to create an account on Azion](/en/documentation/fundamentals/creating-account/).
- A workload that serves your application and is bound to a firewall. To bind one, refer to [Bind a firewall to a workload](/en/documentation/guides/application-security/firewall-and-waf/firewall-protect-your-domain/).
- Network Shield on for that firewall, which is the default. To check the setting, refer to [Set a firewall's main settings](/en/documentation/guides/application-security/firewall-and-waf/firewall-configure-main-settings/#change-the-products-enabled-on-a-firewall).
- The **Edit Network Lists** and **Edit Firewall** permissions. For more information, refer to [Network Lists](/en/documentation/platform/firewall/network-shield/network-lists/#permissions).
- Your public IPv4 address, the one your requests to the workload come from.

**Console**

- Access to Azion Console. To sign in, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/).

**CLI**

- [Azion CLI](/en/documentation/devtools/cli/), installed and authorized. The commands in this guide match Azion CLI 4.23.0.
- The ID of the firewall bound to your workload.

**API**

- A personal token and `curl`. To create a token, refer to [Personal Tokens](/en/documentation/fundamentals/personal-tokens/).
- The ID of the firewall bound to your workload.

---

## Create a network list

A network list holds the entries that a rule matches, and its type fixes what kind of entry they are. The list in this stage has the `ip_cidr` type, *IP/CIDR* in Azion Console. It holds one item: your public IPv4 address with the `/32` prefix, which covers that address alone. The type of a list never changes after creation.

**Console**

To create the list in Azion Console:

1. **Open the Network Lists page**

   Access [Azion Console](https://console.azion.com/) > **Edge Libraries** > **Network Lists**.

2. **Start a list**

   Select **Network List**.

3. **Name the list**

   In the **General** section, enter a **Name**. For example: `network-shield-quickstart`.

4. **Select the IP/CIDR type**

   In the **Network List Settings** section, select *IP/CIDR*. The form opens with *ASN* selected.

5. **Enter your address**

   In the **List** field, enter `<your-ip>/32`, with your public IPv4 address in place of `<your-ip>`.

6. **Save the list**

   Select **Save**.

Azion Console shows the message `Your network list has been created`. The list appears in **Network Lists**, with *IP/CIDR* in the **List Type** column.

**CLI**

To create the list with Azion CLI:

1. **Run the create command**

   Replace `<your-ip>` with your public IPv4 address:

   ```bash
   azion create network-list --name "network-shield-quickstart" --type ip_cidr --items "<your-ip>/32"
   ```

2. **Read the output**

   The command prints the ID of the list it created:

   ```text
   Created Network List with ID <network-list-id>
   ```

The list holds one item, your address. Record its ID, which you pass to the rule.

**API**

To create the list, send a `POST` request to `/v4/workspace/network_lists`:

1. **Send the create request**

   Replace `[TOKEN VALUE]` with your personal token and `<your-ip>` with your public IPv4 address:

   ```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":"network-shield-quickstart","type":"ip_cidr","items":["<your-ip>/32"]}'
   ```

2. **Read the response**

   A create answers `201`, and a `state` of `executed` means the API stored the list at once:

   ```json
   {
     "state": "executed",
     "data": {
       "id": <network-list-id>,
       "name": "network-shield-quickstart",
       "type": "ip_cidr",
       "items": ["<your-ip>/32"],
       "last_editor": "<your-email>",
       "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
     }
   }
   ```

The list holds one item, your address. Record the value of `data.id`, which you pass to the rule as a number.

---

## Deny the list on a test path

A rule in Rules Engine for Firewall runs its behavior only when its criteria are true. The rule in this stage joins two criteria with `and` in one block, so both must be true. The *Network* criterion matches the addresses in your list, and a *Request Uri* criterion matches paths that start with `/network-shield-test`. The *Deny (403 Forbidden)* behavior then refuses the request.

The test path is how this guide tests a block without refusing real traffic. The rule denies only requests from your address to `/network-shield-test`, and it lets every other request through.

**Console**

To create the rule in Azion Console:

1. **Open the firewall bound to your workload**

   Access [Azion Console](https://console.azion.com/) > **Secure** > **Firewalls**, and select the firewall.

2. **Select the Rules Engine tab**

3. **Start a rule**

   Select **Rule**. The **Create Rule** drawer opens.

4. **Name the rule**

   In the **General** section, enter a **Name**. For example: `Deny my address on the test path`.

5. **Set the Network criterion**

   In the **Criteria** section, select the *Network* variable and the *matches* operator.

   If the variable reads *Network - required Network Shield*, the firewall has Network Shield off. The variable becomes selectable after you turn Network Shield on in **Main Settings** and save.

6. **Select your list**

   In the **Select a Network** dropdown, select the list you created. For example: `network-shield-quickstart`.

7. **Add a second condition**

   To add a condition that must also be true, select **And**.

8. **Scope the rule to the test path**

   In the added condition, select the *Request Uri* variable and the *starts with* operator, and enter `/network-shield-test`.

9. **Add the Deny behavior**

   In the **Behaviors** section, select *Deny (403 Forbidden)*.

10. **Save the rule**

    Select **Save**.

Azion Console shows the message `Rule successfully created`. The rule appears in the **Rules Engine** tab, with *Active* in the **Status** column.

**CLI**

`azion create firewall-rule` takes only two flags, `--firewall-id` and `--file`, so the rule goes in a JSON file. To create it with Azion CLI:

1. **Write the rule to a file**

   Save the following as `rule.json`. Replace `<network-list-id>` with the ID of your list, as a number without quotes:

   ```json
   {
     "name": "Deny my address on the test path",
     "active": true,
     "criteria": [
       [
         { "variable": "${network}", "conditional": "if", "operator": "is_in_list", "argument": <network-list-id> },
         { "variable": "${request_uri}", "conditional": "and", "operator": "starts_with", "argument": "/network-shield-test" }
       ]
     ],
     "behaviors": [
       { "type": "deny" }
     ]
   }
   ```

2. **Create the rule**

   Replace `<firewall-id>` with the ID of your firewall:

   ```bash
   azion create firewall-rule --firewall-id <firewall-id> --file rule.json
   ```

3. **Read the output**

   The command prints the ID of the rule it created:

   ```text
   Created Firewall Rule with ID <rule-id>
   ```

The rule is active on the firewall. The last stage confirms that it denies your request.

**API**

To create the rule, send a `POST` request to `/v4/workspace/firewalls/{firewall_id}/request_rules`:

1. **Send the create request**

   Replace `[TOKEN VALUE]` with your personal token and `<firewall-id>` with the ID of your firewall. Replace `<network-list-id>` with the ID of your list, as a number without quotes:

   ```bash
   curl -X POST https://api.azion.com/v4/workspace/firewalls/<firewall-id>/request_rules \
     -H "Authorization: Token [TOKEN VALUE]" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
     "name": "Deny my address on the test path",
     "active": true,
     "criteria": [
       [
         { "variable": "${network}", "conditional": "if", "operator": "is_in_list", "argument": <network-list-id> },
         { "variable": "${request_uri}", "conditional": "and", "operator": "starts_with", "argument": "/network-shield-test" }
       ]
     ],
     "behaviors": [
       { "type": "deny" }
     ]
   }'
   ```

2. **Read the response**

   A create answers `202` with the rule as stored. The `order` field is the position of the rule among the rules of the firewall, counted from `0`:

   ```json
   {
     "state": "pending",
     "data": {
       "id": <rule-id>,
       "name": "Deny my address on the test path",
       "active": true,
       "criteria": [
         [
           { "conditional": "if", "variable": "${network}", "operator": "is_in_list", "argument": <network-list-id> },
           { "conditional": "and", "variable": "${request_uri}", "operator": "starts_with", "argument": "/network-shield-test" }
         ]
       ],
       "behaviors": [{ "type": "deny" }],
       "description": "",
       "order": 0
     }
   }
   ```

An `argument` sent as a string, such as `"<network-list-id>"` in quotes, is refused with `400` and `25042 Invalid Operator Argument Type`. On a firewall with Network Shield off, the request is refused with `25047 Missing Required Modules`.

---

## Verify that the request is denied

The check is the same whichever interface created the rule. Your workload answers on its workload domain, which ends in `.map.azionedge.net`. The commands write it as `<your-workload-domain>`.

A rule you add needs several minutes to take effect across Azion's distributed infrastructure. Until then, the test path answers as any other path does. Wait, then send the request again. For more information, refer to [How Firewall works](/en/documentation/platform/firewall/how-it-works/#propagation).

Send a request to the test path. The `-4` flag sends it over IPv4, the address family of the item in your list:

```bash
curl -4 -i https://<your-workload-domain>/network-shield-test
```

The firewall denies the request:

```text
HTTP/2 403
server: nginx
date: Thu, 01 Jan 2026 12:00:00 GMT
content-type: text/html; charset=utf-8
x-content-type-options: nosniff
x-azion-request-id: <request-id>
x-azion-edge-location: <edge-location>
alt-svc: h3=":443"; ma=86400

<title>Azion - Default error page</title>
...
<h1 class="error-header__title">Forbidden</h1>
...
Your IP         <your-ip>
Request ID      <request-id>
Status Code     403
Edge Location   <edge-location>
```

The body is Azion's default error page, headed **Forbidden**. Its Your IP row shows the address that the firewall compared with the list, which is your own. No header names the firewall, the rule, or the list. The `x-azion-request-id` header identifies the request. To look up the request in the logs, refer to [Real-Time Events](/en/documentation/platform/real-time-events/).

Send the same request to another path of the workload:

```bash
curl -4 -i https://<your-workload-domain>/
```

The firewall lets the request through, and your application answers it:

```text
HTTP/2 204
server: nginx
date: Thu, 01 Jan 2026 12:00:00 GMT
x-azion-request-id: <request-id>
x-azion-edge-location: <edge-location>
alt-svc: h3=":443"; ma=86400
```

Your application decides that status. An application that serves no content answers `204`. What matters is that the response is not the `403` error page.

Network Shield now denies your address on `/network-shield-test`, and every other path still answers you.

---

## Next steps

- [List matching](/en/documentation/platform/firewall/network-shield/list-matching.md): What the Network criterion compares, what each behavior returns, and how long a change takes to reach traffic.
- [Network Lists](/en/documentation/platform/firewall/network-shield/network-lists.md): The list types, item formats, annotations, and errors, before you build a list for real traffic.
- [Block requests by IP, ASN, or country](/en/documentation/guides/application-security/bots-and-network/blocklists-ip-addresses-edge.md): Build a list of addresses, networks, or countries for real traffic, and deny it in a firewall rule.
- [Block Tor exit nodes](/en/documentation/guides/application-security/bots-and-network/block-tor-networks.md): Block the addresses in the Tor exit node list that Azion maintains and refreshes.
- [Allow only the addresses in a list](/en/documentation/guides/application-security/bots-and-network/allowlist.md): Switch the operator to does not match, so a rule denies every address outside the list.
- [Firewall limits](/en/documentation/platform/firewall/limits.md#network-shield): The bounds on a list and its items, and the Firewall usage each service plan includes.