From c9ad1becef684d1f28f854bba279ed97eaa8507e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20R=C3=BCth?= <1324490+janrueth@users.noreply.github.com> Date: Wed, 19 Nov 2025 18:10:10 +0100 Subject: [PATCH 1/2] [API Shield] Clarify sequence mitigation documentation --- .../security/sequence-mitigation/custom-rules.mdx | 11 ++++++----- .../security/sequence-mitigation/index.mdx | 15 +++++++++++---- src/content/glossary/api-shield.yaml | 2 +- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx b/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx index 959e48012dbde22..134dfc06a0a5383 100644 --- a/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx +++ b/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx @@ -11,14 +11,15 @@ import { GlossaryTooltip, Render } from "~/components" API Shield sequence custom rules use the configured API Shield session identifier to track the order of requests a user has made and the time between requests, and makes them available via [Cloudflare Rules](/rules). This allows you to write rules that match valid or invalid sequences. -These rules are different from [cookie sequence rules](/bots/additional-configurations/sequence-rules/) in a few ways: +These rules are similar to [cookie sequence rules](/bots/additional-configurations/sequence-rules/) but have a different set of prerequisties: -- They need the `fraud_acct_ent` entitlement on a Cloudflare account. +- They also need the `fraud_acct_ent` entitlement on a Cloudflare account. - They require [session identifiers](/api-shield/get-started/#session-identifiers) to be set in API Shield. -- Because they use an API's session identifiers, they can be used for APIs designed for mobile applications. -- Because Cloudflare stores the user state in memory and not in a cookie, the session lifetime is limited to 10 minutes. +- Because they require session identifiers, they can only be used on traffic that can be clearly attributed to individual users through session identifiers, that is, usually authenticated traffic. +- Because Cloudflare stores the user state in memory and not in a cookie, a session's sequence lifetime is limited to 10 minutes. +- Currently, at least 1 [API sequence rule](pi-shield/security/sequence-mitigation/manage-sequence-rules/) must be setup to activate the sequence system. -Rules built using these custom rules are different from sequence mitigation rules built [via API or the Cloudflare dashboard](/api-shield/security/sequence-mitigation/). The custom rules syntax enables free-form logic and response options that the dashboard does not. +Rules built using these custom rules are similar to the sequence rules that can be configured [via the API or the Cloudflare dashboard](/api-shield/security/sequence-mitigation/) as they make use of the same underlying technology. However, these custom rules allow for greater flexibility by enabling to use free-form logic on top of the recorded sequence and provide access to the full response options that rulesets offers. ## Availability diff --git a/src/content/docs/api-shield/security/sequence-mitigation/index.mdx b/src/content/docs/api-shield/security/sequence-mitigation/index.mdx index 9ada2a2621e6bd6..6b7c7c8e0146b40 100644 --- a/src/content/docs/api-shield/security/sequence-mitigation/index.mdx +++ b/src/content/docs/api-shield/security/sequence-mitigation/index.mdx @@ -8,9 +8,9 @@ sidebar: import { GlossaryTooltip, Render } from "~/components" -Sequence mitigation allows you to enforce request patterns for authenticated clients communicating with your API. This feature utilizes the same underlying system that powers Sequence Analytics. +Sequence mitigation allows you to enforce request patterns for authenticated clients communicating with your API. -You can use sequence rules to establish a set of known behavior for API clients. +You can use sequence rules to establish a set of known behavior for API clients or detect and mitigate malicious behavior. For example, you may expect that API requests made during a bank funds transfer could conform to the following order in time: @@ -36,6 +36,11 @@ You can [create a sequence rule](/api-shield/security/sequence-mitigation/manage Sequence rules built via the Cloudflare dashboard using API Shield rules utilize a lookback window to match endpoints in the sequence. The rule will match as long as both endpoints are found within [10 requests](/api-shield/security/sequence-mitigation/#request-limitations) (to endpoints within Endpoint Management) of each other and made within [10 minutes](/api-shield/security/sequence-mitigation/#time-limitations) of each other. +:::note + +Talk to your account executive if the default lookback window is not sufficient for you. +::: + If you want to add multiple endpoints, ignore the lookback window, and configure time-based constraints, refer to [Sequence mitigation custom rules](/api-shield/security/sequence-mitigation/custom-rules/). In the bank funds transfer example, enforcing that a user requests `GET /api/v1/accounts/{account_id}/balance` before `POST /api/v1/transferFunds` is considered a positive security model, since a user may only perform a funds transfer after listing an account balance. @@ -57,7 +62,9 @@ API Shield uses your configured sessi ### Request limitations -API Shield currently stores the last 10 requested endpoints by each API user identified by the session identifier. Sequence mitigation de-duplicates requests to the same endpoint while building the sequence. +API Shield, by default, stores the current and the previous 9 requested endpoints by each individual API user identified through the session identifier. Please reach out to your account executive if the default lookback window of 9 requests is not sufficient for you. + +Sequence mitigation further de-duplicates requests to the same endpoint while building the sequence. To illustrate, in the original [sequence example](/api-shield/security/sequence-mitigation/) listed above, sequence mitigation would store the following sequence: @@ -69,7 +76,7 @@ Sequence mitigation de-duplicated the two requests to `GET /api/v1/accounts/{acc ### Time limitations -Sequence mitigation rules have a lookback period of 10 minutes. If you create a rule that one path must be requested before another path and more than 10 minutes elapses between a user requesting each path, the rule will not match. +Sequence mitigation rules have a lookback period of 10 minutes. That means that any two requests using the same session identifier will extend the sequence if they happen no further than 10 minutes apart. A request happening 10 minutes after the last one for a session identifier will start recording a new sequence. Thus, if you create a rule that one endpoint must be requested before another endpoint and more than 10 minutes elapses between a user requesting each endpoint, the rule will not match. ## Availability diff --git a/src/content/glossary/api-shield.yaml b/src/content/glossary/api-shield.yaml index 58437445b140db9..a6017be900d541a 100644 --- a/src/content/glossary/api-shield.yaml +++ b/src/content/glossary/api-shield.yaml @@ -15,7 +15,7 @@ entries: - term: session identifier general_definition: |- - A session identifier is a unique number that a website assigns to identify a specific user for the duration of their visit. + A session identifier is a unique identifier that a website assigns to identify a specific user for the duration of their visit. - term: source endpoint general_definition: |- From 8099b1d0510992a8632317bdb5df47d90a017cba Mon Sep 17 00:00:00 2001 From: Patricia Santa Ana <103445940+patriciasantaana@users.noreply.github.com> Date: Wed, 19 Nov 2025 10:29:24 -0800 Subject: [PATCH 2/2] Apply suggestions from code review --- .../security/sequence-mitigation/custom-rules.mdx | 6 +++--- .../docs/api-shield/security/sequence-mitigation/index.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx b/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx index 134dfc06a0a5383..5a8ba299fb62782 100644 --- a/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx +++ b/src/content/docs/api-shield/security/sequence-mitigation/custom-rules.mdx @@ -15,11 +15,11 @@ These rules are similar to [cookie sequence rules](/bots/additional-configuratio - They also need the `fraud_acct_ent` entitlement on a Cloudflare account. - They require [session identifiers](/api-shield/get-started/#session-identifiers) to be set in API Shield. -- Because they require session identifiers, they can only be used on traffic that can be clearly attributed to individual users through session identifiers, that is, usually authenticated traffic. +- Because they require session identifiers, they can only be used on traffic that can be clearly attributed to individual users through session identifiers (authenticated traffic). - Because Cloudflare stores the user state in memory and not in a cookie, a session's sequence lifetime is limited to 10 minutes. -- Currently, at least 1 [API sequence rule](pi-shield/security/sequence-mitigation/manage-sequence-rules/) must be setup to activate the sequence system. +- You must set up at least one [API sequence rule](/api-shield/security/sequence-mitigation/manage-sequence-rules/) to activate the sequence system. -Rules built using these custom rules are similar to the sequence rules that can be configured [via the API or the Cloudflare dashboard](/api-shield/security/sequence-mitigation/) as they make use of the same underlying technology. However, these custom rules allow for greater flexibility by enabling to use free-form logic on top of the recorded sequence and provide access to the full response options that rulesets offers. +Rules built using these custom rules are similar to the sequence rules that can be configured [via the API or the Cloudflare dashboard](/api-shield/security/sequence-mitigation/) as they make use of the same underlying technology. However, these custom rules allow for greater flexibility by using free-form logic on top of the recorded sequence and providing access to the full response options that rulesets offers. ## Availability diff --git a/src/content/docs/api-shield/security/sequence-mitigation/index.mdx b/src/content/docs/api-shield/security/sequence-mitigation/index.mdx index 6b7c7c8e0146b40..c3207950ace5f6f 100644 --- a/src/content/docs/api-shield/security/sequence-mitigation/index.mdx +++ b/src/content/docs/api-shield/security/sequence-mitigation/index.mdx @@ -38,7 +38,7 @@ Sequence rules built via the Cloudflare dashboard using API Shield rules utilize :::note -Talk to your account executive if the default lookback window is not sufficient for you. +Contact your account team if the default lookback window is not sufficient for you. ::: If you want to add multiple endpoints, ignore the lookback window, and configure time-based constraints, refer to [Sequence mitigation custom rules](/api-shield/security/sequence-mitigation/custom-rules/). @@ -62,7 +62,7 @@ API Shield uses your configured sessi ### Request limitations -API Shield, by default, stores the current and the previous 9 requested endpoints by each individual API user identified through the session identifier. Please reach out to your account executive if the default lookback window of 9 requests is not sufficient for you. +By default, API Shield stores the current and previous nine requested endpoints by each individual API user identified through the session identifier. Contact your account team if the default lookback window is not sufficient for you. Sequence mitigation further de-duplicates requests to the same endpoint while building the sequence. @@ -76,7 +76,7 @@ Sequence mitigation de-duplicated the two requests to `GET /api/v1/accounts/{acc ### Time limitations -Sequence mitigation rules have a lookback period of 10 minutes. That means that any two requests using the same session identifier will extend the sequence if they happen no further than 10 minutes apart. A request happening 10 minutes after the last one for a session identifier will start recording a new sequence. Thus, if you create a rule that one endpoint must be requested before another endpoint and more than 10 minutes elapses between a user requesting each endpoint, the rule will not match. +Sequence mitigation rules have a lookback period of 10 minutes, which means that any two requests using the same session identifier will extend the sequence if they happen no further than 10 minutes apart. A request for a session identifier that happens 10 minutes after the last one will start recording a new sequence. For example, if you create a rule that one endpoint must be requested before another endpoint, and more than 10 minutes elapses between a user requesting each endpoint, the rule will not match. ## Availability