Custom Rules
- 25 Oct 2024
- Print
- DarkLight
Custom Rules
- Updated on 25 Oct 2024
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
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.
Guidelines for Creating Custom Rules
- When creating a custom rule, make the logic as specific as possible.
- If the custom rule is to allow internal testing or other trusted traffic, we recommend to use an Access Token instead of a custom rule.
- If the custom rule is to allow a good bot, check first that there is not already an entry for that bot. For more information, see Known Bots and Crawlers.
- Rules that allow traffic based on the User Agent header only can be abused by attackers. If you'll try to create a rule that is potentially abusable, the system will alert you accordingly. For more information on abusable rules, see What are Abusable Policy Rules.
Creating Custom Rules on HUMAN Portal
- Within Bot Defender, navigate to Policies > Policy Settings.
- 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 HUMAN 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 | 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.
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.humansecurity.com/api/v1/custom_rules
Authentication
In order to access the HUMAN 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 HUMAN Portal (https://console.humansecurity.com/). For more information see Managing Applications .
Endpoints
Create custom rule
HTTP Method | Request URL |
|---|---|
POST |
Parameters
Parameter | Description | Required/ Optional |
|---|---|---|
description | rule description | Required |
type | ["none", "blacklist", "whitelist", "hardblock"] | Required |
conditions | list of conditions | Required |
| priority | integer (the priority of the rule) | Optional |
Setting Priority
As default, the rule priority will be set to lowest precedence. Alternatively, when a priority is assigned to an item on the list, the remaining items will be re-ranked accordingly, with their positions shifting down to accommodate the newly prioritized item.
Request Schema
{
"type": "object",
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"priority": {
"type": "integer"
},
"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"
]
"optional": [
"priority"
]
}
Request Example
curl -X POST
-H "Authorization: Bearer <JWT>"
-H "Content-Type: application/json"
-d '{
"priority": 23,
"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.humansecurity.com/api/v1/custom_rules"Response Schema
{
"type": "object",
"properties": {
"result": {
"type": "boolean"
},
"content": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"priority": {
"type": "integer"
},
"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",
"priority": 23,
"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 | https://console.humansecurity.com/api/v1/custom_rules/:rule_id |
Parameters
Parameter | Description | Required / Optional |
|---|---|---|
rule_id | Rule ID. | Required |
description | rule description | Required |
type | ["none", "blacklist", "whitelist", "hardblock"] | Required |
conditions | list of conditions | Required |
| priority | integer (the priority of the rule) | Optional |
Request Schema
{
"type": "object",
"properties": {
"priority": {
"type": "integer"
},
"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"
],
"optional": [
"priority"
]
}
Request Example
curl -X PUT
-H "Authorization: Bearer <JWT>"
-H "Content-Type: application/json"
-d '{
"priority": 23,
"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.humansecurity.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"
},
"priority": {
"type": "integer"
},
"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",
"priority": 23,
"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 | https://console.humansecurity.com/api/v1/custom_rules/: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.humansecurity.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 | https://console.humansecurity.com/api/v1/custom_rules/: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.humansecurity.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"
},
"priority": {
"type": "integer"
},
"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",
"priority": 1,
"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.humansecurity.com/api/v1/custom_rules"
Response Schema
{
"type": "object",
"properties": {
"result": {
"type": "boolean"
},
"content": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"priority": {
"type": "integer"
},
"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",
"priority": 1,
"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",
"priority": 2,
"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) |
Was this article helpful?