---
title: "Custom rules"
description: "Allow, block, log or rate limit requests by client IP, ASN, country, method, path, query, headers, cookies and body."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom rules

A WAF's `rules` run top to bottom, before its [managed rule sets](/waf/managed-rule-sets). The first
matching rule that ends the request wins. A WAF has at most 100 rules.

```json
{
  "name": "block-scanners",
  "action": "block",
  "mode": null,
  "rateLimit": null,
  "conditions": [
    { "type": "regex", "negate": false, "target": "header:user-agent", "value": "(sqlmap|nikto|masscan)", "caseSensitive": false }
  ]
}
```

| Field | |
| --- | --- |
| `name` | 1 to 64 lowercase letters, digits and dashes, unique in the WAF. |
| `action` | `allow`, `block`, `log` or `rateLimit`, below. |
| `mode` | `rateLimit` only: `block` (the default) or `log`. `null` for other actions. |
| `rateLimit` | `rateLimit` only: `{ "limit", "windowSeconds" }`. `null` for other actions. See [Rate limits](/waf/rate-limits). |
| `conditions` | 1 to 5 conditions. A rule matches when all of them do. |

## Actions

| `action` | A matching request |
| --- | --- |
| `allow` | Goes to its target. Later rules and the managed rule sets don't run. |
| `block` | Is answered `403`. |
| `log` | Is recorded, and evaluation goes on with the next rule. |
| `rateLimit` | Is counted for its client IP. A client over the limit is blocked, or recorded with `mode` `log`. See [Rate limits](/waf/rate-limits). |

The WAF's `mode` of `log` turns every `block` into a log, rate limits included.

## Conditions

Each condition has a `type` and `negate`. With `negate` `true`, the condition matches when it doesn't
hold.

| `type` | Matches when | Fields |
| --- | --- | --- |
| `ipSet` | The client IP is in one of the blocks | `cidrs`: 1 to 1,000 IPv4 and IPv6 addresses and CIDR blocks, such as `203.0.113.0/24` and `2001:db8::/32` |
| `asn` | The client IP is announced by one of the autonomous systems | `numbers`: 1 to 100 AS numbers |
| `country` | The client IP is in one of the countries | `codes`: 1 to 250 ISO 3166-1 alpha-2 codes in capitals, such as `DE` |
| `regex` | The target matches a regular expression | `target`, `value`, `caseSensitive` |
| `contains` | The target contains the value | `target`, `value`, `caseSensitive` |
| `equals` | The target is the value | `target`, `value`, `caseSensitive` |

Country and ASN come from DB-IP data, refreshed monthly.

### Targets

| `target` | |
| --- | --- |
| `path` | The request's path |
| `query` | The query string |
| `method` | The HTTP method, such as `POST` |
| `header:<name>` | A request header, such as `header:user-agent` |
| `cookie:<name>` | A cookie, such as `cookie:session` |
| `body` | The first 16 KB of a request body |

A header or cookie name is 1 to 64 letters, digits, `-` and `_`.

### Values

- `value` is at most 1,024 bytes of UTF-8. Only `equals` takes an empty value.
- Matching is case-insensitive unless `caseSensitive` is `true`.
- A `regex` uses the syntax RE2 and Rust's `regex` both accept: no backreferences or lookaround. An
  expression outside it is `400 invalid_request`, naming the problem.

## Allow before block

Rules are checked in order, so put an `allow` above the rules it exempts. This lets your office through
every rule and managed set, and blocks other countries than the two you serve:

```json
"rules": [
  {
    "name": "office",
    "action": "allow",
    "mode": null,
    "rateLimit": null,
    "conditions": [{ "type": "ipSet", "negate": false, "cidrs": ["198.51.100.0/24"] }]
  },
  {
    "name": "outside-us-ca",
    "action": "block",
    "mode": null,
    "rateLimit": null,
    "conditions": [{ "type": "country", "negate": true, "codes": ["US", "CA"] }]
  }
]
```

See also [Block an IP range](/waf/guides/block-an-ip-range).

This product includes IP data from [DB-IP](https://db-ip.com), licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

Source: https://docs.ezghcloud.com/waf/custom-rules/index.mdx
