Oracle Cloud Infrastructure Documentation

Custom Protection Rules

The WAF service allows you to define and apply custom protection rules from open source firewall modules to your WAF configurations, such as ModSecurity modules. This topic describes how to format, create, and implement custom protection rules in your WAF policies using the WAAS API. For a list of protection rules already available in the service, see Supported Protection Rules.

Note

Custom protection rules can only be created using the WAAS API.

Custom Protection Rule Syntax

All custom protection rules are expressed in ModSecurity Rule Language. For more information about ModSecurity syntax, see Making Rules: The Basic Syntax.

Additionally, each rule must include two placeholder variables that are updated by the WAF service upon publication of the rule.

id: {{id_1}} - This field is updated with a unique rule ID generated by the WAF service which identifies a SecRule. More than one SecRule can be defined in the template field of a CreateCustomProtectionRule call. The value of the first SecRule must be id: {{id_1}} and the id field of each subsequent SecRule should increase by one, as shown in the example.

ctl:ruleEngine={{mode}} - The action to be taken when the criteria of the SecRule are met, either OFF, DETECT or BLOCK. This field is updated with the corresponding value of the action field of the CustomProtectionRuleSetting object when using the UpdateWafConfig operation.

Example of a custom protection rule format:

SecRule REQUEST_COOKIES "regex matching SQL injection - part 1/2" \
	"phase:2,                                                 \
	msg:'Detects chained SQL injection attempts 1/2.',        \
	id: {{id_1}},                                             \
	ctl:ruleEngine={{mode}},                                  \
	deny"
	SecRule REQUEST_COOKIES "regex matching SQL injection - part 2/2" \
	"phase:2,                                                 \
	msg:'Detects chained SQL injection attempts 2/2.',        \
	id: {{id_2}},                                             \
	ctl:ruleEngine={{mode}},                                  \
	deny"

Actions

The WAF service can take an action on an HTTP request when the criteria of a custom protection rule are met.

  • DETECT - Logs the request when the criteria of the custom protection are met.
  • BLOCK - Blocks the request when the criteria of the custom protection rule are met.
  • OFF - The custom protection rule is inactive and will take no action.

Create a Custom Protection Rule

Custom protection rules can be created and added to a compartment using the CreateProtectionRule call in the WAAS API. Using ModSecurity Rule Language formatting, populate the template field with the criteria of the rule.

Example:

{
  "compartmentId": "ocid1.compartment.region1..aaaaaaaa5n4ocdo64z66dzfftcvo6ntalkpojfiiwgmxohi4tlakqosvdrmq",
  "description": "The description text for the rule being created",
  "displayName": "Custom Protection Rule Name",
  "template": "SecRule REQUEST_URI / \"phase:2, t:none, capture, msg:'Custom (XSS) Attack. Matched Data: %{TX.0} found within %{MATCHED_VAR_NAME}: %{MATCHED_VAR}', id:{{id_1}}, ctl:ruleEngine={{mode}}, tag:'Custom', severity:'2'\""
}

Adding Custom Protection Rules to a WAF Configuration

Custom protection rules can be added to a WAF configuration using the UpdateWafConfig call in the WAAS API.

Add the OCID and the desired action to take to the CustomProtectionRuleSetting object of the UpdateWafConfig schema.

Example:

[
  {
    "action": "BLOCK",
    "id": "ocid1.waascustomprotectionrule.oc1..aaaaaaaalxd4jrws4rbbnddzlnotu3giuzo53kopbj747mbvarttr7vyy7ja"
  },
  {
    "action": "DETECT",
    "id": "ocid1.waascustomprotectionrule.oc1..aaaaaaaamx5r72ntmmhwgeaspzpdqcwsgprpuvwsa7xoshnyo3xhtpwcobeq"
  }
]

To view a list of available custom protection rules in a compartment and their corresponding OCIDs, use the ListCustomProtectionRules call in the WAAS API.