You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/firewall/api/cf-filters/endpoints.mdx
+9-21Lines changed: 9 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,11 +6,8 @@ sidebar:
6
6
head:
7
7
- tag: title
8
8
content: Endpoints - Filters
9
-
10
9
---
11
10
12
-
13
-
14
11
To invoke a Cloudflare Filters API operation, append the endpoint to the Cloudflare API base URL:
15
12
16
13
```txt
@@ -23,19 +20,16 @@ For help with endpoints and pagination, refer to [Getting Started: Endpoints](/f
23
20
24
21
:::note
25
22
26
-
27
23
The Filters API endpoints require a value for `<ZONE_ID>`.
28
24
29
25
To retrieve a list of zones associated with your account, use the [List Zones](/api/resources/zones/methods/list/) operation and note the Zone ID associated with the domain for which you want to manage filters.
30
26
31
-
32
27
:::
33
28
34
29
The Cloudflare Filters API supports the operations outlined below. Visit the pages in this section for examples.
35
30
36
-
37
-
38
-
<tablestyle="table-layout:fixed; width:100%">
31
+
{/* prettier-ignore */}
32
+
<table>
39
33
<thead>
40
34
<tr>
41
35
<thstyle="width: 20%">Operation</th>
@@ -49,7 +43,7 @@ The Cloudflare Filters API supports the operations outlined below. Visit the pag
Copy file name to clipboardExpand all lines: src/content/docs/firewall/api/cf-filters/json-object.mdx
+62-6Lines changed: 62 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,22 +6,78 @@ sidebar:
6
6
head:
7
7
- tag: title
8
8
content: Filter JSON object
9
-
10
9
---
11
10
11
+
import { Type } from"~/components";
12
+
12
13
## Filter object structure and properties
13
14
14
15
A JSON response for the [Filters API](/api/resources/filters/methods/list/) has this structure:
15
16
16
17
```json
17
18
{
18
-
"id": "6f58318e7fa2477a23112e8118c66f61",
19
-
"expression": "http.request.uri.path ~ \"^.*/wp-login.php$\" or http.request.uri.path ~ \"^.*/xmlrpc.php$\"",
20
-
"paused": true,
21
-
"description": "WordPress login paths",
22
-
"ref": ""
19
+
"id": "6f58318e7fa2477a23112e8118c66f61",
20
+
"expression": "http.request.uri.path ~ \"^.*/wp-login.php$\" or http.request.uri.path ~ \"^.*/xmlrpc.php$\"",
21
+
"paused": true,
22
+
"description": "WordPress login paths",
23
+
"ref": ""
23
24
}
24
25
```
25
26
26
27
The following table summarizes the object properties:
27
28
29
+
{/* prettier-ignore */}
30
+
<table>
31
+
<thead>
32
+
<tr>
33
+
<th>Property</th>
34
+
<th>Description</th>
35
+
<th>Constraints</th>
36
+
</tr>
37
+
</thead>
38
+
<tbody>
39
+
<tr>
40
+
<td>
41
+
<code>id</code><br />
42
+
<Typetext="String" />
43
+
</td>
44
+
<td>A UUIDv4 identifier generated by Cloudflare.</td>
45
+
<td>
46
+
<p>Unique, read only</p>
47
+
<p>Length: 32 characters</p>
48
+
</td>
49
+
</tr>
50
+
<tr>
51
+
<td>
52
+
<code>expression</code><br />
53
+
<Typetext="String" />
54
+
</td>
55
+
<td>A Rules language expression used to evaluate requests. For more information, refer to <ahref="/ruleset-engine/rules-language/expressions/">Expressions</a>.</td>
56
+
<td></td>
57
+
</tr>
58
+
<tr>
59
+
<td>
60
+
<code>paused</code><br />
61
+
<Typetext="Boolean" />
62
+
</td>
63
+
<td>Returns <code>true</code> when the filter is not active. Use <code>ref</code> to enable/disable the filter.</td>
A JSON response for the [Firewall Rules API](/api/resources/firewall/subresources/rules/methods/list/) has this structure:
15
16
16
17
```json
17
18
{
18
-
"id": "772bf1026a72c400ea576db1ffa16407",
19
-
"filter": {
20
-
"id": "6f58318e7fa2477a23112e8118c66f61",
21
-
"expression": "http.request.uri.path ~ \"^.*/wp-login.php$\" or http.request.uri.path ~ \"^.*/xmlrpc.php$\"",
22
-
"paused": false,
23
-
"description": "WordPress login paths",
24
-
"ref": ""
25
-
},
26
-
"action": "challenge",
27
-
"priority": 1000,
28
-
"paused": false,
29
-
"description": "Protect blog login page",
30
-
"ref": ""
19
+
"id": "772bf1026a72c400ea576db1ffa16407",
20
+
"filter": {
21
+
"id": "6f58318e7fa2477a23112e8118c66f61",
22
+
"expression": "http.request.uri.path ~ \"^.*/wp-login.php$\" or http.request.uri.path ~ \"^.*/xmlrpc.php$\"",
23
+
"paused": false,
24
+
"description": "WordPress login paths",
25
+
"ref": ""
26
+
},
27
+
"action": "challenge",
28
+
"priority": 1000,
29
+
"paused": false,
30
+
"description": "Protect blog login page",
31
+
"ref": ""
31
32
}
32
33
```
33
34
34
35
This table summarizes the object properties:
35
36
36
-
37
+
{/* prettier-ignore */}
38
+
<table>
39
+
<thead>
40
+
<tr>
41
+
<th>Name</th>
42
+
<th>Description</th>
43
+
<th>Constraints</th>
44
+
</tr>
45
+
</thead>
46
+
<tbody>
47
+
<tr>
48
+
<td>
49
+
<code>id</code><br />
50
+
<Typetext="String" />
51
+
</td>
52
+
<td>A UUIDv4 identifier generated by Cloudflare.</td>
53
+
<td>
54
+
<p>Unique, read only</p>
55
+
<p>Length: 32 characters</p>
56
+
</td>
57
+
</tr>
58
+
<tr>
59
+
<td>
60
+
<code>filter</code><br />
61
+
<Typetext="Object" />
62
+
</td>
63
+
<td>
64
+
A <ahref="/firewall/api/cf-filters/json-object/">Cloudflare Filter object</a> that contains an expression for evaluating this rule.
65
+
</td>
66
+
<td></td>
67
+
</tr>
68
+
<tr>
69
+
<td>
70
+
<code>action</code><br />
71
+
<Typetext="String" />
72
+
</td>
73
+
<td>
74
+
The action to take when a request satisfies the filter expression for this rule.
75
+
</td>
76
+
<td>
77
+
Refer to <ahref="/firewall/cf-firewall-rules/actions/">Firewall rules actions</a> for a list of supported values.
78
+
</td>
79
+
</tr>
80
+
<tr>
81
+
<td>
82
+
<code>priority</code><br />
83
+
<Typetext="Number" />
84
+
</td>
85
+
<td>
86
+
Determines the order of evaluation for the rule relative to others. Lower values indicate greater priority. Rules without a value are evaluated last. For guidance, refer to <ahref="#avoiding-priority-conflicts">Avoiding priority conflicts</a>.
87
+
</td>
88
+
<td>
89
+
<p>Read only</p>
90
+
<p>Maximum length: 32</p>
91
+
</td>
92
+
</tr>
93
+
<tr>
94
+
<td>
95
+
<code>paused</code><br />
96
+
<Typetext="Boolean" />
97
+
</td>
98
+
<td>
99
+
Returns <code>true</code> when the rule is not active. Use <code>ref</code> to enable/disable the rule.
100
+
</td>
101
+
<td>
102
+
Default: <code>false</code>
103
+
</td>
104
+
</tr>
105
+
<tr>
106
+
<td>
107
+
<code>description</code><br />
108
+
<Typetext="String" />
109
+
</td>
110
+
<td>An informative summary of the rule.</td>
111
+
<td>Maximum length: 500 characters</td>
112
+
</tr>
113
+
<tr>
114
+
<td>
115
+
<code>ref</code><br />
116
+
<Typetext="String" />
117
+
</td>
118
+
<td>A short string for tagging rules.</td>
119
+
<td>Maximum length: 50 characters</td>
120
+
</tr>
121
+
</tbody>
122
+
</table>
37
123
38
124
## Avoiding priority conflicts
39
125
40
126
Priority plays a key role in configuring firewall rules. With Cloudflare Filters, it is possible to construct conflicting rules such as:
41
127
42
-
* Allow requests from the office IP range, and
43
-
* Block requests with a specific user agent.
128
+
- Allow requests from the office IP range, and
129
+
- Block requests with a specific user agent.
44
130
45
131
Requests from the office IP range using the user agent to block would trigger both rules, but we cannot both allow and block the request. To solve this problem, firewall rules follows a strict ordering depending on action and priority.
46
132
47
-
Cloudflare prioritizes rules in descending order, such that priority 1 is first and rules with no priority are last. For rules of equal priority, Cloudflare orders them by action according to their [order of precedence](/firewall/cf-firewall-rules/actions/#supported-actions). In the example above, if no priority is set, the rule `allow request from the office IP range` would apply because the *allow* action has a higher precedence than *block*.
133
+
Cloudflare prioritizes rules in descending order, such that priority 1 is first and rules with no priority are last. For rules of equal priority, Cloudflare orders them by action according to their [order of precedence](/firewall/cf-firewall-rules/actions/#supported-actions). In the example above, if no priority is set, the rule `allow request from the office IP range` would apply because the _allow_ action has a higher precedence than _block_.
48
134
49
135
To reduce the risk of unintended behavior, it is best to explicitly specify the desired priority for potentially conflicting rules.
0 commit comments