Skip to content

Custom rules

Allow, block, log or rate limit requests by client IP, ASN, country, method, path, query, headers, cookies and body.

Updated View as Markdown

A WAF’s rules run top to bottom, before its managed rule sets. The first matching rule that ends the request wins. A WAF has at most 100 rules.

{
  "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.
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.

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:

"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.

This product includes IP data from DB-IP, licensed under CC BY 4.0.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close