Introduction

A policy is a set of rules that determine the behavior of PerimeterX’s protection scheme.

By managing Access Control, Volume Based Rules, Risk Cookie, and Data Classification Enrichment, different levels and types of site protection can be configured.

You can create and configure policies for different parts of your site if you have more than one application.

In addition, the Bot Defender Settings section allows you to manage and set your challenge settings, custom parameters, data enrichment, and other product-related configurations.

Active / Bypass

An Application can be set in Active or Bypass mode. Setting the application to Bypass mode disables detection and set the score to zero for all requests. In Bypass mode, the JavaScript Client functionality is limited to cookie management only.

In order to set an application to Active or Bypass, go to Overview -> Policy status & Control -> [Select Application] -> set to Active / Bypass.

Regular Expressions

Regular expressions are patterns used to match character combinations in strings. In JavaScript, regular expressions are also objects. PerimeterX uses JavaScript regular expressions, eliminating the need to escape all characters, except for 12 characters with special functions in the regex (,, ^, $, ., |, ?, *, +, (, ), [, {)

A regular expression pattern is composed of simple characters, such as abc, or a combination of simple and special characters, such as ab*c (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)

Important tips for building a safe regex

• Escaping a special character (,, ^, $, ., |, ?, *, +, (, ), [, {) is necessary when one of the characters is used literally. To escape a special character, use \ before the character. For example, to search for a followed by * followed by b, you'd use a\*b
• When writing the regex, try to be as explicit as possible. Catastrophic backtracking or exponential time regexes are not recommended, as they are extremely computationally heavy, and impacts effective detection by PerimeterX.
• Avoid using wildcards characters (or use sparingly), such as * or +,
• Avoid using nested capturing groups.
• When writing a regex for a User Agent, we recommend using a very specific User Agent that will not accidentally appear in the attacker’s User Agents.
• Use the | to separate between User Agents.

For more information on building a regex, see:

• https://regexr.com/
• https://www.regular-expressions.info/catastrophic.html?wlr=1
• https://perlgeek.de/blog-en/perl-tips/in-search-of-an-exponetial-regexp.html

Examples of how to build a safe regex

To create a Custom Rule to block traffic from User Agent:

PerimeterX/4.16.1 (iPhone; iOS 13.3; Scale/2.00), Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.120 Safari/537.36 OPR/64.0.3417.167

All special characters must be escaped with \:

PerimeterX/4\.16\.1 \(iPhone; iOS 13\.3; Scale/2\.00\), Mozilla/5\.0 \(Windows NT 10\.0; Win64; x64\) AppleWebKit/537\.36 \(KHTML, like Gecko\) Chrome/77\.0\.3865\.120 Safari/537\.36 OPR/64\.0\.3417\.167

To create an Allowlist rule to allow any User Agent containing automation use:

.*automation.*

If you built a regex that you think is safe, and PerimeterX is still not allowing it, contact PerimeterX Support

Access Control

Access Control allows you to customize Allowlist and Denylist rules, and allow and/or deny specific bots, IP addresses and access methods.

Custom Rules

Custom Rules allows you to configure custom Allowlist or Denylist rules. Custom Rules can also be configured with the Custom Rules API

Custom Rules can contain multiple conditions and categories. Only when all of the rules conditions match (using the AND operator) the action (allow/deny/hard block) is executed.

Categories include:

📘

Note

Multiple values can be including for the following categories. The values must be comma-separated:

• Client IP
• Client IP Ranges
• True IPs
• True IP Ranges
• HTTP Methods

Actions include:

To add a Custom Rule:

1. Navigate to Product Settings > Security Policy, select the Policy Name, and access the Your custom rules tab. There are no default custom rules.

2. Click Add custom rule.

3. Fill in the Description, set the rule priority, rule response, and define the rule's logic.

4. Click Add Rule

5. Click Save Changes

PerimeterX Known Bots & Crawlers and IP Classification configurations provide a recommended rule response (Allowlist or Denylist). You can change these items to suit your website needs.

📘

Note

Please note that Custom Rules apply before Known bots & crawlers and IP classifications. In addition, within your custom rules, higher rules take precedence.

Custom Rules API

The Custom Rules API allows you to configure Allowlist and Denylist rules via API calls.

For more information on configuring Access Control and Custom Rules, see Access Control.

Requests

Requests must be sent over HTTPS using a content type of application/json and include the Authorization header that is used for authentication.

All requests are made to the base URL of https://console.perimeterx.com/api/v1/custom_rules

Authentication

In order to access the PerimeterX Custom Rules API, you are required to present an authentication token in the HTTP Authorization header.

The following is an example:

Authorization: Bearer <TOKEN>

Authentication tokens can be generated in the PerimeterX Portal (https://console.perimeterx.com/). For more information see Managing Applications .

Endpoints

Create custom rule

Parameters

Request Schema

{
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "type": {
        "enum": ["none", "blacklist", "whitelist", "hardblock"]
      },
      "conditions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "enum": ["ua", "ips", "ipRanges", "domain", "trueIps", "trueIpRanges", "url", "custom_param1", "custom_param2", "custom_param3", "custom_param4", "custom_param5", "custom_param6", "custom_param7", "custom_param8", "custom_param9", "custom_param10"]
            },
            "value": {
              "type": [
                "string",
                "object"
              ],
              "properties": {
                "option": {
                  "enum": ["prefix", "exact", "suffix", "contains", "regex"]
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "option",
                "value"
              ]
            }
          }
        }
      }
    },
    "required": [
      "description",
      "type",
      "conditions"
    ]
  }

Request Example

curl -X POST
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       -d '{
        "description": "custom rule description",
        "type": "blacklist",
        "conditions": [{"category":"ips","value":"1.1.1.1"},{"category":"domain","value":{"option":"exact","value":"example.com"}}]
        }'
        "https://console.perimeterx.com/api/v1/custom_rules"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "custom rule description",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }

Update custom rule by rule id

Parameters

Request Schema

{
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      },
      "type": {
        "enum": ["none", "blacklist", "whitelist", "hardblock"]
      },
      "conditions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "category": {
              "enum": ["ua", "ips", "ipRanges", "domain", "socketIps", "socketIpRanges", "url", "custom_param1", "custom_param2", "custom_param3", "custom_param4", "custom_param5", "custom_param6", "custom_param7", "custom_param8", "custom_param9", "custom_param10"]
            },
            "value": {
              "type": [
                "string",
                "object"
              ],
              "properties": {
                "option": {
                  "enum": ["prefix", "exact", "suffix", "contains", "regex"]
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "option",
                "value"
              ]
            }
          }
        }
      }
    },
    "required": [
      "description",
      "type",
      "conditions"
    ]
  }

Request Example

curl -X PUT
      -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       -d '{
        "description": "updated custom rule description",
        "type": "blacklist",
        "conditions": [{"category":"ips","value":"1.1.1.1"},{"category":"domain","value":{"option":"exact","value":"example.com"}}]
        }'
        "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "updated custom rule description",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }

Delete custom rule by rule id

Parameters

Request Example

curl -X DELETE
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "string"
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": "success",
    "message": "success"
  }

Get custom rule by rule id

Parameters

Request Example

curl -X GET
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules/a596bc02-1189-48b1-9cf2-12001495754e"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "conditions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "object"
                  ],
                  "properties": {
                    "option": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "option",
                    "value"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "id",
          "description",
          "type",
          "conditions"
        ]
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": {
      "id": "a596bc02-1189-48b1-9cf2-12001495754e",
      "description": "custom rule 1",
      "type": "blacklist",
      "conditions": [
        {
          "category": "ua",
          "value": "PhantomJS"
        },
        {
          "category": "ips",
          "value": "1.1.1.1"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        },
        {
          "category": "custom_param1",
          "value": "test"
        }
      ]
    },
    "message": "success"
  }

Get all custom rules

Request Example

curl -X GET
       -H "Authorization: Bearer <JWT>"
       -H "Content-Type: application/json"
       "https://console.perimeterx.com/api/v1/custom_rules"

Response Schema

{
    "type": "object",
    "properties": {
      "result": {
        "type": "boolean"
      },
      "content": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "conditions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string"
                  },
                  "value": {
                    "type": [
                      "string",
                      "object"
                    ],
                    "properties": {
                      "option": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "option",
                      "value"
                    ]
                  }
                }
              }
            }
          },
          "required": [
            "id",
            "description",
            "type",
            "conditions"
          ]
        }
      },
      "message": {
        "type": "string"
      }
    }
  }

Response Example

{
    "result": true,
    "content": [
      {
        "id": "a596bc02-1189-48b1-9cf2-12001495754e",
        "description": "custom rule 1",
        "type": "blacklist",
        "conditions": [
          {
            "category": "ua",
            "value": "PhantomJS"
          },
          {
            "category": "ips",
            "value": "1.1.1.1"
          },
          {
            "category": "domain",
            "value": {
              "option": "exact",
              "value": "example.com"
            }
          }
        ]
      },
      {
        "id": "46a49376-042d-4ccd-96e4-4f753a6d0930",
        "description": "custom rule 2",
        "type": "none",
        "conditions": [
          {
            "category": "ips",
            "value": "2.2.2.2"
          }
        ]
      }
    ],
    "message": "success"
  }

Error Messages and Codes

The Custom rules API returns error messages in JSON format.

Example

{
    "result": false,
    "content": "Invalid authorization token"
  }

The following table describes the codes which may appear when working with the API.

Known Bots & Crawlers

During the tuning process and in PerimeterX's ongoing tuning of the algorithms, bots and crawlers are identified in your application traffic. You are prompted to classify these bots & crawlers both during the initial tuning process and as part of the ongoing tuning process.

The list of known bots & crawlers is maintained by PerimeterX. Of these, some are Allowed or Denied by default. Traffic from known bots & crawlers that are not Allowed or Denied by default is put through to the PerimeterX default detection process. You can select whether to allow or to deny these bots & crawlers, depending on your organization's needs.

Once a week, we will notify you via email in case traffic started coming in from a known bot or crawler which has not yet been classified. Clicking the notification opens the policy's page, and you are directed to take action (Allow or Deny) on the bot. Until action is taken on a known bot or crawler, they will continue to be put through the PerimeterX default detection process.

Known bots & crawlers that generate traffic appear at the top of the Known Bots & Crawlers section. Known bots & crawlers that generate traffic and are not allowed or denied appear in a list above the main Known Bots & Crawlers list with a red dot next to them. These bots & crawlers will remain in this top section until you change policies, or until you refresh the page.

📘

Note

When the traffic detection on an application is below the detection threshold set by PerimeterX, the application’s Volume will be N/A. Once the detection threshold is reached, the application’s Volume is displayed. When no traffic is detected, the Volume is displayed as 0.

Known bots & crawlers can be classified by setting the Rules Response as follows:

• Allowlist to add the specific known bot or crawler to your Allowlist.

• Denylist to add the specific known bot or crawler to your Denylist.

• PerimeterX Managed Traffic matching this rule will be subject to PerimeterX’s detection process.

Changes take effect immediately.

Note that the recommended rule response will be marked with a “star”.

Known bots & crawlers that have not generated any traffic can also be classified by selecting the rule response for the specific bot or crawler.

To include an automation tool service in the Known Bots & Crawlers list, please contact PerimeterX Support, who will determine whether the tool can safely added to the Known Bots & Crawlers list.

Authorized Services Rate Limiting Rules

Rate Limiting Authorized (allowed) services allow you to limit the rate that authorized services send requests to your server. Once the limit is reached an HTTP 429 response (request rate limit exceeded) is served.

In the main Access Control section, you must first define which services to authorize, either as a custom rule, or as part of the Known Bots and Crawlers. All authorized services that have been added to the Allowlist are available for rate limiting. (apply your changes after adding an allowed service for the dropdown list in the rule creation process to be updated).

To add a rule:

1. Within Bot Defender product, navigate to Product Settings > Security Policy and open the Rate Limiting Rules tab. There are no default custom rules.

2. Click Add rate limit rule. A new line is added to the Rate Limiting Rules list.

3. Select the service you wish to rate limit from the dropdown list (based on name/description or ID). If you cannot locate your service, you must save the changes after adding the new service to the custom list or to the PerimeterX configuration and try again.

4. Select the rate limit of the service and the time window that the service will be limited for (in seconds). You can also apply a specific lifetime duration (unlimited by default). During this time the rule will be enforced, and will be expired after the defined end time.

5. Click Save Changes.

📘

Note

You can add multiple rules for the same service name/id for different time windows.

Volume Based Rules

Volume Based Rules allow you to define the volume of activity considered questionable by PerimeterX.

The panel is divided into two sub-panels:

Page Views – Intended for regular pages in your web application. Page Views are calculated against a user’s access to full pages, not including individual requests, such as XHRs.

Available Categories:

• Page Views per Visitor - Defines the threshold for the number of page views from a single visitor.

• Page Views per Visitor per Tab - Defines the threshold for the number of page views from a single visitor and a single browser tab.

• Page Views per Client IP - Defines the threshold for the number of page views from a single client IP.

• Requests per Custom Parameter - Defines the threshold for the number of requests per single custom parameter.

Requests – Intended for any type of request, but specifically useful for APIs. Requests are measured against any individual HTTP request from your application.

Available Categories:

• Requests per Client IP - Defines the threshold for the number of server requests from a single client IP.

• Requests per User-Agent per Client IP - Defines the threshold for the number of server requests from a single client (Client IP + User-agent).

Available Actions:

1. Click Add page view/ page request rule to add another rule. Each rule is evaluated independently of the others.

2. Choose a category from the dropdown list.

3. Enter the threshold of page views or requests

4. Enter the time range for the rule. Volume Based Rules have a time range of 10 seconds to 86400 seconds (1 day).

5. Click Save Changes to add the new rule.

Website Sections

Website Sections is an additional option for defining a "website section" is available in the request panel. Website sections split your app into parts, allowing you to define different rate-limiting rules for each part.

📘

Note

Each rate-limiting rule is evaluated separately. This makes it possible to have part of the website included in two or more sections. When a request is sent to that part of the website, it will count against all relevant rules simultaneously. The “entire app” section is counted against all requests coming to the app.

• To add a new section, In the “Apply on” column, Click the To be applied on -> and then select an existing section or Create new section.
• To edit a section click the pencil icon next to its name.
• To assign a different section to a rule, click the section name and select a different one.

When adding or editing a section, the pop-up dialog allows you to choose a name and a list of URLs. Separate the URLs with commas or line breaks. Each URL must begin with a forward slash (“/”).

Deleting a section completely removes it, as well as all of the rules referencing that section.

Risk Cookie

The Risk Cookie is an HTTP cookie set by PerimeterX on each request of a client session. The information contained in the Risk Cookie can be used to determine what actions should be taken; this includes blocking the session, issuing a challenge page, or changing the application behavior.

📘

Note

1. The default PerimeterX policy does not apply the Risk Cookie. To use the Risk Cookie, with or without encryption, you must create a new policy other than the default policy provided by PerimeterX.

2. To enable the risk cookie, generate a cookie key. The cookie key, an identifier used by PerimeterX, is used by your server to validate the Risk Cookie. To generate a new cookie key, click Generate Cookie Key.
   Note that If you generate a new cookie key, and are using the old cookie key in your application or infrastructure to perform cookie validation, the incorrect HMAC will be computed for the cookie signature. This can yield undesirable results. Take extra precautions when generating a new cookie key.

Duplicating a Policy

Duplicating a policy makes it easier to create a new policy similar to an existing policy, with minor changes.

To duplicate a policy:

1. In the Security Policy section, select the policy you want to duplicate from the list of available policies (can be found in the “Policy Name” drop-down).

2. Click Duplicate Policy (on the right-hand side of the screen). A new policy is created with the same name as the existing policy + copy.

3. To use the new policy, make sure to connect the requested application to the new policy. This can be done in the *Applications connected to policy” tab, or in the “Overview” section by selecting the new policy as the “policy applied”.

Access Tokens

Access Tokens allow you to securely allow traffic that is generated by friendly applications/users.

To generate an access token, click Add and assign it a lifetime by clicking on the desired date/time.
Page requests using this token by setting HTTP Header x-px-access-token: will automatically be allowed by the Bot Defender and be considered as "Custom Allowlist" for the lifetime of the access token.

Challenge Bypass Tokens

The Challenge Bypass Token allows you to bypass the human challenge in testing environments.

The token is available in Product Settings -> Challenge Settings -> [Application Name] -> Challenge Tokens

1. Select Add Token to generate the token then select Save Changes
2. Add the x-px-captcha-testing header with the token as the value so it will be included on the outgoing request.
3. When presented with a Human Challenge, refresh the page and the challenge will be bypassed.

The request will go through as if the challenge was solved and a "good" cookie will be baked. The token can be used multiple times.

Data & Configuration

In Product Settings -> Data & Configuration you can configure custom parameters and data enrichment settings. Click on the links below for further information:

• Custom Parameters
• Data Enrichment