Migrating to WAF custom rules

Improved response for Block action

In custom rules, you can customize the response of the Block action.

The default block response is a CIS standard HTML page. If you need to send a custom response for Block actions, configure the custom rule to return a fixed response with a custom response code (403, by default) and a custom body (HTML, JSON, XML, or plain text).

To define a custom response for a single rule, go to Security > WAF > Custom rules, edit the custom rule, and complete the block-related options.

Custom block response configurations are not returned by the Firewall Rules API. Use the Rulesets API to manage this new feature.

Different error page for blocked requests

Requests blocked by a firewall rule with a Block action get a CIS 1020 error code response. CIS users might customize this error page in Custom Pages > 1000 Class Errors.

Requests blocked by a WAF custom rule get a different response: the WAF block response. To customize the default block response, you can either:

• Define a custom WAF block response for your entire zone in Custom Pages > WAF Block. This custom page will always have an HTML content type.
• Define a custom response for requests blocked by a specific WAF custom rule. This custom response supports other content types besides HTML.

If you customized your 1xxx error page in Custom Pages for requests blocked by firewall rules, you must create a new response page for blocked requests by using one of the preceding methods.

New Skip action replacing both Allow and Bypass actions

Firewall Rules supported the Allow and Bypass actions, often used together. These actions were commonly used for handling known legitimate requests — for example, requests coming from trusted IP addresses.

When a request triggered Allow, all remaining firewall rules are not evaluated, effectively allowing the request to continue to the next security product. The Bypass action was designed to specify which security products (such as WAF managed rules, rate-limiting rules, and User Agent Blocking) should not run on the request triggering the action.

With Firewall Rules, if you wanted to stop running all security products for a given request, you would create two rules:

• One rule with Bypass action (selecting all security products).
• One rule with Allow action (to stop executing other firewall rules).

The requirement of having two rules to address this common scenario no longer applies to WAF custom rules. Now use the Skip action, which combines the Allow and Bypass actions. The Skip action fully replaces the Allow and Bypass actions, which are not supported in WAF custom rules.

With the Skip action you can do the following:

• Stop running all the remaining WAF custom rules (equivalent to the Allow action)
• Avoid running other security products (equivalent to the Bypass action)
• A combination of both.

You can also select whether you want to log events matching the custom rule with the Skip action or not. This is especially useful when creating a positive security model to avoid logging large amounts of legitimate traffic.

The Firewall Rules API does not support the Skip action. When you create a custom rule with Skip action, it is translated to Allow and Bypass in the Firewall Rules API. Use the Rulesets API to fully use the new Skip action functionality.

Custom rules are evaluated in order

Firewall rules actions had specific order of precedence when using priority ordering. In contrast, WAF custom rules actions do not have such an order. Custom rules are always evaluated in order, and some actions, such as Block, stop the evaluation of other rules.

For example, if you use priority ordering and had the following firewall rules with the same priority both matching an incoming request:

• Firewall rule #1 — Priority: 2 / Action: Block
• Firewall rule #2 — Priority: 2 / Action: Allow

The request is allowed because the Allow action in Firewall Rules has precedence over the Block action.

In contrast, if you create two WAF custom rules where both rules match an incoming request:

• Custom rule #1 — Action: Block
• Custom rule #2 — Action: Skip (configured to skip all remaining custom rules)

The request is blocked because WAF custom rules are evaluated in order and the Block action stops the evaluation of other rules.

For the WAF custom rules converted from your existing firewall rules, CIS preserves your current order of execution.

Logs and events

Events that are logged by WAF custom rules are available at Security > Events, with Custom rules as their source. For more information, see Using the CIS Security Events capability.

You might still find events that are generated by firewall rules in the Security Events page when you select a time frame including the days when the transition to WAF custom rules occurred. Similarly, you might still find events with both Skip and Allow actions in the same view during the transition period.

New API

The preferred API for managing WAF custom rules is the Rulesets API. The Rulesets API is used on all recent CIS security products to provide a uniform user experience when interacting with IBM API. For more information on migrating to the Rulesets API, see Relevant changes for API users.

The Firewall Rules API and Filters API will still work until 2025-06-15. There will be a single list of rules for both firewall rules and custom rules, and this list contains WAF custom rules. Thanks to an internal conversion process, the Firewall Rules API, and Filters API return firewall rules/filters converted from these WAF custom rules.