Help Center

  1. StackPath Help
  2. WAF
  3. How-To Guides

WAF Custom Rule Editor

Avatar
Kevin Bond
Updated:

Overview

You can use this document to learn how to create custom WAF rules used to manage requests.

The WAF rule editor allows you to create more complex and robust rules, such as control access to specific URLs, limit access to your application, as well as allow or block countries or organizations.

If you simply want to create ACLs to allow or block IP addresses, see our Allowing and Blocking IP Addresses article.

Review Rule Types

With the WAF rule editor, you can create the following rule types:

Rule type Description
IP

You can use this rule type to challenge requests based on a specified IP address.

You can enter multiple IP addresses.

  • To enter multiple IP addresses, separate each address with a comma.

You cannot enter a subnet.
IP range

You can use this rule type to challenge requests based on a specified IP address range.

For example, if you enter 8.8.8.8 and 10.10.10.10, then every address higher than 8.8.8.8 and every address lower than 10.10.10.10 will trigger the rule.
URL

You can use this rule type to challenge requests based on a specified URL.

The expression may start with slash ( / ) to represent the path following the hostname in the URL.

You can create the rule to trigger for:

  • An exact match, such as /index.html.
    • For an exact match, you must enter a slash ( / ).
  • A partial match, such as index.
    • For a partial match, any request that contains index, such as /index.html, /index.htm, /index.php, will cause the rule to trigger.
User Agent

You can use this rule type to challenge requests based on a specified user agent.

You can create the rule to trigger for:

  • An exact match, which would include a specific user agent, such as Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko). Chrome/44.0.2403.157 Safari/537.36.
  • A partial match, which would include a more general user agent type, such as AppleWebKit.
    • In this case, any user agent with AppleWebKit will trigger the rule.
Header

You can use this rule type to challenge requests based on a specified header.
HTTP Method You can use this rule type to challenge requests based on a specified HTTP method, such as GET, POST, etc.
File Extension You can use this rule type to challenge requests based on a specified file type, such as PDF, JPEG/JFIF, or EXE.
Content Type You can use this rule type to challenge requests based on a specified content type, such as application/pdf.
Country You can use this rule type to challenge requests based on the country associated with the requesting IP address. This challenge is based on public IP address databases.
Organization

You can use this rule type to challenge requests based on the organization associated with the requesting IP address. This challenge is based on a public database that contains known ranges relating to organizations.
Tag

You can use this rule type to sanction requests based on specific pre-defined tags provided by StackPath.

Click here to access the full list of tags, their API slugs and their descriptions.
User Defined Tag

You can use this rule type to sanction requests based on custom generated tags named "user defined tags".

User defined tags can be defined as part of the portal UI or through an API call, using the "tag" action in rules (see actions below).

To learn more about the robust tag ecosystem, see Understanding Tag Rules.

Review Action Types

To complement a rule type, select the action type that will trigger based on the conditions you specify.

If you create multiple rules with the same conditions, then only the action with the highest priority level will take place.

For example, if you create a rule to Allow 1.1.1.1 to access your application, and then you create another rule to present a Captcha screen to 1.1.1.1, then only  Allow action will be triggered because tit has a higher priority level than the Captcha action. Review the Priority level column.

The Tag action does not challenge requests, so it does not have an assigned priority level. All Tag action rules run first, before all the other action types, and don't stop the rule engine, even after the condition has been met and the tag has been applied. Thus, the user defined tags that are generated in this run can be used in the "user defined tag" condition (see above) of the same run (same request processing).

Action type Description Priority level
Monitor

This action type will log any request that meets the condition of the rule.

This action type does send any challenge to the user.

First
Allow

This action type will allow specified traffic to view the application's content and exclude the user from any security checks.

Second
Block

This action type will block specified traffic from accessing the application's content.

Third
Captcha

This action type will display a Captcha challenge before the user can view the application's content.

Fourth
JavaScript Validation

This action type will display a JavaScript validation challenge before the user can view the application's content.

 Fifth
Tag

This action type will tag a request with the custom tag you specify (a user defined tag).

This action type does not send any challenge to the user, rather it only adds information to a request.

N/A

 

Create a Custom WAF Rule

  1. In the StackPath Control Portal, in the left-side navigation menu, click Sites.
  2. Locate and select the desired site.
  3. In the left-side navigation menu, click EdgeRules.
  4. Navigate to Custom Rules, and then click Add WAF Rule.
  5. In Rule Name, enter a descriptive name.
  6. Under Rule Status, use the slider to immediately enable or disable the rule.
    • As an option, you can create a disabled rule, and then at a later time, you can enable the rule.
  7. Under Rule Type, select WAF.
  8. Next to IF, select a rule type.
    Rule type Instructions

    For a single or multiple IP addresses
    1. In the first drop-down menu, select IP.
    2. In the next drop-down menu:
      • To- .
      • To apply the rule to every IP address except for the specified IP address, select Not.
    3. In the field, enter the IP address.
      • To enter multiple IP addresses, separate each address with a comma.
    For an IP range
    1. In the first drop-down menu, select IP range.
    2. In the next drop-down menu:
      • To apply the rule only to the specified IP range, select -- .
      • To apply the rule to every IP address except for the specified IP range, select Not.
    3. In the first field, enter the first address of the range.
    4. In the next field, enter the last address of the range.
    For a URL
    1. In the first drop-down menu, select URL.
    2. In the next drop-down menu:
      • To apply the rule only to the specified URL, select -- .
      • To apply the rule to every URL except for the specified URL, select Not.
    3. In the next drop-down menu:
      • To apply the rule only when the requested URL matches the specified URL, select Equals.
        • For example, if the specified URL is /blog, then when a request is made to /blog, the rule will trigger. If a request is made to /blogarticle, then the rule will not trigger.
      • To apply the rule when the requested URL partly matches the specified URL, select Contains.
        • For example, if the specified URL is /blog, then when a request is made to /blog, the rule will trigger. If a request is made to /blogarticle, then the rule will also trigger.
    4. In the field, enter a URL to your application.
      • If you selected Equals, then you must enter a slash ( / ).
    For a user agent
    1. In the first drop-down menu, select User Agent.
    2. In the next drop-down menu:
      • To apply the rule only to the specified user agent, select -- .
      • To apply the rule to every user agent except for the specified user agent, select Not.
    3. In the next drop-down menu:
      • To apply the rule only when the user agent matches the specified user agent, select Equals.
        • For example, you could enter a very specific user agent, such as
        • Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.157 Safari/537.36. In this case, the rule will only trigger when the user agent matches exactly.
      • To apply the rule when the user agent partly matches the specified user agent, select Contains.
        • For example, if you enter AppleWebKit, then any AppleWebKit user agent will trigger the rule.
        • You can still enter a specific user agent, and any requesting user agent that partially matches the header will trigger the rule. For example, if you enter Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.157 Safari/537.36, then any matching component will trigger the rule.
    4. In the field, enter the user agent.
    For a header
    1. In the first drop-down menu, select Header.
    2. In the next drop-down menu:
      • To apply the rule only to the specified header, select -- .
      • To apply the rule to every header except for the specified header, select Not.
    3. In the field, enter a header key.
    4. In the next drop-down menu:
      • To apply the rule only when the header matches the specified header, select Equals.
        • In this case, you can enter a specific header, which means the rule will only trigger when the requesting header matches exactly.
      • To apply the rule when the header partly matches the specified user agent, select Contains.
        • In this case, you can enter a generic header, which means that any requesting header that matches this generic header will trigger the rule.
        • You can still enter a specific header, and any requesting header that partially matches the header will trigger the rule.
    5. In the field, enter the header value.
    For an HTTP method
    1. In the first drop-down menu, select HTTP Method.
    2. In the next drop-down menu:
      • To apply the rule only to the specified HTTP method, select -- .
      • To apply the rule to every HTTP method except for the specified HTTP method, select Not.
    3. In the next drop-down menu, select the HTTP method.
    For a file extension
    1. In the first drop-down menu, select File Extension.
    2. In the next drop-down menu:
      • To apply the rule only to the specified file extension, select -- .
      • To apply the rule to every file extension except for the specified file extension, select Not.
    3. In the field, enter the file extension.
    For a specific content type
    1. In the first drop-down menu, select Content Type.
    2. In the next drop-down menu:
      • To apply the rule only to the specified content type, select -- .
      • To apply the rule to every content type except for the specified content type, select Not.
    3. In the field, enter the content type.
    For a country
    1. In the first drop-down menu, select Country.
    2. In the next drop-down menu:
      • To apply the rule only to the specified country, select -- .
      • To apply the rule to every country except for the specified country, select Not.
    3. In the next drop-down menu, select the country.
      • You can select multiple countries.
    For an organization
    1. In the first drop-down menu, select Organization.
    2. In the next drop-down menu:
      • To apply the rule only to the specified organization, select -- .
      • To apply the rule to every organization except for the specified organization, select Not.
    3. In the next drop-down menu, select the organization.
    For a tag
    1. In the first drop-down menu, select Tag.
    2. In the next drop-down menu:
      • To apply the rule only to a specific tag, select --.
      • To apply the rule to every tag except for the specific tag, select Not.
    3. In the next drop-down menu, select the tag.
      • You can select multiple tags.
    For a user defined tag
    1. In the first drop-down menu, select User Defined Tag.
    2. In the next drop-down menu:
      • To apply the rule only to the specified tag, select -- .
      • To apply the rule to every request except the requests containing the specified user defined tag, select Not.
    3. In the field, enter the user defined tag you would like to use.
  9. (Optional) Next to AND, create a second condition to complement the first condition.
    • If you create multiple conditions, then the rule will only trigger when all conditions are met.
  10. Next to THEN, select an action type (Monitor, Allow, Block, Captcha, JavaScript Validation, Tag).
  11. Click Save Rule.

Custom WAF Rule Example

In our example below, we've created a custom WAF rule that will allow a trusted administrator access to our site. Please note that you can apply additional conditions using the AND option as well.allow_admin.png

 

Edit or Delete Custom WAF Rules

You can use these instructions to edit or delete an existing custom WAF rule.

  1. In the StackPath Control Portal, in the left-side navigation menu, click Sites.
  2. Locate and select the desired site.
  3. In the left-side navigation menu, click EdgeRules.
  4. Navigate to Custom Rules.
  5. Locate the desired rule, and then under Action, click the corresponding ellipses.
  6. Click Edit or Delete, and then make your desired changes.
Was this article helpful?

Related articles

Not finding what you need?

95% of questions can be answered using the search tool. This is the quickest way to get a response.

Contact Us