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 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 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.

Using the Console

To create a custom protection rule
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click Custom protection rules.
  3. Click Create custom protection rule.
  4. 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 Making Rules: The Basic Syntax.
    • Show advanced options: Click this link to display options for tagging. See Overview of Tagging.
  5. Choose one of the following:
To edit a custom protection rule
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click Custom Protection Rules.
  3. Click the name of the custom protection rule you want to edit.
  4. Click Edit.
  5. Make the necessary changes and then click Save Changes.
To manage tags for a custom protection rule
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click Custom Protection Rules.
  3. Click the name of the protection rule you want to manage tags for.
  4. Click the Tags tab to view or edit existing tags. Or click Add tag(s) to add new ones.

For more information, see Resource Tags.

To move a custom protection rule to another compartment
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click Custom Protection Rules.
  3. Find the protection rule in the list, click the Actions menu (Actions Menu), and then click Move Resource.

  4. Choose the destination compartment from the list.

  5. Click Move Resource.
To delete a custom protection rule
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click Custom Protection Rules.

  3. Select the check box for the protection rule you want to delete.

  4. Click Delete.
  5. In the confirmation dialog box, click Delete.
To add a custom protection rule to a WAF policy
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click the name of the WAF Policy you want to configure rule settings for. The WAF Policy overview appears.
  3. Click Protection Rules.
  4. Click the Custom Rules tab.
  5. Click Add from the Actions drop down menu.
  6. 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.
  7. 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.
  8. Click Add.
To apply a new action to a custom protection rule in a WAF policy
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click the name of the WAF Policy where you want to edit a custom protection rule.
  3. Click Protection Rules and then click the Custom Rules tab.
  4. Select the check box for the custom rule you want to change the action for.
  5. Select the action from the Actions drop down menu.
To delete a custom protection rule from a WAF policy
  1. Open the navigation menu and click Identity & Security. Under Web Application Firewall, click Policies.
  2. Click the name of the WAF Policy where you want to remove a custom protection rule. The WAF Policy overview appears.
  3. Click Protection Rules.
  4. Click the Custom Rules tab.

  5. Select the check box for the custom rule you want to delete.

  6. 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.