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 959e48012dbde2..5a8ba299fb6278 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 (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. +- 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 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 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 9ada2a2621e6bd..c3207950ace5f6 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 + +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/). 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. +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. 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, 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 diff --git a/src/content/glossary/api-shield.yaml b/src/content/glossary/api-shield.yaml index 58437445b140db..a6017be900d541 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: |-