Skip to content

Commit

Permalink
[WAF] Account-level configuration (cloudflare#17324)
Browse files Browse the repository at this point in the history 
---------

Co-authored-by: marciocloudflare <83226960+marciocloudflare@users.noreply.github.com>
  • Loading branch information
@pedrosousa @marciocloudflare
pedrosousa and marciocloudflare authored Oct 10, 2024
1 parent 7bb4d70 commit 368cf4f
Show file tree
Hide file tree
Showing 53 changed files with 1,150 additions and 334 deletions.
5 changes: 4 additions & 1 deletion public/_redirects
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1233,6 +1233,8 @@
/waf/security-analytics/ /waf/analytics/security-analytics/ 301
/waf/custom-rules/use-cases/require-valid-hmac-token/ /waf/custom-rules/use-cases/configure-token-authentication/ 301
/waf/tools/scrape-shield/server-side-excludes/ /waf/tools/scrape-shield/ 301
/waf/rate-limiting-rules/create-account-dashboard/ /waf/account/rate-limiting-rulesets/create-dashboard/ 301
/waf/managed-rules/deploy-account-dashboard/ /waf/account/managed-rulesets/deploy-dashboard/ 301

# waiting-room
/waiting-room/how-to/mobile-traffic/ /waiting-room/how-to/json-response/ 301
Expand Down Expand Up @@ -1735,7 +1737,8 @@
/waf/managed-rulesets/* /waf/managed-rules/:splat 301
/firewall/recipes/* /waf/custom-rules/use-cases/:splat 301
/workers/wrangler-legacy/* /workers/wrangler/migration/v1-to-v2/wrangler-legacy/:splat 301
/waf/custom-rulesets/* /waf/custom-rules/custom-rulesets/:splat 301
/waf/custom-rulesets/* /waf/account/custom-rulesets/:splat 301
/waf/custom-rules/custom-rulesets/* /waf/account/custom-rulesets/:splat 301
/waf/exposed-credentials-check/* /waf/managed-rules/check-for-exposed-credentials/:splat 301
/waf/security-events/* /waf/analytics/security-events/:splat 301
/web3/polygon-gateway/* /web3/ 301
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/fundamentals/setup/manage-members/roles.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ Domain-scoped roles apply for a given domain within an account.
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bot Management | Can edit [Bot Management](/bots/plans/bm-subscription/) (including [Super Bot Fight Mode](/bots/get-started/pro/)) configurations. |
| Cache Domain Purge | Grants access to [purge the edge cache](/cache/how-to/purge-cache/) for a specific domain. |
| Domain Administrator | Grants full access to domains in an account, and read-only access to account-wide [Firewall](/waf/managed-rules/deploy-account-dashboard/), [Access](/cloudflare-one/policies/access/), and [Worker](/workers/) resources. |
| Domain Administrator Read Only | Grants read-only access to domains in an account, as well as account-wide [Firewall](/waf/managed-rules/deploy-account-dashboard/), [Access](/cloudflare-one/policies/access/), and [Worker](/workers/) resources. |
| Domain Administrator | Grants full access to domains in an account, and read-only access to account-wide [Firewall](/waf/account/managed-rulesets/deploy-dashboard/), [Access](/cloudflare-one/policies/access/), and [Worker](/workers/) resources. |
| Domain Administrator Read Only | Grants read-only access to domains in an account, as well as account-wide [Firewall](/waf/account/managed-rulesets/deploy-dashboard/), [Access](/cloudflare-one/policies/access/), and [Worker](/workers/) resources. |
| Domain API Gateway | Grants full access to API Gateway (including [API Shield](/api-shield/)). |
| Domain API Gateway Read | Grants read access to API Gateway (including [API Shield](/api-shield/)). |
| Domain DNS | Grants access to edit [DNS settings](/dns/) for domains in an account. |
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/ruleset-engine/custom-rulesets/add-rules-ruleset.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ When you add rules to a custom ruleset using the [Update an account ruleset](/ap

You can use other API operations depending on the type of operation:

- Add a single rule to an existing custom ruleset — use the [Create an account ruleset rule](/api/operations/createAccountRulesetRule) operation.
- Update a single rule in a custom ruleset — use the [Update an account ruleset rule](/api/operations/updateAccountRulesetRule) operation.
- Add a single rule to an existing custom ruleset: Use the [Create an account ruleset rule](/api/operations/createAccountRulesetRule) operation.
- Update a single rule in a custom ruleset: Use the [Update an account ruleset rule](/api/operations/updateAccountRulesetRule) operation.

:::

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/ruleset-engine/custom-rulesets/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Use the following workflow to deploy a custom ruleset at the account level:

You must create a rule with `execute` action in an entry point ruleset to execute the custom ruleset (step 3 in the previous procedure). If you skip this step, the rules of the custom ruleset will not run.

Custom rulesets are currently only supported by the [Cloudflare WAF](/waf/).
Currently, custom rulesets are only supported by the [Cloudflare WAF](/waf/).

:::caution
You cannot execute a custom ruleset from another custom ruleset, only from an entry point ruleset.
Expand Down
124 changes: 10 additions & 114 deletions src/content/docs/ruleset-engine/managed-rulesets/deploy-managed-ruleset.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ sidebar:
order: 2
---

import { RuleID, Render } from "~/components";

You can deploy a managed ruleset at the zone level or at the account level.

To deploy a managed ruleset to a phase, use the [Rulesets API](/ruleset-engine/rulesets-api/).
Expand All @@ -14,133 +16,27 @@ To deploy a managed ruleset to a phase, use the [Rulesets API](/ruleset-engine/r
Use the following workflow to deploy a managed ruleset to a phase at the zone level.

1. Get your [zone ID](/fundamentals/setup/find-account-and-zone-ids/).
2. Invoke the [List account rulesets](/api/operations/listAccountRulesets) operation to obtain the available rulesets. Managed rulesets exist at the account level, but you can deploy them to a zone. Find the ruleset ID of the managed ruleset you wish to deploy.
2. Invoke the [List account rulesets](/api/operations/listAccountRulesets) operation to obtain the available managed rulesets. Managed rulesets exist at the account level, but you can deploy them to a zone. Find the ruleset ID of the managed ruleset you want to deploy.
3. Identify the [phase](/ruleset-engine/about/phases/) where you want to deploy the managed ruleset. Ensure that the managed ruleset belongs to the same phase where you want to deploy it. To learn more about the available phases supported by each Cloudflare product, refer to the specific documentation for that product, or the [Phases list](/ruleset-engine/reference/phases-list/).
4. Add a rule to the zone-level phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) that executes the managed ruleset.
4. Add a rule to the zone-level phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) that executes the managed ruleset. Refer to the following example for details on this step.

### Example

The following example deploys a managed ruleset to the `http_request_firewall_managed` phase of a given zone (`{zone_id}`) by creating a rule that executes the managed ruleset.

```bash
curl --request PUT \
https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_request_firewall_managed/entrypoint \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"rules": [
{
"action": "execute",
"action_parameters": {
"id": "<CLOUDFLARE_MANAGED_RULESET_ID>"
},
"expression": "true",
"description": "Execute Cloudflare Managed Ruleset on my zone-level phase entry point"
}
]
}'
```
<Render file="managed-rulesets/api-zone-example" product="waf" />

```json output
{
"result": {
"id": "<ZONE_PHASE_RULESET_ID>",
"name": "Zone-level phase entry point",
"description": "",
"kind": "zone",
"version": "3",
"rules": [
{
"id": "<RULE_ID_1>",
"version": "1",
"action": "execute",
"action_parameters": {
"id": "<CLOUDFLARE_MANAGED_RULESET_ID>",
"version": "latest"
},
"expression": "true",
"description": "Execute Cloudflare Managed Ruleset on my zone-level phase entry point",
"last_updated": "2021-03-18T18:08:14.003361Z",
"ref": "<RULE_REF_1>",
"enabled": true
}
],
"last_updated": "2021-03-18T18:08:14.003361Z",
"phase": "http_request_firewall_managed"
},
"success": true,
"errors": [],
"messages": []
}
```
In this example, the managed ruleset executes the behavior configured by Cloudflare. To customize the behavior of managed rulesets, refer to [Override a managed ruleset](/ruleset-engine/managed-rulesets/override-managed-ruleset/).

## Deploy a managed ruleset to a phase at the account level

Use the following workflow to deploy a managed ruleset to a phase at the account level.

1. Get your [account ID](/fundamentals/setup/find-account-and-zone-ids/).
2. Invoke the [List account rulesets](/api/operations/listAccountRulesets) operation to obtain the available rulesets. Find the ruleset ID of the managed ruleset you wish to deploy.
2. Invoke the [List account rulesets](/api/operations/listAccountRulesets) operation to obtain the available managed rulesets. Find the ruleset ID of the managed ruleset you want to deploy.
3. Identify the [phase](/ruleset-engine/about/phases/) where you want to deploy the managed ruleset. Ensure that the managed ruleset belongs to the same phase where you want to deploy it. To learn more about the available phases supported by each Cloudflare product, refer to the specific documentation for that product, or the [Phases list](/ruleset-engine/reference/phases-list/).
4. Add a rule to the account-level phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) that executes the managed ruleset. Use parentheses to enclose any custom conditions in the rule expression and end your expression with `and cf.zone.plan eq "ENT"` so that it only applies to zones on an Enterprise plan.
4. Add a rule to the account-level phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) that executes the managed ruleset. Use parentheses to enclose any custom conditions in the rule expression and end your expression with `and cf.zone.plan eq "ENT"` so that it only applies to zones on an Enterprise plan. Refer to the following example for details on this step.

### Example

The following example deploys a managed ruleset to the `http_request_firewall_managed` phase of your account (`{account_id}`) by creating a rule that executes the managed ruleset. The rules in the managed ruleset are executed when the zone name matches one of `example.com` or `anotherexample.com`.

:::caution
Managed rulesets deployed at the account level will only apply to incoming traffic of zones on an Enterprise plan. The expression of your `execute` rule must end with `and cf.zone.plan eq "ENT"` or else the operation will fail.
:::

```bash
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/phases/http_request_firewall_managed/entrypoint \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"rules": [
{
"action": "execute",
"action_parameters": {
"id": "<CLOUDFLARE_MANAGED_RULESET_ID>"
},
"expression": "(cf.zone.name in {\"example.com\" \"anotherexample.com\"}) and cf.zone.plan eq \"ENT\"",
"description": "Execute Cloudflare Managed Ruleset on my account-level phase entry point"
}
]
}'
```

```json output
{
"result": {
"id": "<RULESET_ID>",
"name": "Account-level phase entry point",
"description": "",
"kind": "root",
"version": "5",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "execute",
"action_parameters": {
"id": "<CLOUDFLARE_MANAGED_RULESET_ID>",
"version": "latest"
},
"expression": "(cf.zone.name in {\"example.com\" \"anotherexample.com\"}) and cf.zone.plan eq \"ENT\"",
"description": "Execute Cloudflare Managed Ruleset on my account-level phase entry point",
"last_updated": "2021-03-18T18:30:08.122758Z",
"ref": "<RULE_REF>",
"enabled": true
}
],
"last_updated": "2021-03-18T18:30:08.122758Z",
"phase": "http_request_firewall_managed"
},
"success": true,
"errors": [],
"messages": []
}
```
<Render file="managed-rulesets/api-account-example" product="waf" />

In these examples, the managed ruleset executes the behavior configured by Cloudflare. To customize the behavior of managed rulesets, refer to [Override a managed ruleset](/ruleset-engine/managed-rulesets/override-managed-ruleset/).
In this example, the managed ruleset executes the behavior configured by Cloudflare. To customize the behavior of managed rulesets, refer to [Override a managed ruleset](/ruleset-engine/managed-rulesets/override-managed-ruleset/).
6 changes: 2 additions & 4 deletions src/content/docs/ruleset-engine/managed-rulesets/override-managed-ruleset.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar:
order: 3
---

import { Details } from "~/components";
import { Render, Details } from "~/components";

To customize the behavior of a managed ruleset, override the ruleset at deployment. When you override a ruleset you specify changes to be executed on top of the default configuration. These changes take precedence over the ruleset's default behavior.

Expand All @@ -23,9 +23,7 @@ You can override a ruleset at three levels:

Specific overrides take precedence over more general ones, and rule overrides take precedence over tag overrides, which take precedence over ruleset overrides.

:::caution
Ruleset overrides and tag overrides apply to both existing and **future** rules in the managed ruleset. If you wish to override existing rules only, you must use rule overrides.
:::
<Render file="managed-ruleset-override-warning" product="waf" />

To apply an override for a managed ruleset:

Expand Down
66 changes: 63 additions & 3 deletions src/content/docs/ruleset-engine/rulesets-api/create.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar:
order: 5
---

import { Description, Type } from "~/components";
import { Description, Type, Render } from "~/components";

Creates a ruleset of a given kind in the specified phase. Allows you to create phase entry point rulesets.

Expand Down Expand Up @@ -42,7 +42,7 @@ Use the `rules` parameter to supply a list of rules for the ruleset. For an obje

## Example - Create a custom ruleset

The following example request creates a custom ruleset in the `http_request_firewall_custom` phase containing a single rule.
The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase containing a single rule.

```bash
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
Expand Down Expand Up @@ -111,7 +111,7 @@ curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \

## Example - Create a zone-level phase entry point ruleset

The following example request creates a zone-level phase entry point ruleset at the `http_request_firewall_managed` phase with a single rule that executes a managed ruleset.
The following `POST` request creates a zone-level phase entry point ruleset at the `http_request_firewall_managed` phase with a single rule that executes a managed ruleset.

:::note

Expand Down Expand Up @@ -168,3 +168,63 @@ curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \
"messages": []
}
```

## Example - Create an account-level phase entry point ruleset

The following `POST` request creates an account-level phase entry point ruleset for the `http_ratelimit` phase with a single rule that executes a rate limiting ruleset for all Enterprise zones in the account.

:::note
You do not have to use this method to create a phase entry point ruleset — Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information.
:::

```bash
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"name": "Account-level phase entry point",
"kind": "root",
"description": "This ruleset executes a rate limiting ruleset.",
"rules": [
{
"action": "execute",
"expression": "(cf.zone.plan eq \"ENT\")",
"action_parameters": {
"id": "<RATE_LIMITING_RULESET_ID>"
}
}
],
"phase": "http_ratelimit"
}'
```

```json output
{
"result": {
"id": "<RULESET_ID>",
"name": "Account-level phase entry point",
"description": "This ruleset executes a rate limiting ruleset.",
"kind": "root",
"version": "1",
"rules": [
{
"id": "<RULE_ID>",
"version": "1",
"action": "execute",
"expression": "(cf.zone.plan eq \"ENT\")",
"action_parameters": {
"id": "<RATE_LIMITING_RULESET_ID>"
},
"last_updated": "2024-09-17T15:42:37.917815Z"
}
],
"last_updated": "2024-09-17T15:42:37.917815Z",
"phase": "http_ratelimit"
},
"success": true,
"errors": [],
"messages": []
}
```

<Render file="account-enterprise-zones-only-api" product="waf" />
5 changes: 1 addition & 4 deletions src/content/docs/terraform/additional-configurations/waf-managed-rulesets.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -183,10 +183,7 @@ The following example adds three [overrides](/ruleset-engine/managed-rulesets/ov
- A rule override for rule with ID `75a0060762034a6cb663fd51a02344cb` disabling the rule.
- A tag override for the `wordpress` tag, setting the action of all the rules with this tag to `js_challenge`.

:::caution[Important]

Ruleset overrides and tag overrides apply to both existing and **future** rules in the managed ruleset. If you wish to override existing rules only, you must use rule overrides.
:::
<Render file="managed-ruleset-override-warning" product="waf" />

The following configuration includes the three overrides in the rule that executes the Cloudflare Managed Ruleset:

Expand Down
Loading

0 comments on commit 368cf4f

Please sign in to comment.