Global IP Blacklist REST Interface

Data

ip_range The blacklisted IP range (IPv4 / IPv6). This entry is normalized and always contains the netmask in short form.

ttl The time-to-life value in seconds. When ttl reaches zero, vWAF automatically deletes the entry from the global IP blacklist.

For more information regarding global IP blacklisting, see Global IP Blacklisting.

Getting a list of global IP blacklist entries

Request

Method	GET
URL	/blacklistedips/
Arguments	–

Response

Return code	Arguments	Meaning
200	[, , ...]	list successfully returned
401	-	no login
403	-	not enough rights
500	-	internal server error

Example

The following request retrieves a list of all globally blacklisted IP addresses.

$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/blacklistedips { "__name": "blacklistedips", "__path": "/api/af/2.0/blacklistedips/", "__subnodes": [ "::1-128", "127.0.0.1-32" ], "blacklist": [ { "ip_range": "127.0.0.1/32", "ttl": 6981 }, { "ip_range": "::1/128", "ttl": 300 } ] }

Getting a global IP blacklist entry

Request

Method	GET
URL	/blacklistedips/IPRANGE
Arguments	–

Response

Return code	Arguments	Meaning
200	{ ENTRY }	global IP blacklist entry successfully returned
401	-	no login
403	-	not enough rights
404	-	global IP blacklist entry not found
500	-	internal server error

Examples

The following request retrieves the values of the blacklisted IP address "127.0.0.1".

$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/blacklistedips/127.0.0.1 { "__name": "127.0.0.1", "__path": "/api/af/2.0/blacklistedips/127.0.0.1/", "__subnodes": [], "ip_range": "127.0.0.1/32", "ttl": 7200 }

The following request retrieves the values of the blacklisted IP address "::1/128". A slash can't be part of an object name, so it must be replaced by a hyphen within the URL.

$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/blacklistedips/::1-128 { "__name": "::1-128", "__path": "/api/af/2.0/blacklistedips/::1-128/", "__subnodes": [], "ip_range": "::1/128", "ttl": 300 }

Adding one or multiple global IP blacklist entries

Request

Method	POST
URL	/blacklistedips/
Arguments	{ 'ip_range' : ip_range, 'ttl' : ttl } or: { 'ip_range_list' : [{'ip_range': ip_range, 'ttl' : ttl}, …]}

Response

Return code	Arguments	Meaning
200	-	new global IP blacklist entry successfully added
401	-	no login
403	-	not enough rights
409	-	malformed, conflicting, or missing data
500	-	internal server error

Examples

The following request creates a global IP blacklist entry for the IP address "127.0.0.1" with a ttl of "300". As a result, the old blacklist entry is returned. T0he fact that the returned ttl is larger than 300 is due to the fact that for the given IP address there had already existed an IP blacklist entry with a larger ttl.

$ curl -u admin:admin -H 'Content-Type: application/json' --data '{"ip_range":"127.0.0.1", "ttl": 300}' http://127.0.0.1:8087/api/af/2.0/blacklistedips { "__name": "127.0.0.1", "__path": "/api/af/2.0/blacklistedips/127.0.0.1/", "__subnodes": [], "ip_range": "127.0.0.1/32", "ttl": 6981 }

The following request adds a global IP blacklist entry for the IPv6 address "2a01:4f8:130:8421::145" with a ttl of 300.

$ curl -u admin:admin -H 'Content-Type: application/json' --data '{"ip_range":"::1", "ttl": 300}' http://2a01:4f8:130:8421::145/api/af/2.0/blacklistedips { "__name": "::1", "__path": "/api/af/2.0/blacklistedips/::1/", "__subnodes": [], "ip_range": "::1/128", "ttl": 300 }

The following request adds a global IP blacklist entry for the IPv6 address "2a01:4f8:130:8421::145" with a ttl of 300.

If you want to add multiple entries to the blacklist, you can do so in one or several bulk operations. This is significantly faster than sending a separate request for each entry. We recommend using lists of about 100 to 200 entries each. If, for example, you want to add 1000 entries to the blacklist, instead of sending 1000 requests, send 10 requests, each consisting of a list of 100 entries.

The following example adds 4 entries to the global IP blacklist:

$ cat bulk_post.json { "ip_range_list" : [ {"ip_range" : "127.0.0.1", "ttl" : 3600}, {"ip_range" : "127.0.0.2", "ttl" : 3600}, {"ip_range" : "127.0.0.3", "ttl" : 3600}, {"ip_range" : "127.0.0.4", "ttl" : 3600} ] } $ curl -u admin:admin -X POST --data @bulk_post.json -H "Content-Type: application/json" http://localhost:8087/api/af/latest/blacklistedips/ { "__name": "blacklistedips", "__path": "/api/af/latest/blacklistedips/", "__subnodes": [ "127.0.0.1-32", "127.0.0.2-32", "127.0.0.3-32", "127.0.0.4-32", "excludedips" ], "blacklist": [ { "ip_range": "127.0.0.1/32", "ttl": 3600 }, { "ip_range": "127.0.0.2/32", "ttl": 3600 }, { "ip_range": "127.0.0.3/32", "ttl": 3600 }, { "ip_range": "127.0.0.4/32", "ttl": 3600 } ] }

Changing a global IP blacklist entry

Request

Method	PUT
URL	/blacklistedips/IPRANGE
Arguments	{ 'ttl' : ttl }

If the new ttl value is below the old one, the new value is ignored.

If you do a PUT request to a nonexistent ip_range, this ip_range entry is created with the given ttl.

Response

Return code	Arguments	Meaning
200	-	IP blacklist entry successfully modified
401	-	no login
403	-	not enough rights
409	-	malformed, conflicting, or missing data
500	-	internal server error

Example

The following request changes the ttl of a global IP blacklist entry to a value of "7200".

$ curl -X PUT -u admin:admin -H 'Content-Type: application/json' --data '{"ttl": 7200}' http://127.0.0.1:8087/api/af/2.0/blacklistedips/127.0.0.1 { "__name": "127.0.0.1", "__path": "/api/af/2.0/blacklistedips/127.0.0.1/", "__subnodes": [], "ip_range": "127.0.0.1/32", "ttl": 7200 }

Deleting a global IP blacklist entry

Request

Method	DELETE
URL	/blacklistedips/IPRANGE
Arguments	–

Response

Return code	Arguments	Meaning
200	-	IP blacklist entry successfully deleted
401	-	no login
403	-	not enough rights
404	-	IP blacklist entry not found
500	-	internal server error

Example

The following request deletes the global IP blacklist entry of the IP address "::1/128."

$ curl -X DELETE -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/blacklistedips/::1-128 {}

Managing ranges of excluded IP addresses

You can also manage ranges of IP addresses that are excluded from the global IP blacklist via the REST interface. To do so, you can reach the list of excluded IP addresses via api/af/2.0/blacklistedips/excludedips/.

Example: Getting a list of excluded IP address ranges

GET http://localhost:8087/api/af/2.0/blacklistedips/excludedips {    "__name": "excludedips",    "__path": "/api/af/2.0/blacklistedips/excludedips/",    "__subnodes": [        "10.10.2.10-32",        "10.0.0.0-8",        "1.2.3.4-32"    ],    "whitelist": [        { "ip_range": "1.2.3.4/32" },        { "ip_range": "10.10.2.10/32" },        { "ip_range": "10.0.0.0/8" }    ] }

Example: Checking data for one IP address range

GET http://localhost:8087/api/af/2.0/blacklistedips/excludedips/{IPRANGE} Note that IPRANGE in the URL is written in the form IP-prefixlength, not in the form IP/prefixlength. curl example: curl -u admin:admin \    http://localhost:8087/api/af/2.0/blacklistedips/excludedips/1.2.3.4-32 {    "__name": "1.2.3.4-32",    "__path": "/api/af/2.0/blacklistedips/excludedips/1.2.3.4-32/",    "__subnodes": [],    "__type": "WhitelistedIPObject",    "ip_range": "1.2.3.4/32" }

Example: Adding a range of excluded IP addresses

POST a JSON object with ip_range set to the range of IP addresses that you want to add to the list of excluded IP addresses.

curl example:

$ curl -u admin:admin -H "Content-Type: application/json" \    -data '{"ip_range": "192.168.0.0/16"}' \    http:/localhost:8087/api/af/2.0/blacklistedips/excludedips {    "__name": "192.168.0.0-16",    "__path": "/api/af/2.0/blacklistedips/excludedips/192.168.0.0-16/",    "__subnodes": [],    "ip_range": "192.168.0.0/16" }

Example: Deleting a range of excluded IP addresses

$ curl -u admin:admin -H "Content-Type: application/json" \    -data '{"ip_range": "192.168.0.0/16"}' \    http:/localhost:8087/api/af/2.0/blacklistedips/excludedips {    "__name": "192.168.0.0-16",    "__path": "/api/af/2.0/blacklistedips/excludedips/192.168.0.0-16/",    "__subnodes": [],    "ip_range": "192.168.0.0/16" }

Note that IPRANGE in the URL is written in the form IP-prefixlength, not in the form IP/prefixlength.

curl example:

curl -X DELETE -u admin:admin \    http://localhost:8087/api/af/2.0/blacklistedips/excludedips/192.168.0.0-16 {}