How do I match a user agent in a Cloudflare custom rule?

Definition: A user-agent match in a Cloudflare custom rule compares the http.user_agent field, which contains the HTTP User-Agent request header, with a specified string. The rule combines that matching expression with an action such as Block.

Key facts

• As of 17 October 2026, Cloudflare's custom rules documentation describes separate expression and action parameters, with rules evaluated in order.
• The field reference defines http.user_agent as a string containing the HTTP User-Agent request header.
• Cloudflare's operator reference documents case-sensitive string comparisons and the case-insensitive wildcard operator.
• Cloudflare's IP validation documentation describes verification using an owner's public IP list or domain-based reverse DNS, alongside a user-agent match pattern.

Where does the expression go?

Cloudflare's dashboard instructions place rule creation under Security rules > Create rule > Custom rules. The rule name identifies the configuration. Under When incoming requests match, the builder compares a selected field with a value using an operator. Then take action defines the response to matching requests.

The Expression Editor documentation identifies Edit expression, beside Expression Preview, as the control for entering a text expression. The editor supports functions such as lower(). Cloudflare validates expressions before saving them. Save as Draft retains a rule without deploying it; Deploy saves and activates it.

Which expression matches the intended text?

The following illustrative expressions apply Cloudflare's documented operators to the user-agent field. Each block is an alternative matching condition.

To match a header containing the case-sensitive substring Googlebot:

http.user_agent contains "Googlebot"

This also matches longer header strings containing that text. To require the entire header value to equal Googlebot:

http.user_agent eq "Googlebot"

For a case-insensitive substring comparison, lower() converts the field value to lowercase before comparison with a lowercase literal:

lower(http.user_agent) contains "googlebot"

The same operator documentation reserves regular expression matching for matches, available on Business and Enterprise plans. Asterisks have wildcard meaning with wildcard and strict wildcard; contains performs a substring comparison.

How does matching differ from verifying a crawler?

A header match alone does not authenticate the sender. Google's request verification documentation addresses requests claiming to come from Google and specifies checks against published IP ranges or reverse DNS followed by forward DNS confirmation.

Within Cloudflare, the Boolean field cf.client.bot indicates whether a request originates from a known good bot or crawler. An illustrative condition combining that classification with the header text is:

cf.client.bot and http.user_agent contains "Googlebot"

Here, cf.client.bot supplies Cloudflare's classification and the header comparison narrows the matching text. Cloudflare's IP validation methods use owner-provided address lists or domain-based reverse DNS to validate bot addresses. A header-only condition is therefore unsuitable as the sole identity check for a security exception.

How can the result be checked?

Cloudflare's Security Events documentation describes events for requests that security products act on or flag. The User agent column helps inspect matching traffic; expanding an event exposes its details. Sampled logs contain a subset of events, and narrowing the time range can reduce sampling.

Rule order also matters. The custom rules documentation states that an earlier Block action stops later rules from running for that request. Reviewing the action and applied security feature helps distinguish the intended rule from another control affecting the request.

Related terms

• User-agent spoofing
• How do I apply a Cloudflare WAF rule to one URL path?
• How do I verify an OpenAI crawler request?

FAQ

Why does capitalization change the result?

Cloudflare's operator documentation makes contains and eq case-sensitive. You can use lower(http.user_agent) with a lowercase comparison value to accommodate capitalization differences.

Can I return to the visual builder after adding lower()?

Cloudflare's editor documentation says the builder excludes function calls. You may need to continue editing the expression in the text editor.

Sources

1. Cloudflare, "Custom rules", 16 October 2026
2. Cloudflare, "http.user_agent", undated
3. Cloudflare, "Operators and grouping symbols", 1 October 2026
4. Cloudflare, "IP validation", 15 April 2026
5. Cloudflare, "Create a custom rule in the dashboard", 8 October 2026
6. Cloudflare, "Edit expressions in the dashboard", 16 April 2026
7. Google, "Verify requests from Google crawlers and fetchers", 20 March 2026
8. Cloudflare, "cf.client.bot", undated
9. Cloudflare, "Security Events", 2 October 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer