IP address graylist¶

Graylist is a list of suspicious IP addresses processed by the node only in the safe blocking filtration mode as follows: if graylisted IP originates malicious requests, the node blocks them while allowing legitimate requests.

Malicious requests originating from graylisted IPs are those containing the signs of the following attacks:

• Input validation attacks

• Attacks of the vpatch type

• Attacks detected based on regular expressions

In contrast to graylist, denylist points to IP addresses that are not allowed to reach your applications at all - the node blocks even legitimate traffic produced by denylisted sources. IP graylisting is one of the options aimed at the reduction of false positives.

Behavior of the filtering node may differ if graylisted IP addresses are also allowlisted, more about list priorities.

In Wallarm Console → IP lists → Graylist, you can manage graylisted IP addresses as follows:

• Add a single IP address or a subnet

• Add a group of IP addresses registered in a specific country/region, data center, network, etc.

• Customize the time and reason for storing the IP address in the list

• Delete IP address from the list

• Review the history of list changes

Examples of IP graylist usage¶

• Graylist IP addresses from which several consecutive attacks originated.

  An attack may include several requests originating from one IP address and containing malicious payloads of different types. One of the methods to block most of the malicious requests and allow legitimate requests originated from this IP address is to graylist this IP. You can configure automatic source IP graylisting by configuring the threshold for source IP graylisting and appropriate reaction in the trigger.

  Source IP graylisting can significantly reduce the number of false positives.

• Graylist IP addresses, countries, regions, data centers, networks (for example, Tor) that usually produce harmful traffic. The Wallarm node will allow legitimate requests produced by graylisted objects and block malicious requests.

Adding an object to the list¶

You can both enable Wallarm to graylist IP addresses automatically if they produce some suspicious traffic as well as graylist objects manually.

Automatic graylist population (recommended)¶

The triggers functionality enables automatic graylisting of IPs by the following conditions:

• Malicious requests of the following types: Brute force, Forced browsing, BOLA.

• Number of malicious payloads produced by an IP.

• New company accounts are featured with the pre-configured (default) trigger graylisting an IP when it originates more than 3 different malicious payloads within 1 hour.

Triggers having the Graylist IP address reaction to the listed events automatically graylist IPs for a specified timeframe. You can configure triggers in Wallarm Console → Triggers.

Manual graylist population¶

To add an IP address, subnet, or group of IP addresses to the list manually:

1. Open Wallarm Console → IP lists → Graylist and click Add object.

2. Specify an IP address or group of IP addresses in one of the following ways:

   • Input a single IP address or a subnet

     Supported subnet masks

     The supported maximum subnet mask is /32 for IPv6 addresses and /12 for IPv4 addresses.

   • Select a country or a region (geolocation) to add all IP addresses registered in this country or region

   • Select the source type to add all IP addresses that belong to this type, e.g.:
     • Tor for IP addresses of the Tor network
     • Proxy for IP addresses of public or web proxy servers
     • Search Engine Spiders for IP addresses of search engine spiders
     • VPN for IP addresses of virtual private networks
     • AWS for IP addresses registered in Amazon AWS

3. Select the applications to which you allow or restrict access for the specified IP addresses.

4. Select the period for which an IP address or a group of IP addresses should be added to the list. The minimum value is 5 minutes, the maximum value is forever.

5. Specify the reason for adding an IP address or a group of IP addresses to the list.

Automatic bots' IPs graylisting¶

The Wallarm's API Abuse Prevention module also automatically populates either the graylist or denylist with the malicious bots' IPs.

Bots' IPs are distinguished by the Bot Reason and the details on its nature including the confidence rate, e.g.:

Analyzing objects added to the list¶

Wallarm Console displays the following data on each object added to the list:

• Object - IP address, subnet, country/region or IP source added to the list.

• Application - application to which access configuration of the object is applied.

• Source - source of a single IP address or subnet:

  • The country/region where a single IP address or subnet is registered (if it was found in the databases like IP2Location or others)
  • The source type, like Public proxy, Web proxy, Tor or the cloud platform the IP registered in, etc (if it was found in the databases like IP2Location or others)

• Reason - reason for adding an IP address or a group of IP addresses to the list. The reason is manually specified when adding objects to the list or automatically generated when IPs are added to the list by triggers.

• Adding date - date and time when an object was added to the list.

• Remove - time period after which an object will be deleted from the list.

Filtering the list¶

You can filter the objects in the list by:

• IP address or subnet specified in the search string

• Period for which you want to get a status of the list

• Country/region in which an IP address or a subnet is registered

• Source to which an IP address or a subnet belongs

Changing the time that an object is on the list¶

To change the time that an IP address is on the list:

1. Select an object from the list.

2. In the selected object menu, click Change time period.

3. Select a new date for removing an object from the list and confirm the action.

Deleting an object from the list¶

To delete an object from the list:

1. Select one or several objects from the list.

2. Click Delete.

API calls to get, populate and delete IP list objects¶

To get, populate and delete IP list objects, you can call the Wallarm API directly besides using the Wallarm Console UI. Below are some examples of the corresponding API calls.

API request parameters¶

Parameters to be passed in the API requests to read and change IP lists:

Add to the list the entries from the .csv file¶

To add to the list the IPs or subnets from the .csv file, use the following bash script:

#!/bin/bash

UUID="<YOUR_UUID>"
SECRET="<YOUR_SECRET_KEY>"
CLIENT="<YOUR_CLIENT_ID>"
LIST="<TYPE_OF_IP_LIST>"
PATH_TO_CSV_FILE="<PATH_TO_CSV_FILE>" # path to the CSV file with IPs or subnets
APPLICATIONS="<APP_IDS_THROUGH_COMMA>"
REMOVE_DATE="TIMESTAMP_REMOVE_DATE"
REASON='<REASON>'
API="us1.api.wallarm.com"


index=0
while read line; do
    subnets[$index]="$line"
    index=$(($index+1))
done < "$PATH_TO_CSV_FILE"


for i in ${subnets[@]}; do
    currentDate=`date -u +%s`
    time=$REMOVE_DATE
    remove_date=$(($currentDate+$time))

curl -X POST \
https://$API/v4/ip_rules \
-H "Content-Type: application/json" \
-H "X-WallarmApi-Token: <YOUR_TOKEN>"  \
-d '{
"clientid": '$CLIENT',
"ip_rule": {
    "list": "'$LIST'",
    "rule_type": "ip_range",
    "subnet": "'$i'",
    "expired_at": '$remove_date',
    "pools": [
        '$APPLICATIONS'
    ],
    "reason": "'"$REASON"'"
},
"force": false
}'

done

#!/bin/bash

UUID="<YOUR_UUID>"
SECRET="<YOUR_SECRET_KEY>"
CLIENT="<YOUR_CLIENT_ID>"
LIST="<TYPE_OF_IP_LIST>"
PATH_TO_CSV_FILE="<PATH_TO_CSV_FILE>" # path to the CSV file with IPs or subnets
APPLICATIONS="<APP_IDS_THROUGH_COMMA>"
REMOVE_DATE="TIMESTAMP_REMOVE_DATE"
REASON='<REASON>'
API="api.wallarm.com"


index=0
while read line; do
    subnets[$index]="$line"
    index=$(($index+1))
done < "$PATH_TO_CSV_FILE"


for i in ${subnets[@]}; do
    currentDate=`date -u +%s`
    time=$REMOVE_DATE
    remove_date=$(($currentDate+$time))

curl -X POST \
https://$API/v4/ip_rules \
-H "Content-Type: application/json" \
-H "X-WallarmApi-Token: <YOUR_TOKEN>"  \
-d '{
"clientid": '$CLIENT',
"ip_rule": {
    "list": "'$LIST'",
    "rule_type": "ip_range",
    "subnet": "'$i'",
    "expired_at": '$remove_date',
    "pools": [
        '$APPLICATIONS'
    ],
    "reason": "'"$REASON"'"
},
"force": false
}'

done

Add to the list a single IP or subnet¶

To add particular IPs or subnets to the IP list, send the following request for each IP/subnet:

curl 'https://us1.api.wallarm.com/v4/ip_rules' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"clientid":<YOUR_CLIENT_ID>,"force":false,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>","pools":[<ARRAY_OF_APP_IDS>],"expired_at":<TIMESTAMP_REMOVE_DATE>,"rule_type":"ip_range","subnet":"<IP_OR_SUBNET>"}}'

curl 'https://api.wallarm.com/v4/ip_rules' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"clientid":<YOUR_CLIENT_ID>,"force":false,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>","pools":[<ARRAY_OF_APP_IDS>],"expired_at":<TIMESTAMP_REMOVE_DATE>,"rule_type":"ip_range","subnet":"<IP_OR_SUBNET>"}}'

Add to the list multiple countries¶

curl 'https://us1.api.wallarm.com/v4/ip_rules' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"country","source_values":[<ARRAY_OF_COUNTRIES_REGIONS>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'

curl 'https://api.wallarm.com/v4/ip_rules' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"country","source_values":[<ARRAY_OF_COUNTRIES_REGIONS>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'

Add to the list multiple proxy services¶

curl 'https://us1.api.wallarm.com/v4/ip_rules' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"proxy_type","source_values":[<ARRAY_OF_PROXY_SERVICES>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'

curl 'https://api.wallarm.com/v4/ip_rules' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"proxy_type","source_values":[<ARRAY_OF_PROXY_SERVICES>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'

Delete an object from the IP list¶

Objects are deleted from IP lists by their IDs.

To get an object ID, request the IP list contents and copy objects.id of the required object from a response:

curl 'https://us1.api.wallarm.com/v4/ip_rules?filter%5Bclientid%5D=<YOUR_CLIENT_ID>&filter%5Blist%5D=<TYPE_OF_IP_LIST>&offset=0&limit=50' \
      -H 'X-WallarmApi-Token: <YOUR_TOKEN>'

curl 'https://api.wallarm.com/v4/ip_rules?filter%5Bclientid%5D=<YOUR_CLIENT_ID>&filter%5Blist%5D=<TYPE_OF_IP_LIST>&offset=0&limit=50' \
      -H 'X-WallarmApi-Token: <YOUR_TOKEN>'

Having the object ID, send the following request to delete it from the list:

curl 'https://us1.api.wallarm.com/v4/ip_rules' \
  -X 'DELETE' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"filter":{"clientid":<YOUR_CLIENT_ID>,"id":[<OBJECT_ID_TO_DELETE>]}}'

curl 'https://api.wallarm.com/v4/ip_rules' \
  -X 'DELETE' \
  -H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"filter":{"clientid":<YOUR_CLIENT_ID>,"id":[<OBJECT_ID_TO_DELETE>]}}'

You can delete multiple objects at once passing their IDs as an array in the deletion request.