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
- Navigate to Product Settings > Security Policy.
- Under Policy Name, select the required policy.
- Under Policy Rules, click Add custom rule.
- 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.
- Click AND if you want to add another category to the rule.
- Click Add Rule.
- Click Save Changes.
Category | Description |
|---|---|
User Agent | Full UA regex example: Partial UA regex example: 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. |
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 |
Header | Exact header name and expected header value(s)
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. 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
HTTP Method | Request URL |
|---|---|
POST |
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
HTTP Method | Request URL |
|---|---|
PUT |
Parameters
Parameter | Description |
|---|---|
rule_id | Rule ID. |
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
HTTP Method | Request URL |
|---|---|
DELETE |
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
HTTP Method | Request URL |
|---|---|
GET |
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
HTTP Method | Request URL |
|---|---|
GET |
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) |
Updated 21 days ago