Custom Rules

By using Custom Rules, you can define your own Allow and Deny lists to adjust default Bot Defender settings to your specific needs.

You can create Custom Rules either on HUMAN Portal or by using API calls.

Creating Custom Rules on HUMAN Portal

  1. Navigate to Product Settings > Security Policy.
  2. Under Policy Name, select the required policy.
  3. Under Policy Rules, click Add custom rule.
  4. In the New custom rule ID window that opens, define the following:
    • Rule description and priority
    • Rule response - Allowlist, Denylist, or HardBlock
    • Rule logic - Category and values. Where multiple values are allowed, separate them with a comma.
  5. Click AND if you want to add another category to the rule.
  6. Click Add Rule.
  7. Click Save Changes.

Category

Description

User Agent

Full UA regex example:
AdoreMe/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

Partial UA regex example:
.*automation.*

See Regular Expressions for details on regex syntax.

Client IPs

The reported client IP address, as deducted by special forwarding headers used by proxy services (such as x-forwarded-for). This IP in general is less reliable, as it is easily manipulated.

Client IP Ranges

Client IP addresses included within the specified range.

Domain

The domain of the website you want to block

True IPs

The true IP address that is connected to the PerimeterX service. This IP is extremely hard to fake. When the client is using a proxy service to access the Internet, the IP address will be of the forwarding proxy service and not of the actual user.

True IP Ranges

True IP addresses included within the specified range

Path

URL’s path part.
See Regular Expressions for details on regex syntax.

Client IP ASN

The Autonomous System Number, to which the client IP belongs

True IP ASN

The Autonomous System Number, to which the true IP belongs

Custom Parameters

Custom parameter(s) - written as a regex
See Regular Expressions for details on regex syntax.

Header

Exact header name and expected header value(s)

  • The header name must be written in lower-case letters only.
  • The expected header value(s) must be written as a regex.

See Regular Expressions for details on regex syntax.

HTTP Method

The HTTP request method(s)

Actions include:

Action

Description

Allowlist

Allow access in any case

Denylist

Block access and display a CAPTCHA

HardBlock

Block with no CAPTCHA or option for exoneration.
Hard block is currently not supported on Fastly, Citrix and F5 Enforcers.

See here for more information.

Creating Custom Rules with API Calls

The Custom Rules API allows you to configure Allowlist and Denylist rules by using 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.

Header

Description

Authorization

Token to provide authentication

Content-Type

Value is always application/json

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

Parameter

Description

description

rule description

type

["none", "blacklist", "whitelist", "hardblock"]

conditions

list of conditions

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", "httpMethods", "header", "ipASN", "socketIpASN", "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", "name"]
                },
                "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, 2.2.2.2"},{"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,2.2.2.2"
        },
        {
          "category": "domain",
          "value": {
            "option": "exact",
            "value": "example.com"
          }
        }
      ]
    },
    "message": "success"
  }
Update custom rule by rule id

Parameters

Parameter

Description

rule_id
(query)

Rule ID.
This can be obtained from the Portal Policy section

description

rule description

type

["none", "blacklist", "whitelist", "hardblock"]

conditions

list of conditions

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", "httpMethods", "header", "ipASN", "socketIpASN", "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", "name"]
               },
                "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

Parameter

Description

rule_id

Rule ID. It can be obtained from portal policy view

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

Parameter

Description

rule_id

Rule ID. It can be obtained from portal policy view

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.

Status Code

Text

Description

400

Request object not valid

The request structure may be invalid

400

Invalid request

The request structure may be invalid

400

Invalid authorization Token

The Authorization header : Bearer is missing or invalid

400

Custom rule id does not exist

Custom rule id does not exist

400

Custom rule has invalid value

Custom rule id is not a valid UUID

400

Description field value is missing

Description has no value (mandatory field)

400

Type field value is missing

Type has no value (mandatory field)