diff --git a/src/content/docs/ruleset-engine/rules-language/fields/dynamic-fields.mdx b/src/content/docs/ruleset-engine/rules-language/fields/dynamic-fields.mdx index 5525109790614d..988a61f357ede5 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/dynamic-fields.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/dynamic-fields.mdx @@ -94,7 +94,7 @@ Indicates whether the visitor has previously passed a JS Detection. For more det List of IDs that correlate to the Bot Management heuristic detections made on a request (you can have multiple heuristic detections on the same request). Use this field to explicitly match a specific heuristic or to exclude a heuristic in a rule. -Example: +Example usage: ```txt any(cf.bot_management.detection_ids[*] eq 33554817) @@ -148,7 +148,7 @@ Represents a Cloudflare threat score from 0–100, where 0 indicates low risk. V The cipher for the connection to Cloudflare. -Example: +Example value: ```txt "AES128-SHA256" @@ -178,7 +178,7 @@ Returns `true` when a request presents a certificate (valid or not). The Distinguished Name (DN) of the Certificate Authority (CA) that issued the certificate included in the request. -Example: +Example value: ```txt "CN=Access Testing CA,OU=TX,O=Access Testing,L=Austin,ST=Texas,C=US" @@ -190,7 +190,7 @@ Example: The Distinguished Name (DN) of the owner (or requester) of the certificate included in the request. -Example: +Example value: ```txt "CN=James Royal,OU=Access Admins,O=Access,L=Austin,ST=Texas,C=US" @@ -202,9 +202,9 @@ Example: The Distinguished Name (DN) of the Certificate Authority (CA) that issued the certificate in the request in [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) format. -Example: +Example value: -``` +```txt "CN=Access Testing CA,OU=TX,O=Access Testing,L=Austin,ST=Texas,C=US" ``` @@ -214,9 +214,9 @@ Example: The Distinguished Name (DN) of the owner (or requester) of the certificate in the request in [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) format. -Example: +Example value: -``` +```txt "CN=James Royal,OU=Access Admins,O=Access,L=Austin,ST=Texas,C=US" ``` @@ -226,9 +226,9 @@ Example: The Distinguished Name (DN) of the Certificate Authority (CA) that issued the certificate in the request in a legacy format. -Example: +Example value: -``` +```txt "/C=US/ST=Texas/L=Austin/O=Access Testing/OU=TX/CN=Access Testing CA" ``` @@ -238,9 +238,9 @@ Example: The Distinguished Name (DN) of the owner (or requester) of the certificate in the request in a legacy format. -Example: +Example value: -``` +```txt "/C=US/ST=Texas/L=Austin/O=Access/OU=Access Admins/CN=James Royal" ``` @@ -250,9 +250,9 @@ Example: Serial number of the certificate in the request. -Example: +Example value: -``` +```txt "527E0F20A20EA2A4146C78390F34CE7AF0878CA4" ``` @@ -262,9 +262,9 @@ Example: Serial number of the direct issuer of the certificate in the request. -Example: +Example value: -``` +```txt "2688201DBA77402EA87118876F2E1B24CF8B0395" ``` @@ -274,9 +274,9 @@ Example: The SHA-256 fingerprint of the certificate in the request. -Example: +Example value: -``` +```txt "af363dc85bc942a892d3cee9796190fdb36d89cd588a4f1cb17c74a943439714" ``` @@ -286,9 +286,9 @@ Example: The SHA-1 fingerprint of the certificate in the request. -Example: +Example value: -``` +```txt "933ad5282c560ae3f482a43ecd73bc9de878a190" ``` @@ -298,9 +298,9 @@ Example: The certificate in the request is not valid before this date. -Example: +Example value: -``` +```txt "Mar 21 13:35:00 2022 GMT" ``` @@ -310,9 +310,9 @@ Example: The certificate in the request is not valid after this date. -Example: +Example value: -``` +```txt "Mar 21 13:35:00 2023 GMT" ``` @@ -322,9 +322,9 @@ Example: The Subject Key Identifier (SKI) of the certificate in the request. -Example: +Example value: -``` +```txt "27846FAE6EAC4A8DAD9101B519CF1EB460242831" ``` @@ -334,9 +334,9 @@ Example: The Subject Key Identifier (SKI) of the direct issuer of the certificate in the request. -Example: +Example value: -``` +```txt "8204924CF49D471E855862706D889F58F6B784D3" ``` @@ -346,9 +346,9 @@ Example: The SHA-1 fingerprint of TLS client extensions, encoded in Base64. -Example: +Example value: -``` +```txt "OWFiM2I5ZDc0YWI0YWYzZmFkMGU0ZjhlYjhiYmVkMjgxNTU5YTU2Mg==" ``` @@ -358,9 +358,9 @@ Example: The length of the client hello message sent in a [TLS handshake](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake). Specifically, the length of the bytestring of the client hello. -Example: +Example value: -``` +```txt 508 ``` @@ -370,9 +370,9 @@ Example: The value of the 32-byte random value provided by the client in a [TLS handshake](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake), encoded in Base64. Refer to [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446#section-4.1.2) for more details. -Example: +Example value: -``` +```txt "YWJjZA==" ``` @@ -382,9 +382,9 @@ Example: The TLS version of the connection to Cloudflare. -Example: +Example value: -``` +```txt "TLSv1.2" ``` diff --git a/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx b/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx index e91e7e197fcaf3..a1bc8040360b2d 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/http-request-body.mdx @@ -72,14 +72,13 @@ The return value may be truncated if [`http.request.body.truncated`](#httpreques - **Whitespace:** preserved - **Non-ASCII:** preserved -Example: +Example value: -```txt -any(http.request.body.form["username"][*] == "admin") -``` +`{"username": ["admin"]}` -Example value: -`{username": ["admin"]}` +Example usage: + +`any(http.request.body.form["username"][*] == "admin")` ## `http.request.body.form.names` @@ -97,16 +96,14 @@ The return value may be truncated if [`http.request.body.truncated`](#httpreques - **Whitespace:** preserved - **Non-ASCII:** preserved -Example: - -```txt -any(http.request.body.form.names[*] == "username") -``` - Example value: `["username"]` +Example usage: + +`any(http.request.body.form.names[*] == "username")` + ## `http.request.body.form.values` `http.request.body.form.values` @@ -123,16 +120,14 @@ The return value may be truncated if [`http.request.body.truncated`](#httpreques - **Whitespace:** preserved - **Non-ASCII:** preserved -Example: - -```txt -any(http.request.body.form.values[*] == "admin") -``` - Example value: `["admin"]` +Example usage: + +`any(http.request.body.form.values[*] == "admin")` + ## `http.request.body.mime` `http.request.body.mime` @@ -141,9 +136,13 @@ The MIME type of the request detected from the request body. Supports the most common MIME types of the following general categories: video, audio, image, application, text. -Example: +Example value: + +`"image/jpeg"` + +Example usage: -`image/jpeg` +`http.request.body.mime in {"image/bmp" "image/gif" "image/jpeg" "image/png" "image/tiff"}` This field is available on all Cloudflare plans. @@ -155,7 +154,11 @@ A Map (or associative array) representation of multipart names to multipart valu Example value: -`{"username": ["alice_doe"], "picture": []}` +`{"username": ["alice_doe"], "role": ["editor"], "picture": []}` + +Example usage: + +`any(http.request.body.multipart["role"][*] == "admin")` ## `http.request.body.multipart.names` @@ -167,7 +170,7 @@ Example value: `[["username"], ["picture"]]` -Example: +Example usage: `any(http.request.body.multipart.names[*][0] == "picture")` @@ -181,6 +184,10 @@ Example value: `["alice_doe", ]` +Example usage: + +`any(http.request.body.multipart.values[*] == "alice_doe")` + ## `http.request.body.multipart.content_types` `http.request.body.multipart.content_types` @@ -191,7 +198,7 @@ Example value: `[["text/plain"], ["image/jpeg"]]` -Example: +Example usage: `any(http.request.body.multipart.content_types[*][0] == "application/octet-stream")` @@ -203,7 +210,11 @@ List of `Content-Disposition` headers for each part in the multipart body. Example value: -`[["form-data; name=\"username\"], ["form-data;name=\"picture\"]]` +`[["form-data; name=\"username\""], ["form-data; name=\"picture\""]]` + +Example usage: + +`any(http.request.body.multipart.content_dispositions[*][0] in {"form-data; name=\"username\"" "form-data; name=\"picture\""})` ## `http.request.body.multipart.content_transfer_encodings` @@ -213,7 +224,11 @@ List of `Content-Transfer-Encoding` headers for each part in the multipart body. Example value: -`[["quoted-printable"], ["quoted-printable"]]` +`[["quoted-printable"], ["base64"]]` + +Example usage: + +`any(http.request.body.multipart.content_transfer_encodings[*][0] == "binary")` ## `http.request.body.multipart.filenames` @@ -224,3 +239,7 @@ List of filenames for each part in the multipart body. Example value: `[["file1.txt"], ["photo.jpg"]]` + +Example usage: + +`any(http.request.body.multipart.filenames[*][0] in {"token.txt" "password.txt"})` diff --git a/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx b/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx index c05cfd468335a4..ea15cc2c400fff 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/http-request-header.mdx @@ -30,7 +30,7 @@ The request header values are not pre-processed and retain the original case use - **Whitespace:** preserved - **Non-ASCII:** preserved -Example: +Example usage: ```txt any(http.request.headers["content-type"][*] == "application/json") @@ -62,9 +62,9 @@ Duplicate headers are listed multiple times. - **Whitespace:** preserved - **Non-ASCII:** preserved -Example: +Example usage: -``` +```txt any(http.request.headers.names[*] == "content-type") ``` @@ -86,30 +86,30 @@ Duplicate headers are listed multiple times. - **Whitespace:** preserved - **Non-ASCII:** preserved -Example 1: +Example value 1: -``` -any(http.request.headers.values[*] == "application/json") +```txt +["application/json"] ``` -Example value 1: +Example usage 1: -``` -["application/json"] +```txt +any(http.request.headers.values[*] == "application/json") ``` Additionally used to match requests according to the specified operator and the length/size entered for the header value. -Example 2: +Example value 2: -``` -any(len(http.request.headers.values[*])[*] gt 10) +```txt +["This header value is longer than 10 bytes"] ``` -Example value 2: +Example usage 2: -``` -["This header value is longer than 10 bytes"] +```txt +any(len(http.request.headers.values[*])[*] gt 10) ``` ## `http.request.headers.truncated` @@ -133,13 +133,19 @@ If the HTTP header includes the language tag `*` it will not be stored in the ar Example 1: Request with header `Accept-Language: fr-CH, fr;q=0.8, en;q=0.9, de;q=0.7, *;q=0.5`. In this case: -`http.request.accepted_languages[0] == "fr-CH"` -`http.request.accepted_languages == ["fr-CH", "en", "fr", "de"]` + +```txt +http.request.accepted_languages[0] ==> "fr-CH" +http.request.accepted_languages ==> ["fr-CH", "en", "fr", "de"] +``` Example 2: Request without an `Accept-Language` HTTP header and a URI of `https://www.example.com/my-path`. In this case: -`concat("/", http.request.accepted_languages[0], http.request.uri.path) == "//my-path"`. + +```txt +concat("/", http.request.accepted_languages[0], http.request.uri.path) ==> "//my-path" +``` :::note This field is only available in [Transform Rules](/rules/transform/). diff --git a/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx b/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx index c8b89d02ab3ed8..e8ff32e90f6b83 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/http-request-response.mdx @@ -33,16 +33,16 @@ When there are repeating headers, the array includes them in the order they appe - Whitespace: preserved - Non-ASCII: preserved -Example: +Example value: ```txt -any(http.response.headers["server"][*] == "nginx") +{"server": ["nginx"]} ``` -Example value: +Example usage: ```txt -{"server": ["nginx"]} +any(http.response.headers["server"][*] == "nginx") ``` ## `http.response.headers.names` @@ -59,14 +59,16 @@ Duplicate headers are listed multiple times. - Whitespace: preserved - Non-ASCII: preserved -Example: +Example value: + +`["content-type"]` -``` +Example usage: + +```txt any(http.response.headers.names[*] == "content-type") ``` -Example value: `["content-type"]` - ## `http.response.headers.values` `http.response.headers.values` @@ -83,25 +85,28 @@ Duplicate headers are listed multiple times. - Whitespace: preserved - Non-ASCII: preserved -Example 1: +Example value 1: -``` +`["application/json"]` + +Example usage 1: + +```txt any(http.response.headers.values[*] == "application/json") ``` -Example value 1: `["application/json"]` - Additionally used to match responses according to the specified operator and the length/size entered for the header value. -Example 2: +Example value 2: -``` +`["This header value is longer than 10 bytes"]` + +Example usage 2: + +```txt any(len(http.response.headers.values[*])[*] gt 10) ``` -Example value 2: -`["This header value is longer than 10 bytes"]` - ## `http.response.content_type.media_type` `http.response.content_type.media_type` @@ -128,6 +133,7 @@ The lowercased content type (including subtype and suffix) without any parameter Contains the specific code for 1XXX Cloudflare errors. Use this field to differentiate between 1XXX errors associated with the same HTTP status code. The default value is `0`. For a list of 1XXX errors, refer to [Troubleshooting Cloudflare 1XXX errors](/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-1xxx-errors/). Example value: + `1020` :::note @@ -142,16 +148,16 @@ A string with the type of error in the response being returned. The default valu The available values are the following: -- `managed_challenge` -- `iuam` -- `legacy_challenge` -- `ip_ban` -- `waf` -- `5xx` -- `1xxx` -- `always_online` -- `country_challenge` -- `ratelimit` +- `"managed_challenge"` +- `"iuam"` +- `"legacy_challenge"` +- `"ip_ban"` +- `"waf"` +- `"5xx"` +- `"1xxx"` +- `"always_online"` +- `"country_challenge"` +- `"ratelimit"` You can use this field to customize the response for a specific type of error (for example, all 1XXX errors or all WAF block actions). diff --git a/src/content/docs/ruleset-engine/rules-language/fields/magic-firewall.mdx b/src/content/docs/ruleset-engine/rules-language/fields/magic-firewall.mdx index 8d521787373d8b..3e9ee7c10bd9fc 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/magic-firewall.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/magic-firewall.mdx @@ -20,7 +20,7 @@ Some Magic Firewall fields are available only to customers who purchased Magic F The data center that is handling this traffic. -Example value: `sfo06` +Example value: `"sfo06"` --- @@ -30,7 +30,7 @@ Example value: `sfo06` Region of the data center that is handling this traffic. -Example value: `WNAM` +Example value: `"WNAM"` --- @@ -86,7 +86,7 @@ Example value: `192.0.2.2` Represents the 2-letter country code associated with the server IP address in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search/code/) format. -Example value: `GB` +Example value: `"GB"` For more information on the ISO 3166-1 Alpha 2 format, refer to [ISO 3166-1 Alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) on Wikipedia. @@ -98,7 +98,7 @@ For more information on the ISO 3166-1 Alpha 2 format, refer to [ISO 3166-1 Alph Represents the 2-letter country code associated with the client IP address in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search/code/) format. -Example value: `GB` +Example value: `"GB"` For more information on the ISO 3166-1 Alpha 2 format, refer to [ISO 3166-1 Alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) on Wikipedia. @@ -142,7 +142,7 @@ Example value: `25` The transport layer for the packet, if it can be determined. -Example values: `icmp`, `tcp` +Example values: `"icmp"`, `"tcp"` --- @@ -160,7 +160,7 @@ The source address of the IP Packet. Represents the 2-letter country code associated with the client IP address in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search/code/) format. -Example value: `GB` +Example value: `"GB"` For more information on the ISO 3166-1 Alpha 2 format, refer to [ISO 3166-1 Alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) on Wikipedia. diff --git a/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx b/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx index e5b4a146f27e74..ede51025be34f7 100644 --- a/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx +++ b/src/content/docs/ruleset-engine/rules-language/fields/standard-fields.mdx @@ -39,7 +39,7 @@ The entire cookie as a string. Example value: ```txt -session=8521F670545D7865F79C3D7BEDC29CCE;-background=light +"session=8521F670545D7865F79C3D7BEDC29CCE;-background=light" ``` ## `http.host` @@ -51,7 +51,7 @@ The hostname used in the full request URI. Example value: ```txt -www.example.org +"www.example.org" ``` ## `http.referer` @@ -63,7 +63,7 @@ The HTTP `Referer` request header, which contains the address of the web page th Example value: ```txt -Referer: htt­ps://developer.example.org/en-US/docs/Web/JavaScript +"https://developer.example.org/en-US/docs/Web/JavaScript" ``` ## `http.request.full_uri` @@ -75,7 +75,7 @@ The full URI as received by the web server (does not include `#fragment`, which Example value: ```txt -htt­ps://www.example.org/articles/index?section=539061&expand=comments +"https://www.example.org/articles/index?section=539061&expand=comments" ``` ## `http.request.method` @@ -87,7 +87,7 @@ The HTTP method, returned as a string of uppercase characters. Example value: ```txt -GET +"GET" ``` ## `http.request.cookies` @@ -98,16 +98,16 @@ The `Cookie` HTTP header associated with a request represented as a Map (associa **Decoding:** The cookie names are URL decoded. If two cookies have the same name after decoding, their value arrays are merged. -Example: +Example value: ```txt -any(http.request.cookies["app"][*] == "test") +{ "app": ["test"] } ``` -Example value: +Example usage: -```json -{ "app": ["test"] } +```txt +any(http.request.cookies["app"][*] == "test") ``` ## `http.request.timestamp.sec` @@ -149,7 +149,7 @@ The URI path and query string of the request. Example value: ```txt -/articles/index?section=539061&expand=comments +"/articles/index?section=539061&expand=comments" ``` ## `http.request.uri.path` @@ -161,7 +161,7 @@ The URI path of the request. Example value: ```txt -/articles/index +"/articles/index" ``` ## `http.request.uri.path.extension` @@ -174,7 +174,7 @@ If the first character of the last path segment is a dot and the segment does no Example values: -- If the URI path is `/articles/index.html`, the field value will be `html`. +- If the URI path is `/articles/index.html`, the field value will be `"html"`. - If the URI path is `/articles/index.`, the field value will be an empty string (`""`).
@@ -200,7 +200,7 @@ The entire query string, without the `?` delimiter. Example value: ```txt -section=539061&expand=comments +"section=539061&expand=comments" ``` ## `http.user_agent` @@ -212,7 +212,7 @@ The HTTP `User-Agent` request header, which contains a characteristic string to Example value: ```txt -Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36 +"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36" ``` ## `http.request.version` @@ -223,19 +223,19 @@ The version of the HTTP protocol used. Use this field when different checks are Example values: -- `HTTP/1.1` -- `HTTP/3` +- `"HTTP/1.1"` +- `"HTTP/3"` ## `http.x_forwarded_for` `http.x_forwarded_for` -The full `X-Forwarded-For` HTTP header. +The full value of the `X-Forwarded-For` HTTP header. Example value: ```txt -203.0.113.195, 70.41.3.18 +"203.0.113.195, 70.41.3.18" ``` ## `ip.src` @@ -259,7 +259,7 @@ The latitude associated with the client IP address. Example value: ```txt -37.78044 +"37.78044" ``` ## `ip.src.lon` @@ -271,7 +271,7 @@ The longitude associated with the client IP address. Example value: ```txt --122.39055 +"-122.39055" ``` ## `ip.src.city` @@ -283,7 +283,7 @@ The city associated with the client IP address. Example value: ```txt -San Francisco +"San Francisco" ``` ## `ip.src.postal_code` @@ -295,7 +295,7 @@ The postal code associated with the incoming request. Example value: ```txt -78701 +"78701" ``` ## `ip.src.metro_code` @@ -307,7 +307,7 @@ The metro code or Designated Market Area (DMA) code associated with the incoming Example value: ```txt -635 +"635" ``` ## `ip.src.region` @@ -319,7 +319,7 @@ The region name associated with the incoming request. Example value: ```txt -Texas +"Texas" ``` ## `ip.src.region_code` @@ -331,7 +331,7 @@ The region code associated with the incoming request. Example value: ```txt -TX +"TX" ``` ## `ip.src.timezone.name` @@ -343,7 +343,7 @@ The name of the timezone associated with the incoming request. This field is onl Example value: ```txt -America/Chicago +"America/Chicago" ``` ## `ip.src.asnum` @@ -360,14 +360,14 @@ This field has the same value as the `ip.geoip.asnum` field, which is deprecated The continent code associated with the client IP address: -- **AF**: Africa -- **AN**: Antarctica -- **AS**: Asia -- **EU**: Europe -- **NA**: North America -- **OC**: Oceania -- **SA**: South America -- **T1**: Tor network +- `"AF"`: Africa +- `"AN"`: Antarctica +- `"AS"`: Asia +- `"EU"`: Europe +- `"NA"`: North America +- `"OC"`: Oceania +- `"SA"`: South America +- `"T1"`: Tor network This field has the same value as the `ip.geoip.continent` field, which is deprecated. The `ip.geoip.continent` field is still available for new and existing rules, but you should use the `ip.src.continent` field instead. @@ -380,7 +380,7 @@ The 2-letter country code in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#se Example value: ```txt -GB +"GB" ``` For more information on the ISO 3166-1 Alpha 2 format, refer to [ISO 3166-1 Alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) on Wikipedia. @@ -396,7 +396,7 @@ The ISO 3166-2 code for the first-level region associated with the IP address. W Example value: ```txt -GB-ENG +"GB-ENG" ``` For more information on the ISO 3166-2 standard and the available regions, refer to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) on Wikipedia. @@ -412,7 +412,7 @@ The ISO 3166-2 code for the second-level region associated with the IP address. Example value: ```txt -GB-SWK +"GB-SWK" ``` For more information on the ISO 3166-2 standard and the available regions, refer to [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) on Wikipedia.