Skip to content

[Rules] Update operators.mdx #18557

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 4, 2024
Merged

[Rules] Update operators.mdx #18557

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
02abd31
[Rules] Update operators.mdx
ngayerie Dec 4, 2024
4d44d66
PCX review
pedrosousa Dec 4, 2024
0b0c982
Mention potential limitation
pedrosousa Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 42 additions & 9 deletions src/content/docs/ruleset-engine/rules-language/operators.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ The Rules language supports these comparison operators:
</td>
</tr>
<tr>
<td>Exactly<br />contains</td>
<td>Contains</td>
<td><code>contains</code></td>
<td></td>
<td>✅</td>
Expand All @@ -129,7 +129,29 @@ The Rules language supports these comparison operators:
</td>
</tr>
<tr>
<td>Matches<br />regex*</td>
<td>Wildcard<sup>1</sup><br/>(case-insensitive)</td>
<td><code>wildcard</code></td>
<td></td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>
<code>http.request.uri.path <strong>wildcard</strong> "/articles/*"</code>
</td>
</tr>
<tr>
<td>Strict wildcard<sup>1</sup><br/>(case-sensitive)</td>
<td><code>strict wildcard</code></td>
<td></td>
<td>✅</td>
<td>❌</td>
<td>❌</td>
<td>
<code>http.request.uri.path <strong>strict wildcard</strong> "/AdminTeam/*"</code>
</td>
</tr>
<tr>
<td>Matches<br />regex<sup>2</sup></td>
<td><code>matches</code></td>
<td><code>~</code></td>
<td>✅</td>
Expand All @@ -140,34 +162,45 @@ The Rules language supports these comparison operators:
</td>
</tr>
<tr>
<td>Value is in <br />a set of values</td>
<td>Is in set of values / list<sup>3</sup></td>
<td><code>in</code></td>
<td></td>
<td>✅</td>
<td>✅</td>
<td>✅</td>
<td>
<code>ip.src <strong>in</strong> {"{ 203.0.113.0 203.0.113.1 }"}</code>
<code>ip.src <strong>in</strong> {"{ 203.0.113.0 203.0.113.1 }"}</code><br/>
<code>ip.src.asnum <strong>in</strong> $&lt;LIST&gt;</code>
</td>
</tr>
</tbody>
</table>
</div>

\* _Access to the `matches` operator requires a Cloudflare Business or Enterprise plan._
{/* prettier-ignore */}
<sup>1</sup> For more information, refer to [Wildcard matching](#wildcard-matching).<br/>
<sup>2</sup> Access to the `matches` operator requires a Cloudflare Business or Enterprise plan. For more information, refer to [Regular expression matching](#regular-expression-matching).<br/>
<sup>3</sup> Currently, not all Cloudflare products support lists in their expressions. For more information on lists, refer to [Inline lists](/ruleset-engine/rules-language/values/#inline-lists) and [Lists](/waf/tools/lists/).

:::caution
Comparison operators entered using English notation (such as `eq`, `lt`, and `gt`) must be written in lowercase.
:::

### Additional operators in the Cloudflare dashboard

The Cloudflare dashboard shows the following functions as operators:
The Cloudflare dashboard may show the following additional operators, depending on the exact field and the type of rule:

- _starts with_ (corresponding to the [`starts_with()`](/ruleset-engine/rules-language/functions/#starts_with) function): Returns `true` when a string starts with a given substring, and `false` otherwise.

- _ends with_ (corresponding to the [`ends_with()`](/ruleset-engine/rules-language/functions/#ends_with) function): Returns `true` when a string ends with a given substring, and `false` otherwise.

However, when writing your own custom expressions, you must use these functions in function calls, not as operators. For example:
- _is in list_ (corresponding to `<FIELD> in $<LIST_NAME>`): Returns `true` when the field value is present in the specified [list](/waf/tools/lists/), and `false` otherwise. For more information, refer to [Use lists in expressions](/waf/tools/lists/use-in-expressions/).

- _is not in list_ (corresponding to `not <FIELD> in $<LIST_NAME>`): Returns `true` when the field value is not present in the specified [list](/waf/tools/lists/), and `false` otherwise. For more information, refer to [Use lists in expressions](/waf/tools/lists/use-in-expressions/).

:::note

When writing your own custom expressions, you must use the `starts_with()` and `ends_with()` functions in function calls, not as operators. For example:

```txt
# Valid function call
Expand All @@ -177,6 +210,8 @@ ends_with(http.request.uri.path, ".html")
http.request.uri.path ends_with ".html"
```

:::

### Comparing string values

String comparison in rule expressions is case-sensitive. To account for possible variations of string capitalization in an expression, you can use the [`lower()`](/ruleset-engine/rules-language/functions/#lower) function and compare the result with a lowercased string, like in the following example:
Expand All @@ -185,9 +220,7 @@ String comparison in rule expressions is case-sensitive. To account for possible
lower(http.request.uri.path) contains "/wp-login.php"
```

:::caution
Wildcard matching is only supported with the `wildcard` and `strict wildcard` operators, and regular expression matching is only supported with the `matches` operator.
:::

### Wildcard matching

Expand Down
Loading