Custom Protection Rules
Learn how protection rules match web traffic to rule conditions and determine the action to be taken when the conditions are met.
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 Console and WAAS API. For a list of protection rules already available in the service, see Supported Protection Rules.
Custom Protection Rule Syntax
Provides information about custom protection rule syntax for the Web Application Firewall service.
All custom protection rules are expressed in ModSecurity Rule Language. For more information about ModSecurity syntax, see the ModSecurity documentation.
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.
Using the Console
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select Custom protection rules.
- Select Create custom protection rule.
- In the Create custom protection rule dialog box, enter the following:
- Name: A unique name for the protection rule.
- Description: Optional. A description of the custom protection rule.
- Template: Enter the protection rule criteria in ModSecurity Rule Language. Each rule must include two placeholder variables: id:{{id_1}} and ctl:ruleEngine={{mode}}. For more information about ModSecurity syntax, see the ModSecurity documentation.
- Show advanced options: Select this link to display options for tagging. See Overview of Tagging.
-
Choose one of the following:
- To create the rule, select Create.
- To create the rule later using Resource Manager see Creating a Stack from a Resource Creation Page.
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select Custom Protection Rules.
- Select the name of the custom protection rule you want to edit.
- Select Edit.
- Make the necessary changes and then select Save Changes.
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select Custom Protection Rules.
- Find the protection rule in the list, select the , and then Select Move Resource.
-
Choose the destination compartment from the list.
- Select Move Resource.
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select Custom Protection Rules.
-
Select the check box for the protection rule you want to delete.
- Select Delete.
- In the confirmation dialog box, select Delete.
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select the name of the WAF Policy you want to configure rule settings for. The WAF Policy overview appears.
- Select Protection Rules.
- Select the Custom Rules tab.
- Select Add from the Actions drop down menu.
- In the Add Custom Rule dialog box, select a custom protection rule from the drop down menu. If the custom protection rule exists in another compartment, you can change the compartment where the rule exists.
- Select one of the following actions to apply to the rule:
- Detect: Matching requests generate an alert and the request is proxied.
- Block: Matching requests are blocked.
- Select Add.
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select the name of the WAF Policy where you want to edit a custom protection rule.
- Select Protection Rules and then select the Custom Rules tab.
- Select the check box for the custom rule you want to change the action for.
- Select the action from the Actions drop down menu.
- Open the navigation menu and select Identity & Security. Under Web Application Firewall, select Edge Policy Resources.
The Policies list opens. All edge policies are listed in a table.
- Select the name of the WAF Policy where you want to remove a custom protection rule. The WAF Policy overview appears.
- Select Protection Rules.
- Select the Custom Rules tab.
-
Select the check box for the custom rule you want to delete.
- Select delete from the Actions drop down menu.
Using the API
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..<unique_ID>",
"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.