skip to content

In a Cloudflare WAF custom rule, what do the expression and the action do, and how would you block a scraper on one search endpoint?

level: juniorimportance: must knowfreq 62%

answer

  1. two parts per rule
  2. field, operator, value
  3. path and network together
  4. ip.src.asnum in an inline set

basics

~20 s

A WAF custom rule pairs a Rules language expression, which tests request fields such as http.request.uri.path and ip.src.asnum, with an action such as Block or Managed Challenge that Cloudflare applies to every request the expression matches.

solid answer

~40 s

A custom rule has two parts: an **expression** written in the Rules language and an **action**. The expression compares request fields with values, for example `http.request.uri.path eq "/search"`, and joins comparisons with `and`, `or` and `not`. The action says what happens on a match: `Block`, `Managed Challenge`, `Skip`, or `Log` on Enterprise. Custom rules run in the `http_request_firewall_custom` phase, top to bottom. For a scraper that hits one search endpoint from a few networks, I would match both the path and the networks, `http.request.uri.path eq "/search" and ip.src.asnum in {64496 64500}`, with Block. Then other people on those networks can still use the rest of the site, and the scraper gets the WAF block response, a 403 by default.

code

plaintext · 1 line
plaintext
http.request.uri.path eq "/search" and ip.src.asnum in {64496 64500}

go deeper

for a junior

Recall the two parts of a custom rule, expression and action, and write a field operator value comparison such as http.request.uri.path eq "/search" from memory.

for a middle

Explain why the rule combines the path with the networks, which operators are case-sensitive, and which actions and list types each plan allows.

for a senior

Show you size a rule's blast radius before deploying it: who else shares those networks, which paths the expression really covers, and how you would confirm that in Security Events.

for a principal

Talk about keeping a zone's handful of rules readable as they accumulate: naming, one purpose per rule, and lists instead of addresses copied into many expressions.

## What a custom rule is A **WAF custom rule** is a filter you write yourself and run on Cloudflare's edge before a request reaches your origin. Cloudflare's **Ruleset Engine** evaluates it in the `http_request_firewall_custom` phase. Every rule has two parts: - an **expression**: a test written in the **Rules language** that is either true or false for a request; - an **action**: what Cloudflare does when the expression is true. Custom rules are evaluated **in order**, top to bottom. A terminating action such as Block or Managed Challenge stops evaluation, so the rules below it never see that request. ## Writing the expression A simple expression is `<field> <operator> <value>`. Fields are values Cloudflare computes for each request. The ones this kind of rule uses most: | Field | Type | Example value | |---|---|---| | `http.request.uri.path` | String | `"/search"` (no query string) | | `http.request.method` | String, uppercase | `"POST"` | | `ip.src` | IP address | `198.51.100.7` | | `ip.src.asnum` | Number | `64496` | | `ip.src.country` | String, ISO 3166-1 alpha-2 | `"DE"` | Common operators: - `eq` / `ne`: exact equality, **case-sensitive** for strings; - `in`: membership in an inline set such as `{64496 64500}` or in a named list such as `$office_network`; - `contains`: substring match, case-sensitive; - `wildcard`: whole-value match with `*`, case-insensitive (`strict wildcard` is the case-sensitive form); - `matches`: regular expressions, available on **Business and Enterprise** only. English-notation operators (`eq`, `and`, `or`, `not`) must be lowercase. Comparisons combine with `not`, `and`, `xor` and `or`. Use parentheses to make grouping explicit, because `and` binds tighter than `or`. ## Choosing the action | Action | API value | Effect | |---|---|---| | Block | `block` | Denies the request with the WAF block response, 403 by default | | Managed Challenge | `managed_challenge` | Cloudflare chooses a non-interactive or interactive challenge | | Non-Interactive Challenge | `js_challenge` | Browser must run a challenge script | | Interactive Challenge | `challenge` | Visitor must interact to pass | | Skip | `skip` | Skips remaining custom rules, later phases or listed products | | Log | `log` | Records the match only; Enterprise plans only | Block, the three challenges and Skip are available on every plan. On Pro and above a Block can carry a **custom response**: a status code from 400 to 499 and an HTML, text, JSON or XML body of up to 2 KB. ## The scraper rule The operations team sees one search endpoint hammered from a few networks. The precise rule matches **both** conditions, so it touches nobody else: ```plaintext http.request.uri.path eq "/search" and ip.src.asnum in {64496 64500} ``` With the action Block, those networks can still load every other page, and everyone else can still search. Matching only the networks would cut off every customer who shares them. Matching only the path would block every searcher. ## Plan limits that shape the rule 1. **Rule count** per zone: 5 on Free, 20 on Pro, 100 on Business, 1,000 on Enterprise. 2. **Lists**: custom IP lists exist on every plan (Free gets one list); lists of ASNs or hostnames are Enterprise-only, so on lower plans networks go in an inline set like `{64496 64500}`. 3. **Regex**: `matches` needs Business or Enterprise; `eq`, `in`, `contains` and `wildcard` work everywhere. 4. **Log** is Enterprise-only, which matters when you want to try a rule before enforcing it. ## Reading what the rule did A deployed rule leaves evidence in **Security Events**, the security analytics view for the zone: - each match is recorded with the action taken and the rule that took it, under the source **Custom Rules**; - **Top events by source** breaks matches down by IP address, ASN, country, path, host and user agent, which is how you confirm the rule caught the two scraper networks and nothing else; - a rule that has since been deleted shows as `Rule unavailable`, and the account's audit logs record who changed it. If the breakdown shows networks or paths you did not intend, narrow the expression before the next wave of complaints. If the scraper moves to a new network, add that ASN to the inline set, or, for a few addresses, to an IP list, rather than writing a second near-identical rule. On Free, with five rules per zone, every rule has to earn its place, so one well-scoped rule beats several overlapping ones. ## Habits that keep a rule precise - Combine *what* is requested (path, method) with *who* is requesting (network, address, country). - Prefer `eq` or an inline set to `contains`: `contains "/search"` also matches `/search-help`. - Give every rule a descriptive name; Security Events shows matches by rule, with the source **Custom Rules**. - Write the expression in the **Expression Editor** when it needs parentheses or functions; the Expression Builder supports neither.

  • Why put the scraper's networks in an inline set rather than a list on a Pro plan?
    Custom lists of ASNs are Enterprise-only; Free, Pro and Business can only create IP lists. So on Pro the ASNs go inline, `ip.src.asnum in {64496 64500}`. If the scraper used a handful of addresses instead, an IP list such as `$scraper_ips` would work on any plan, and updating the list updates every rule that references it, across all zones in the account.
  • What does a client blocked by a custom rule receive, and can you change it?
    By default it gets the WAF block response, an HTML page with status 403. On Pro and above you can give the rule a custom response: a status code between 400 and 499 and an HTML, plain-text, JSON or XML body of up to 2 KB. That helps an API return machine-readable errors. On paid plans the zone-wide WAF block page can also be customised under Error Pages.

  • Custom rules offer an Allow action for trusted traffic, just like the old firewall rules.
  • A rule matching contains "search" targets exactly one endpoint.
  • Using ip.src.asnum in a custom rule requires an Enterprise plan.
  • Operators such as EQ and AND can be typed in any letter case.
  • Blocking the scraper's networks alone is precise enough, whatever else those networks carry.