[DDoS Protection] L3/4 managed ruleset override guidance updates (#27209)

Kbman99 · patriciasantaana · web-flow · commit a2f0e32f8692 · 2025-12-19T11:54:05.000-08:00
* [DDoS Protection] L3/4 managed ruleset override guidance updates

This change introduces a fix to a mix-up in the logic of how
Network-layer DDoS Attack Protection managed ruleset override
expressions work and adds some additional context, guidance, and
recommendations on how effectively utilize them.

* Apply suggestions from code review

---------

Co-authored-by: Patricia Santa Ana &lt;103445940+patriciasantaana@users.noreply.github.com&gt;
diff --git a/src/content/docs/ddos-protection/managed-rulesets/network/network-overrides/override-examples.mdx b/src/content/docs/ddos-protection/managed-rulesets/network/network-overrides/override-examples.mdx
@@ -17,10 +17,10 @@ The following scenarios detail how you can make use of override rules as a solut
 
 ### VPN traffic is blocked by a UDP rule
 
-If you have VPN traffic concentrated to a single or a few single destination IP addresses and the traffic is being blocked by a UDP rule, you can create an override rule for the UDP rule to the destination IPs or ranges. 
+If you have VPN traffic concentrated to a single or a few single destination IP addresses and the traffic is being blocked by a UDP rule, you can create an override rule for the UDP rule to the destination IPs or ranges.
 
 :::note
-The override only applies to the fingerprint and not the detection. Refer to [Important remarks](/ddos-protection/managed-rulesets/network/network-overrides/override-expressions/#important-remarks) for more information.
+The override only applies to the detection and not the fingerprint generated and used for mitigation. Refer to [Important remarks](/ddos-protection/managed-rulesets/network/network-overrides/override-expressions/#important-remarks) for more information.
 :::
 
 ### Attack traffic is flagged by the adaptive rule based on UDP and destination port
diff --git a/src/content/docs/ddos-protection/managed-rulesets/network/network-overrides/override-expressions.mdx b/src/content/docs/ddos-protection/managed-rulesets/network/network-overrides/override-expressions.mdx
@@ -11,18 +11,20 @@ head:
 
 import { GlossaryTooltip } from "~/components"
 
-Set an override expression for the Network-layer DDoS Attack Protection managed ruleset to define a specific scope for [sensitivity level](/ddos-protection/managed-rulesets/network/override-parameters/#sensitivity-level) or [action](/ddos-protection/managed-rulesets/network/override-parameters/#action) adjustments. For example, you can set different sensitivity levels for different destination IP addresses or ports: a medium sensitivity level for destination IP address `A` and a low sensitivity level for destination IP address `B`.
+Set an override expression for the Network-layer DDoS Attack Protection managed ruleset to define a specific scope for [sensitivity level](/ddos-protection/managed-rulesets/network/override-parameters/#sensitivity-level) or [action](/ddos-protection/managed-rulesets/network/override-parameters/#action) adjustments.
+
+When considering which, if any, expressions you should utilize, think of expressions as a tool to scope overrides to the specific service that the Network-layer DDoS Attack Protection managed ruleset is protecting. That is to say that most services are defined by their destination ports and IPs as opposed to source ports or IPs. Refer to [Imporant remarks](/ddos-protection/managed-rulesets/network/network-overrides/#important-remarks) for more information.
+
+For example, you can set different sensitivity levels for different destination IP addresses or ports: a medium sensitivity level for destination IP address `A` and a low sensitivity level for destination IP address `B`.
 
 ## Available expression fields
 
-You can use the following fields in override expressions:
+The following fields are made available for use in override expressions.
+
+The list of fields we recommend using in expressions:
 
-- `ip.src`
 - `ip.dst`
 - `ip.proto.num`
-- `ip.len`
-- `ip.ttl`
-- `tcp.srcport`
 - `tcp.dstport`
 - `tcp.flags`
 - `tcp.flags.ack`
@@ -31,16 +33,30 @@ You can use the following fields in override expressions:
 - `tcp.flags.reset`
 - `tcp.flags.syn`
 - `tcp.flags.urg`
-- `udp.srcport`
 - `udp.dstport`
 
+The list of fields we do not recommend to be used in expressions:
+
+- `ip.src`
+- `ip.len`
+- `ip.ttl`
+- `tcp.srcport`
+- `udp.srcport`
+
 Refer to the [Fields reference](/ruleset-engine/rules-language/fields/reference/) in the Rules language documentation for more information.
 
 ## Important remarks
 
-- Each expression is limited to 4,000 characters, which means you can enter approximately a maximum of 200 IP addresses in a single expression. However, you can enter IP addresses in CIDR format, which allows you to include a larger number of IP addresses. For example, you can use `192.0.0.0/24` to match IP addresses from `192.0.0.0` to `192.0.0.255`.
-- Override expressions are not allowlists. They apply to the mitigation, not during detection. This means an override only takes effect if the attack fingerprint — as generated by the DDoS managed rules — includes the same fields specified in your expression.
+### Recommended vs. non-recommended fields
+
+Override expressions are not allowlists. Overrides are applied to the detection, and are not applied to the resulting mitigation. This means an override only takes effect if the attack fingerprint, as generated by the DDoS managed rules, includes the same fields specified in your expression. Thus, it makes the use of source fields like `ip.src`, `ip.len`, `ip.ttl`, `tcp.srcport`, and `udp.srcport` unreliable.
+
+The use of non-recommended fields in an expression may result in unexpected behavior. While you may be inclined to utilize source properties, the expressions are not allowlists and including source traffic properties may result in false positives.
 
 For example, if you create an override with sensitivity set to `Essentially Off` for `ip.src eq 192.0.2.1`, it only applies if the fingerprint includes `ip.src`. However, because DDoS attacks are often distributed across many source IPs, the fingerprint may not include `ip.src` at all. In such cases, your override is not applied.
 
 In a common scenario, an attack originating from thousands of IPs can target a single destination IP and port. The fingerprint would focus on the shared attributes, such as the destination IP, port, and additional packet fields that represent strong signals of the attack pattern. Even if your override matches a specific source IP, it will not apply if that field is not present in the fingerprint. As a result, the system will mitigate the attack using the default high sensitivity, and traffic from your specified IP could still be blocked. It is recommended to use more stable expressions such as protocol, destination IP, and destination port.
+
+### Character limits
+
+Each expression is limited to 4,000 characters, which means you can enter approximately a maximum of 200 IP addresses in a single expression. However, you can enter IP addresses in CIDR format, which allows you to include a larger number of IP addresses. For example, you can use `192.0.0.0/24` to match IP addresses from `192.0.0.0` to `192.0.0.255`.
