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 [{ENTRY1}, {ENTRY2}, ...] 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 {}