Using API calls allows you to configure request processing rules.
Settings are managed using specially designed queries. The general conventions (authorization, response codes, the *_hash methods and paginated selection) are described in the relevant section.
The general rules for writing the value of a host apply to the host and host_x options, taking into account the following features:
Base64 format.Examples of the value (before encoding to Base64):
example.com
*.example.com
10.10.10.1
[fe80:0:0:0:200:f8ff:fe21:67cf]
The query processing rules mechanism allows you to use additional conditions for a more accurate result. For example, you can create a rule according to which a request will be blocked or unblocked if:
user-agent, cookie, referer, etc.) and/or the contents of these headers, as well as their absence.For a more accurate result, the parameters can be combined with each other. In this case, the rule will only work if all the conditions are met.
Request example:
curl http://api.example.com:8080/filter/v1/get_erl --header 'Content-type: application/json' --data '{"key": "%PRODUCT KEY%"}'
Response format:
{
"status": "success",
"erl": [
{
"active": boolean,
"timestamp": integer,
"id": integer,
"comment": string,
"method": string,
"host": string,
"host_x": string,
"port": string,
"path": string,
"path_x": string,
"query": string,
"query_x": string,
"ip": string,
"body": string,
"body_x": string,
"user-agent": string,
"user-agent_x": string,
"no_user-agent": boolean,
"cookie": string,
"cookie_x": string,
"no_cookie": boolean,
"referer": string,
"referer_x": string,
"no_referer": boolean,
"other_headers": array,
"other_headers_x": array,
"cc": string,
"block_tor": boolean,
"block_proxy": boolean,
"zone_max_size": object,
"api": boolean,
"dm": boolean,
"noban": boolean,
"mla": boolean,
"wl": boolean,
"wl_data": array
}
]
}
or (in the case where data is missing)
{"status": "none"}
or (in case of an error)
{"status": "fail", "description": "%DESCRIPTION%"}
Response example:
{
"status": "success",
"erl": [
{
"active": true,
"timestamp": 1730973337,
"id": 100048,
"comment": "my rule",
"method": "UE9TVA==",
"host": "XHcuZXhhbXBsZS5jb20=",
"host_x": "XHcuZXhhbXBsZS5jb20=",
"port": "80",
"path": "L3VzZXJzL2xvZ2luLnBocA==",
"path_x": "W2EtekEtWjAtOV0=",
"query": "VVJM",
"query_x": "W2EtekEtWjAtOV0=",
"ip": "10.10.10.1",
"body": "c29tZV90ZXh0",
"body_x": "W2EtekEtWjAtOV0=",
"user-agent": "TW96aWxsYSA1LzA=",
"user-agent_x": "W2EtekEtWjAtOV0=",
"no_user-agent": false,
"cookie": "aWQ9YW5ubWszNDU0R2Fmbmo2",
"cookie_x": "W2EtekEtWjAtOV0=",
"no_cookie": true,
"referer": "aHR0cDovL2V4YW1wbGUuY29t",
"referer_x": "W2EtekEtWjAtOV0=",
"no_referer": true,
"other_headers": ["dXNlcl9JRA==:|YWRtaW4=|YWRtaW5pc3RyYXRvcg=="],
"other_headers_x": ["dXNlcl9JRA==:|YWRtaW4=|YWRtaW5pc3RyYXRvcg=="],
"cc": "|Q0g=|VVM=",
"block_tor": true,
"block_proxy": false,
"zone_max_size": {"path": 1024, "query": 1024, "body": 2048},
"api": false,
"dm": false,
"noban": true,
"mla": true,
"wl": true,
"wl_data": [{"*": ["body"]}]
}
]
}
active - if the value is false, the settings are deactivated;timestamp - the date of the last configuration change in the Unix Timestamp format.Due to the query processing features, the functionality is not designed to work with a large number of IP addresses. If you need to block requests for a list of IP addresses, use the functionality to add an IP address to the Block list.
Request example:
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"comment": "my rule",
"ip": "10.10.10.1",
"dm": true,
"user-agent": "TW96aWxsYSA1LzA=",
"user-agent_x": "W2EtekEtWjAtOV0=",
"api": true,
"path": "L3VzZXJzL2xvZ2luLnBocA==",
"path_x": "W2EtekEtWjAtOV0=",
"query": "VVJM",
"query_x": "W2EtekEtWjAtOV0=",
"body": "c29tZV90ZXh0",
"body_x": "W2EtekEtWjAtOV0=",
"noban": true,
"mla": true,
"cookie": "aWQ9YW5ubWszNDU0R2Fmbmo2|aWQ9YW5ubWszNGZuYWpjNg==",
"cookie_x": "dXNlcj1bYS16LUEtWjAtOV0=",
"method": "UE9TVA==",
"host": "XHcuZXhhbXBsZS5jb20=",
"host_x": "XHcuZXhhbXBsZS5jb20=",
"port": "80",
"cc": "|Q0g=|VVM=",
"referer": "aHR0cDovL2V4YW1wbGUuY29t",
"referer_x": "W2EtekEtWjAtOV0=",
"block_tor": true,
"no_cookie": false,
"no_user-agent": true,
"no_referer": false,
"block_proxy": true,
"other_headers": ["dXNlcl9JRA==:|YWRtaW4=|YWRtaW5pc3RyYXRvcg=="],
"other_headers_x": ["dXNlcl9JRA==:|YWRtaW4=|YWRtaW5pc3RyYXRvcg=="],
"zone_max_size": {"path": 1024, "query": 1024, "body": 2048},
"wl": true,
"wl_data": [{"*": ["body"]}, {"1": ["$mfd:dGVzdA=="]}],
"exclude_from_body": ["dGVzdA==", {"$mfd": ["dGVzdA=="]}, {"$json": ["dGVzdA=="]}],
"exclude_from_body_x": ["W2EtekEtWjAtOV0=", {"$mfd": ["dGVzdA=="]}, {"$json": ["dGVzdA=="]}]
}
}'
Examples:
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"ip": "|10.10.10.1",
"host": "|XHcuZXhhbXBsZS5jb20=",
"other_headers": ["dGVzdC1oZWFkZXI=:YWJj"]
}
}'
The request will be blocked by the rule if on example.com a request will be received from the IP address 10.10.10.1 and the test-header header contains the string abc.
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"cc": "|VVM=|Q0g=",
"host": "|XHcuZXhhbXBsZS5jb20=",
"other_headers": ["dGVzdC1oZWFkZXI=:YWJj"],
"cookie": "|!dGVzdF9jb29raWU=",
"referer": "|!aHR0cDovL2V4YW1wbGUuY29t"
}
}'
The request will be blocked by the rule if on example.com a request is received from an IP address located in US or CH (VVM= and Q0g= in Base64), the test-header header contains the string abc, the cookie header does not contain the string test_cookie and the referer header does not contain http://example.com.
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"ip": "|10.10.10.1",
"other_headers": ["VGVzdC1GaWVsZA==:"],
"referer": "|aHR0cDovL2V4YW1wbGUuY29tLw==",
"user-agent": "|TW96aWxsYS81LjA=",
"cookie": "|dGVzdF9jb29raWU=",
"body": "|YmM9MyZjYz0x",
"query": "|P3BhZ2U9Mw==",
"host": "|XHcuZXhhbXBsZS5jb20=",
"api": false
}
}'
The request will be blocked by the rule if on example.com a request will be received from the IP address 10.10.10.1, which will contain:
referer header with the contents http://example.com/;test-field header with any content;user-agent header with the content Mozilla/5.0;cookie header with the content test_cookie;bc=3&cc=1;?page=3.curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"host": "|XHcuZXhhbXBsZS5jb20=",
"ip": "|10.10.10.1",
"referer": "|aHR0cDovL2V4YW1wbGUuY29tLw==",
"zone_max_size": {"body": 2048}
}
}'
The request will be blocked by the rule if on example.com a request will be received from the IP address 10.10.10.1, which will contain:
referer header with the contents http://example.com/;curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"ip": "|10.10.10.1",
"user-agent": "|TW96aWxsYS81LjA=",
"cookie": "|dGVzdF9jb29raWU=",
"host": "|XHcuZXhhbXBsZS5jb20=",
"wl": true
}
}'
The request will not be blocked by the rule, even if it contains signs of an attack, if a request is received on example.com from the IP address 10.10.10.1 and contains:
user-agent header with the content Mozilla/5.0;cookie header with the content test_cookie.curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"ip": "|10.10.10.1",
"host": "|XHcuZXhhbXBsZS5jb20=",
"wl": true,
"wl_data": [{"*": ["body"]}]
}
}'
The request will not be blocked when any signature is triggered in the request body, if the request is received on example.com from the IP address 10.10.10.1.
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"add": {
"active": true,
"ip": "|10.10.10.1",
"host": "|XHcuZXhhbXBsZS5jb20=",
"wl": true,
"wl_data": [{"*": ["$mfd:dGVzdA=="]}]
}
}'
The request will not be blocked when any signature is triggered in the request data transmitted using multipart/form-data if the request is received by example.com from the IP address 10.10.10.1.
Response example:
{"status": "success", "id": 100053}
or (in case of an error)
{"status": "fail", "description": "%DESCRIPTION%"}
|
For all parameters (except for parameters that support the values The default values of the parameters: When creating a rule, at least one non-empty parameter is required from the list: When checking whether the request processing rule is triggered, all fields except For example, with The rule is triggered only if all the conditions specified in the rule are met, otherwise the request will be skipped. |
The activity of the rule. If the value is false, the rule is not applied. If this option is omitted, the default value is true.
"active": true
The IP address of the attacker, from which the rule will be applied to the request.
IPv4/IPv6 addresses, CIDR (for example, 10.10.10.1/24) an IP address range are allowed.
"ip": "|10.10.10.1|2.2.2.2-3.3.3.3|10.0.0.0/24"
The country from which the request was received, determined based on IP geolocation data and specified as a two-letter ISO 3166-1 alpha-2 country code. For example, with the value US, the rule will be applied to requests from IP addresses located in the United States.
The value for the option is passed in the Base64 format (GB and US in the example below).
"cc": "|R0I=|VVM="
The method used when sending the HTTP request.
The value for the option is passed in the Base64 format.
"method": "UE9TVA==|R0VU"
The host that the rule will be applied to.
The general rule for writing values applies to the option.
"host": "XHcuZXhhbXBsZS5jb20=|ZXhhbXBsZS51cw=="
The host in the regular expression format that the rule will be applied to when accessing.
The general rule for writing values applies to the option.
The value for the option is passed in the Base64 format (\w.example.com and \w.example.uk in the example below).
"host_x": "|XHcuZXhhbXBsZS5jb20=|XHcuZXhhbXBsZS51cwo="
The port or the range of ports that the rule will be applied to when accessing.
"port": "80|443"
The occurrence of a string in the contents of the PATH zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"path": "|aW50ZXJuYWx0ZXN0|YWRtaW4vdXBsb2FkLnBocA=="
The occurrence of a string based on a regular expression in the contents of the PATH zone, at which the rule will be applied to the query.
The value for the option is passed in the Base64 format.
"path_x": "|W2EtekEtWjAtOV0=|W2EtekEtWjAtOV0="
The occurrence of a string in the contents of the QUERY zone, for which the rule will be applied.
The value for the option is passed in the Base64 format.
"query": "|P3BhZ2U9Mw==|dXNlcj1hZG1pbg=="
The occurrence of a string based on a regular expression in the contents of the QUERY zone, for which the rule will be applied.
The value for the option is passed in the Base64 format.
"query_x": "|W2EtekEtWjAtOV0=|W2EtekEtWjAtOV0="
The occurrence of a string in the contents of the BODY zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"body": "|dGVzdF9ib2R5|dXNlcj1hZG1pbg=="
The occurrence of a string based on a regular expression in the contents of the BODY zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"body_x": "|W2EtekEtWjAtOV0=|W2EtekEtWjAtOV0="
The occurrence of a string in the contents of the Cookie zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"cookie": "|UEhQU0VTU0lE|dGVzdF9jb29raWU="
To apply the rule correctly, it is forbidden to use the cookie, cookie_x and no_cookie options at the same time.
The occurrence of a string based on a regular expression in the contents of the Cookie zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"cookie_x": "|W2EtekEtWjAtOV0=|W2EtekEtWjAtOV0="
With the value true, the rule applies only to a request with an empty Cookie zone.
"no_cookie": true
To apply the rule correctly, it is forbidden to use the cookie/cookie_x and no_cookie options at the same time.
The occurrence of a string in the contents of the User-Agent zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"user-agent": "|TW96aWxsYS81LjA=|TW96aWxsYS81LjQ="
To apply the rule correctly, it is forbidden to use the user-agent/user-agent_x and no_user-agent options at the same time.
The occurrence of a string based on a regular expression in the contents of the User-Agent zone, for which the rule will be applied.
The value for the option is passed in the Base64 format.
"user-agent_x": "|W2EtekEtWjAtOV0=|W2EtekEtWjAtOV0="
With the value true, the rule applies only to a query with an empty User-Agent zone.
"no_user-agent": true
To apply the rule correctly, it is forbidden to use the user-agent/user-agent_x and no_user-agent options at the same time.
The occurrence of a string in the contents of the Referer zone, at which the rule will be applied.
The value for the option is passed in the Base64 format.
"referer": "|aHR0cDovL2V4YW1wbGUuY29t|aHR0cDovL3dlYi5leGFtcGxlLmNvbQ=="
To apply the rule correctly, it is forbidden to use the referer/referer_x and no_referer options at the same time.
The occurrence of a string based on a regular expression in the contents of the Referer zone, for which the rule will be applied.
The value for the option is passed in the Base64 format.
"referer_x": "|W2EtekEtWjAtOV0=|W2EtekEtWjAtOV0="
With the value true, the rule applies only to a query with an empty Referer zone.
"no_referer": true
To apply the rule correctly, it is forbidden to use the referer/referer_x and no_referer options at the same time.
The occurrence of a string in the contents of the HEADERS zone, with the exception of the Cookie, User-Agent and Referer zones, in which the rule will be applied.
For the other_headers option, the contents of the header_name and header_value sections are optional, but at least one of the sections must be specified. For example, if there is a header_name header, the contents of the header_value header will be checked only for the header_name header if there is no header, the contents of all headers will be checked.
All the elements of the list interact with each other according to the principle of logical "and" (&). Nesting of arrays of no more than 3 levels is allowed; empty nested arrays are not allowed. The name of the header cannot contain the operators !, & and |.
If header_name is set without header_value, then the rule will be applied at any value of the header_name header (blocking by the presence of the header).
The value for the option is passed in the Base64 format.
More detailed information is available in the KB.
"other_headers": [
"aGVhZGVyX25hbWU=:",
"dGVzdC1oZWFkZXI=:YWJj"
]
The occurrence of a string based on a regular expression in the contents of the HEADERS zone, with the exception of the Cookie, User-Agent and Referer zones, in which the rule will be applied.
For the other_headers option, the contents of the header_name and header_value sections are optional, but at least one of the sections must be specified. For example, if there is a header_name header, the contents of the header_value header will be checked only for the header_name header if there is no header, the contents of all headers will be checked.
All the elements of the list interact with each other according to the principle of logical "and" (&).
If header_name is set without header_value, then the rule will be applied at any value of the header_name header (blocking by the presence of the header).
The values of the header name and header content are transmitted in the Base64 format.
More detailed information is available in the KB.
"other_headers_x": [
"aGVhZGVyX25hbWU=:",
"dGVzdC1oZWFkZXI=:YWJj"
]
This option activates the rule for IP addresses that are the exit node of the Tor network.
It can be used without other options.
"block_tor": true
The option activates the rule for IP addresses that belong to a Proxy/VPN service or are an exit node of the Tor network.
It can be used without other options.
"block_proxy": true
This option activates the rule if values larger than the allowed size in bytes are transmitted in the specified zone.
The restrictions set for several zones are applied according to the principle of logical "OR". In other words, the option will work if the size of the transmitted data is exceeded for at least one of the listed zones.
When setting the maximum allowed size for the other_headers zone, all headers related to Other_headers are taken into account when calculating the amount of transmitted data (for example: host, accept, content-type, content-length, etc.).
Setting the maximum allowed size for the User-Agent, Cookie Referer zones simultaneously with using the no_cookie, no_user-agent no_referer options will make it impossible for the rule to trigger due to conflicting conditions.
It can be used without other options.
"zone_max_size": {"path": 1024, "query": 1024, "body": 2048}
With the value true, the rule trigger will be added to the attack report.
Does not apply when using the wl option with the true value.
"api": true
With the value true, rule triggers are recorded in logs, but not blocked (detection mode).
Does not apply when using the wl option with the true value.
"dm": true
With the value true, triggering the rule will not affect the automatic blocking of the IP address.
Does not apply when using the wl option with the true value.
"noban": true
With the value true, triggering the rule will send the request to MLA for additional analysis.
Does not apply when using the wl option with the true value.
"mla": true
With the value true, triggering the rule will not block the request, even if there are signs of an attack in the request. If this option is omitted, the default value is false.
It is not allowed to use the option with the value true together with dm, exclude_from_body and exclude_from_body_x. When downloading the rules, the dm, mla, api, noban, exclude_from_body and exclude_from_body_x parameters are not returned for the rules with "wl": true the wl_data parameter is not returned for the rules with "wl": false.
"wl": true
This option deactivates the signature in the corresponding zone: path (path to the resource), query (request arguments), body (request body), headers (request headers), cookie (cookie header), user-agent (user-agent header), referer (referer header), $header:%custom-header-name% (a specific request header, for example, $header:x-forwarded-for), $nomla, $mfd:%b64(field-name)%.
To deactivate signature activation, you must specify its identifier (or the identifier of the created request processing rule). With the value *, any signature used for request analysis will be deactivated.
Using the same zone more than once in the list is not allowed.
When using the zone value $nomla, triggering the signature will not affect sending a request to the MLA machine learning module for additional analysis, regardless of which zone it was detected in. If the zone is used in conjunction with other zones (path, query, etc.), then triggering the signature will not affect sending the request to the MLA machine learning module if the signature was detected only in the listed zones.
When using the zone value $mfd, the activation of the signature in the data transmitted using multipart/form-data is deactivated. As a value, you must specify (in the Base64 format) the field name of that part of the multipart body of the HTTP request, the data of which should be excluded from the analysis for the presence of a signature.
The option can only be used in conjunction with the wl option with the value true.
At least one zone must be selected when using the option.
"wl_data": [{"*": ["body"]}, {"1": ["query", "$nomla"]}, {"*": ["$mfd:dXNlcm5hbWU="]}]
{"*": ["$mfd:base64(username)"]} this means that for the contents of the field named username, any signature will be excluded if the data was transmitted using multipart/form-data.
This option allows you to set a comment for the rule being created.
"comment": "my rule"
The occurrence of a string in the content of the BODY zone, which is excluded from the query analysis.
The value for the option is passed in the Base64 format.
It does not act on requests sent for analysis to the API Firewall and antivirus software.
"exclude_from_body": ["dGVzdA==", {"$mfd": ["dGVzdA=="]}, {"$json": ["dGVzdA=="]}]
"base64(test)" means that when analyzing for signs of an attack, the occurrence of the test sequence will be excluded from the contents of the request body, regardless of its location.
{"$mfd": ["base64(username)"]} this means that when transmitting data using multipart/form-data, all data of the form with the name username will be excluded from analysis.
{"$json": ["base64(username)"]} this means that when transmitting data in JSON format, all data for the key named username will be excluded from analysis. If the contents of the username key are represented as a JSON object (nested structure), the analysis will be deactivated for the entire object. If it is necessary to deactivate the analysis for a specific key inside the JSON structure, then you must specify the full path to this key, according to the structure of the JSON object, for example:
{"$json": ["base64(users):base64(id):base64(username)"]} will match the structure:
{
"users": {
"id": {
"username": "admin"
}
}
}
In this case, the analysis will be deactivated only for the contents of the username key.
The occurrence of a string based on a regular expression in the contents of the BODY zone, which is excluded from the request analysis.
The value for the option is passed in the Base64 format.
Does not apply to requests sent for analysis to the API Firewall and antivirus software.
"exclude_from_body_x": ["W2EtekEtWjAtOV0=", {"$mfd": ["W2EtekEtWjAtOV0="]}, {"$json": ["W2EtekEtWjAtOV0="]}]
"base64([a-zA-Z0-9])" means that when analyzing for signs of an attack, any occurrence matching the regular expression [a-zA-Z0-9] will be excluded from the contents of the request body, regardless of its location.
{"$mfd": ["base64([a-zA-Z0-9])"]} means that when transmitting data using multipart/form-data, the data of any form whose name matches the regular expression will be excluded from analysis.
{"$json": ["base64(username)"]} this means that when transmitting data in JSON format, all data for the key named username will be excluded from analysis. If the contents of the username key are represented as a JSON object (nested structure), the analysis will be deactivated for the entire object. If it is necessary to deactivate the analysis for a specific key inside the JSON structure, then you must specify the full path to this key, according to the structure of the JSON object, for example:
{"$json": ["base64(users):base64(id):base64(username)"]} will match the structure:
{
"users": {
"id": {
"username": "admin"
}
}
}
In this case, the analysis will be deactivated only for the contents of the username key.
Request example:
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"upd": {
"active": true,
"id": 1,
"ip": "|10.10.10.1"
}
}'
Response example:
{"status": "success"}
or (in case of an error)
{"status": "fail", "description": "%DESCRIPTION%"}
The method allows you to check whether the data has changed without downloading it in full. More detailed information is available in the relevant section.
Request example:
curl http://api.example.com:8080/filter/v1/get_erl_hash --header 'Content-type: application/json' --data '{"key": "%PRODUCT KEY%"}'
Response example:
{"status": "success", "hash": "8ddd2b342d3190a866ee35afb249919a"}
or (in the case where data is missing)
{"status": "none"}
or (in case of an error)
{"status": "fail", "description": "%DESCRIPTION%"}
Request example:
curl http://api.example.com:8080/filter/v1/set_erl --header 'Content-type: application/json' --data '{
"key": "%PRODUCT KEY%",
"del": {
"id": 1
}
}'
Response example:
{"status": "success"}
or (in case of an error)
{"status": "fail", "description": "%DESCRIPTION%"}