Overriding rule sets

To customize the behavior of a managed ruleset, override the ruleset at deployment. When you override a ruleset, you specify changes to be executed in addition to the default configuration.

You can override a ruleset at the following levels:

Ruleset overrides apply to all rules in the executed ruleset.
Tag overrides apply to all rules with a specific tag. For example, use a tag override to customize the CIS Managed Ruleset so all rules with the wordpress tag are set to Block. If multiple tags have overrides and if a rule has more than one of these tags, the tag overrides order determines the behavior. For rules tagged with multiple overridden tags, the last tag’s overrides apply.
Rule overrides apply to specific rules in a managed ruleset, referenced by their Rule ID.

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

Ruleset overrides and tag overrides apply to both existing and future rules in the managed ruleset. If you want to override existing rules only, you must use rule overrides.

Overriding workflow

To apply an override for a managed ruleset, take the following steps.

List the rule sets available by using the list rule sets operation.
List the rules for that rule set by using the get rule set operation.
Call the update ruleset operation on your phase entry point.
Specify the overrides in the action_parameters of the rule that executes your managed ruleset.

"action_parameters": {
  "id": "<RULESET_ID>",
  "overrides": {
    // ruleset overrides
    "property-to-modify": "value",
    "property-to-modify": "value",
    // tag overrides
    "categories": [
      {
        "category": "<TAG_NAME>",
        "property-to-modify": "value",
        "property-to-modify": "value"
      }
    ],
    // rule overrides
    "rules": [
      {
        "id": "<RULE_ID>",
        "property-to-modify": "value",
        "property-to-modify": "value"
      }
    ]
  }
}

You can override the following rule properties.

"action"
"enabled"

Some managed rulesets can have extra override requirements, or they might override other rule properties.

It is not effective to enable all the rules in a managed ruleset at the instance level by using an override. This change can affect all the zones in your instance. Some rules are disabled by default because they eventually affect legitimate traffic. Do not enable these rules across zones without previous consideration.

Overriding rule sets from the CLI

You can override rule sets from the CLI.

Listing rule sets from the CLI

To list all zone rule sets from the CLI, run the following command:

ibmcloud cis managed-waf rulesets DNS_DOMAIN_ID [-i, --instance INSTANCE] [--output FORMAT]

Where:

DNS_DOMAIN_ID is the ID of the domain.
-i, --instance value is the instance name or ID.
--output value specifies the output format; only JSON is supported.

Listing rules from the CLI

To list the rules under a zone rule set from the CLI, run the following command:

ibmcloud cis managed-waf ruleset DNS_DOMAIN_ID RULESET_ID [-i, --instance INSTANCE] [--output FORMAT]

Where:

DNS_DOMAIN_ID is the ID of the domain.
RULESET_ID is the ID of the ruleset for the rules to be listed.
-i, --instance value is the instance name or ID.
--output value specifies the output format; only JSON is supported.

Overriding managed rule sets from the CLI

To override a managed WAF ruleset from the CLI, run the following command:

ibmcloud cis managed-waf deployment-add-ruleset DNS_DOMAIN_ID RULESET_ID [--match EXPRESSION] [--enabled true|false] [--override-action ACTION] [--override-status STATUS] [--paranoia-level LEVEL] [--override-rules RULE] [-i, --instance INSTANCE] [--output FORMAT]

Where:

DNS_DOMAIN_ID is the ID of the domain.
--match value is the conditions that must be matched for the rule to run. See fields and expressions for a list of values to match.
--enabled value indicates whether the rule is active. Defaults to "true".
--override-action value is the ruleset action of any overrides. Valid values are "managed_challenge", "block", "js_challenge", "log", "challenge".
--paranoia-level value is the OWASP paranoia level. Valid values are "PL1", "PL2", "PL3", "PL4" and it's only available for CIS OWASP Core Ruleset.
--override-rules value is the rules options of the overrides. For example, --override-rules rule=RULE_ID,action=ACTION,enabled=STATUS.
-i, --instance value is the instance name or ID.
--output value specifies the output format; only JSON is supported.

Overriding rule sets with the API

You can override rule sets from the API.

Listing rule sets from the API

To list all zone rule sets from the API, run the following command:

curl -X GET \
  https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'x-auth-user-token: Bearer xxxxxx'

Listing rules from the API

To list all rules for a specific rule set, run the following command:

curl -X GET \
  https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets/$RULESET_ID \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'x-auth-user-token: Bearer xxxxxx'

Where:

$RULESET_ID is the ID of the managed ruleset which the rules are listed for.

Overriding an entry point rule set from the API

To update the entry point rule set from the API with an override, run the following command:

curl -X PUT \
  https://api.cis.cloud.ibm.com/v1/$CRN/zones/$ZONE_ID/rulesets/phases/$RULESET_PHASE/entrypoint \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -H 'x-auth-user-token: Bearer xxxxxx' \
  -d '{"description":"Deploy managed ruleset, enabling a specific rule with log action","rules":[{"action":"execute","expression":"true","action_parameters":{"id":"<MANAGED_RULESET_ID>","overrides":{"rules":[{"id":"<RULE_ID>","enabled":true,"action":"log"}]}}}]}'

Where:

$RULESET_PHASE is the rule set phase that is deployed to. Use http_request_firewall_managed to override managed WAF rule sets.
-d is the object of attributes that are required to create the rule set.
- description defines your own summary of what a rule set is accomplishing.
- rules is the array of rules to deploy with the rule set.
  - action is the action for the rule to take. See Rules actions for a description of available actions.
  - action_parameters is the object for defining what the action operates on.
    - id is the ID of the ruleset to execute. This ID is retrieved from the list zone rulesets operation.
    - overrides is the object of overrides to set upon the selected rule set.
      - rules is the list of rules that are overridden with the selected properties.
        
        id is the ID of the rule to override. This ID is retrieved from the list zone ruleset rules operation.
        
        enabled overwrites even when the rule is enabled.
        
        action specifies the overridden action that the rule takes.
  - expression is the condition under which the rule runs. Using "true" means that this rule always runs.
  - description defines your own summary of what the rule is accomplishing.