diff --git a/src/content/docs/ruleset-engine/rules-language/functions.mdx b/src/content/docs/ruleset-engine/rules-language/functions.mdx index 3ab88e3e3735e69..5ad75b57b8499d9 100644 --- a/src/content/docs/ruleset-engine/rules-language/functions.mdx +++ b/src/content/docs/ruleset-engine/rules-language/functions.mdx @@ -73,7 +73,7 @@ Examples: - If `ip.src` is `113.10.0.2`, `cidr(ip.src, 24, 24)` will return `113.10.0.0`. - If `ip.src` is `2001:0000:130F:0000:0000:09C0:876A:130B`, `cidr(ip.src, 24, 24)` will return `2001:0000:0000:0000:0000:0000:0000:0000`. -:::caution +:::note You can only use the `cidr()` function in [custom rules](/waf/custom-rules/) and [rate limiting rules](/waf/rate-limiting-rules/). ::: @@ -95,7 +95,7 @@ Examples: - If `ip.src` is `2001:0000:130F:0000:0000:09C0:876A:130B`, `cidr6(ip.src, 24)` will return `2001:0000:0000:0000:0000:0000:0000:0000`. - If `ip.src` is `113.10.0.2`, `cidr6(ip.src, 24)` will return `113.10.0.2` (unchanged). -:::caution +:::note You can only use the `cidr6()` function in [custom rules](/waf/custom-rules/) and [rate limiting rules](/waf/rate-limiting-rules/). ::: @@ -104,7 +104,7 @@ You can only use the `cidr6()` function in [custom rules](/waf/custom-rules/) an {/* prettier-ignore */} concat(): -Takes a comma-separated list of values. Concatenates the argument values into a single String or array. +Takes a comma-separated list of values. Concatenates the argument values into a single String or array. The return type depends on the type of input arguments. For example, if you concatenate arrays, the function will return an array. @@ -121,7 +121,7 @@ Decodes a Base64-encoded String specified in `source`. For example, with the following HTTP request header: `client_id: MTIzYWJj`, `(any(decode_base64(http.request.headers["client_id"][*])[*] eq "123abc"))` would return `true`. -:::caution +:::note You can only use the `decode_base64()` function in [header transform rules](/rules/transform/), [custom rules](/waf/custom-rules/), and [rate limiting rules](/waf/rate-limiting-rules/). ::: @@ -249,7 +249,7 @@ Examples: Create capture groups by putting part of the regular expression in parentheses. Then, reference a capture group using `${}` in the replacement string, where `` is the number of the capture group. -:::caution +:::note You can only use the `regex_replace()` function in rewrite expressions of [Transform Rules](/rules/transform/) and target URL expressions of [dynamic URL redirects](/rules/url-forwarding/single-redirects/). ::: @@ -262,6 +262,43 @@ Returns a new byte array with all the occurrences of the given bytes removed. For example, if `http.host` is `"www.cloudflare.com"`, then `remove_bytes(http.host, "\x2e\x77")` will return `"cloudflarecom"`. +### `remove_query_args` + +{/* prettier-ignore */} +remove_query_args(field , query_param1 , query_param2 , ...): + +Removes one or more query string parameters from a URI query string. Returns a string without the specified parameters. + +The `field` must be one of the following: + +- `http.request.uri.query` +- `raw.http.request.uri.query` + +The `field` cannot be a literal value such as `"search=foo&order=asc"`. + +The `remove_query_args()` function will remove all specified parameters (as `query_param1`, `query_param2`, etc.) , including repeated occurrences of the same parameter. + +The ordering of unaffected query parameters will be preserved. + +Examples: + +```txt +// If http.request.uri.query is "order=asc&country=GB": + +remove_query_args(http.request.uri.query, "country") will return "order=asc" +remove_query_args(http.request.uri.query, "order") will return "country=GB" +remove_query_args(http.request.uri.query, "search") will return "order=asc&country=GB" (unchanged) + +// If http.request.uri.query is "category=Foo&order=desc&category=Bar": + +remove_query_args(http.request.uri.query, "order") will return "category=Foo&category=Bar" +remove_query_args(http.request.uri.query, "category") will return "order=desc" +``` + +:::note +You can only use the `remove_query_args()` function in [rewrite expressions of Transform Rules](/rules/transform/). +::: + ### `starts_with` {/* prettier-ignore */} @@ -308,7 +345,7 @@ to_string(cf.bot_management.score) will return "5" to_string(ssl) will return "true" ``` -:::caution +:::note You can only use the `to_string()` function in rewrite expressions of [Transform Rules](/rules/transform/) and target URL expressions of [dynamic URL redirects](/rules/url-forwarding/single-redirects/). ::: @@ -363,7 +400,7 @@ Generates a random UUIDv4 (Universally Unique Identifier, version 4) based on th For example, `uuidv4(cf.random_seed)` will return a UUIDv4 similar to `49887398-6bcf-485f-8899-f15dbef4d1d5`. -:::caution +:::note You can only use the `uuidv4()` function in [rewrite expressions of Transform Rules](/rules/transform/). ::: @@ -408,7 +445,7 @@ Examples: For more examples of wildcard matching, refer to [Wildcard matching](/ruleset-engine/rules-language/operators/#wildcard-matching). -:::caution +:::note Currently, you can only use the `wildcard_replace()` function in rewrite expressions of [URL rewrites](/rules/transform/url-rewrite/) and target URL expressions of [dynamic URL redirects](/rules/url-forwarding/single-redirects/). ::: @@ -453,27 +490,21 @@ is_timed_hmac_valid_v0( The `is_timed_hmac_valid_v0()` function has these parameter definitions: - `Key` - - Specifies the secret cryptographic key for validating the HMAC. - `MessageMAC` - - Contains a concatenation of these HMAC elements: `message`, `separator`, `timestamp`, `mac`. For a definition and an example, refer to [MessageMAC](#messagemac). - `ttl` - - Defines the time-to-live for the HMAC token, expressed in seconds. Determines how long the token is valid, relative to the time it was issued. - `currentTimeStamp` - - Represents the UNIX timestamp when Cloudflare received the request, expressed in seconds. Pass the `http.request.timestamp.sec` field as an approximate value to this argument. - `lengthOfSeparator` - - Specifies the length of the `separator` between the `timestamp` and the `message` in the `MessageMAC`. Expressed in bytes, with a default value of `0`. - `flags` - - When you set this optional argument to `'s'`, the function expects the value of the Base64-encoded `mac` in the `MessageMAC` argument to use the URL-safe character set with no padding. - When you do **not** set the value of `flags` to `'s'`, you must URL encode the Base64 value for `mac` in the `MessageMAC` argument. @@ -512,7 +543,7 @@ For details on generating a MessageMAC, refer to [HMAC token generation](/waf/cu ## HMAC validation examples -:::caution[Important] +:::note When you do not use the optional `flags` argument for `is_timed_hmac_valid_v0()`, you must URL-encode the Base64 value for `mac` in the `MessageMAC` argument.