# IP address lists




IP address lists are a feature that let you organize allowed and forbidden IP addresses into reusable lists with common attributes.

They make it possible to apply specific policy settings to incoming requests based on the source IP address.

Each IP address list includes:
- A unique name
- An enforcement type (`always`, `never`, or `policy-default`)
- A list of IP addresses

For the `ipAddress` value, use either a single IP (`192.0.2.1`) or a CIDR network address (`192.0.2.0/24`). `192.0.2.1/24` is invalid. `192.0.2.1/32` is valid and equivalent to `192.0.2.1`.

Here is an example of a declarative policy using an IP address lists configuration:

```json
{
  "policy": {
    "name": "IpGroups_policy",
    "template": {
       "name": "POLICY_TEMPLATE_NGINX_BASE"
    },
    "applicationLanguage": "utf-8",
    "caseInsensitive": false,
    "enforcementMode": "blocking",
    "ip-address-lists": [
       {
         "name": "Standalone",
         "description": "Optional Description",
         "blockRequests": "policy-default",
         "setGeolocation": "IN",
         "ipAddresses": [
          {
             "ipAddress": "1.2.3.4/32"
          },
          {
             "ipAddress": "1111:fc00:0:112::2"
          }
        ]
      }
    ]
  }
}
```

The following example shows an IP group definition stored in an external file `external_ip_groups.json`:

```json
{
  "policy": {
    "name": "IpGroups_policy2",
    "template": {
       "name": "POLICY_TEMPLATE_NGINX_BASE"
    },
    "applicationLanguage": "utf-8",
    "caseInsensitive": false,
    "enforcementMode": "blocking",
    "ip-address-lists": [
      {
        "name": "external_ip_groups",
        "description": "Optional Description",
        "blockRequests": "always",
        "setGeolocation": "IL",
        "$ref": "file:///tmp/policy/external_ip_groups.json"
      }
    ]
  }
}
```

Example of the file `external_ip_groups.json`:

```json
{
    "name": "External IP address lists",
    "description": "Optional Description",
    "blockRequests": "always",
    "setGeolocation": "IR",
    "ipAddresses": [
      {
        "ipAddress": "66.51.41.21"
      },
      {
        "ipAddress": "66.52.42.22"
      }
    ]
}
```

## IP address lists in policy override rules conditions

The **Override Rules** feature allows you to override original or parent policy settings.

Rules are defined using specific conditions, which can include an IP address list based on the declarative policy JSON schema.

When triggered, the rule is applied to the `clientIp` attribute using the `matches` function:

`clientIp.matches(ipAddressLists["standalone"])`

Here is a policy example:

```json
{
  "policy": {
    "name": "ip_group_override_rule",
    "template": {
      "name": "POLICY_TEMPLATE_NGINX_BASE"
    },
    "applicationLanguage": "utf-8",
    "caseInsensitive": false,
    "enforcementMode": "blocking",
    "ip-address-lists": [
      {
        "name": "standalone",
        "ipAddresses": [
          {
            "ipAddress": "1.1.1.1/32"
          }
        ]
      }
     ],
     "override-rules": [
      {
        "name": "myRule1",
        "condition": "clientIp.matches(ipAddressLists['standalone'])",
        "actionType": "extend-policy",
        "override": {
          "policy": {
            "enforcementMode": "transparent"
          }
        }
      }
    ]
  }
}
```

The previous example policy contains an IP address list named `standalone`, which is used in the override rule condition `clientIp.matches(ipAddressLists['standalone'])`.

This condition means that the rule enforcement is applied and overrides the base policy enforcement whenever the `clientIp` matches one of the `ipAddresses` in the `ip-address-list` named `standalone`.

The value used in the override condition must exist and exactly match the name defined in `ip-address-lists`.

### Possible errors

| Error text                              | Input                                             | Explanation                                               |
|-----------------------------------------|---------------------------------------------------|-----------------------------------------------------------|
| Invalid field `invalidList`             | `clientIp.matches(invalidList['standalone']);`    | An incorrect keyword was used instead of `ipAddressLists` |
| Invalid value empty string              | `clientIp.matches(ipAddressLists[''])`            | An empty name was provided                                |
| Failed to compile policy - `ipGroupOverridePolicy` | `uri.matches(ipAddressLists['standalone']);`     | Used `ipAddressLists` without the `clientIp` attribute    |