Overview of the IP user list features

IP User-defined lists are lists of IP addresses and subnets that can be added to custom policies. The API service allows the creation, edit and deletion of lists - both their settings and the list of IP subnets.

User-defined IP lists can be added to both IP Policies (to block connections from and to the IP addresses in the list) and to DNS Policies (to block records resolving to the IP addresses). Subnets are supported by both policy types.

List types

IP lists have two possible types:

  • block lists, used to block connections from or to the IP address
  • allow lists, used to whitelist connections. Allow lists take precedence over block lists but require a device which supports whitelists.

List sharing

Lists can be shared with other ThreatSTOP company accounts. Shared lists can be read (but not updated) by third party accounts that have been granted access to the account configuration.

  • A list is shared if the shared setting is True.
  • For shared lists, the account that can make changes to the list (settings or list of subnets) has the owner field set to True. Accounts with whom the list is shared has the owner field set to False, and can only read the list with the API.

Addresses

Addresses can be written as IP addresses, subnets and ranges.

The address types are:

  • ip (single IP address, no netmask, e.g. a.b.c.d)
  • netmask (based address/mask, e.g. a.b.c.d/n)
  • range (a.b.c.d-e.f.g.h). IP address 2 must be after IP address 1. Ranges will be converted to subnets in the policy data.

The larger network size accepted in IP User lists is /8.

Warning: be careful about inserting large subnets into your custom lists. This could result in unintentionally overblocking large sections of the Internet.

Note: The API will output the type in responses but will auto-detect the type in the body of POST, PATCH and PUT requests. The type of address is not needed when add entries and will be ignored.

Entry types can be mixed in the same request, for example:

"addresses": [
  {
    "value": "8.8.8.8"
  },
  {
    "value": "8.8.8.0/24".
    "comments": "a /24 network"
  },
  {
    "value": "192.0.0.0-192.0.0.255",
    "comments": "a range with 256 addresses"
  }
]

When using in a DNS policy assigned to an RPZ-compatible device, records are added using the *Response IP Address trigger.

Forbidden values

The system doesn’t allow the following entries:

  • Netmask and Ranges greater than a /8 subnet
  • RFC1918 IPs
    • By default, private subnets are not allowed in IP user lists. Malicious actor can not use RFC1918 IPs to host their infrastrcture as they are not routed on the Internet and blocking RFC1918 IPs could result in blocking your own internal traffic.
    • The subnets are
      • 10.0.0.0/8
      • 127.0.0.0/8
      • 172.16.0.0/12
      • 192.168.0.0/16
      • 169.254.0.0/16
      • 0.0.0.0/8
    • However, in rare cases, it might make sense to use a user-defined list to whitelist an internal IP address that would otherwise be blocked by your policy. For example, your policy can be configured to block a country (using a Geo Target) but you want to allow an internal server to connect or receive connections from that country (e.g. an email server or a web server).
    • To bypass the validation checking for RFC1918 IPs, set the allow_bogon parameter to true.

Expiration

Each entry can be set to individually expire. If an expiration date is set, it will not be included in the policy once the date is reached. However, it will remain in the user defined list. The expiration date can be written as YYYY-MM-DD or MM/DD/YYYY in requests. It is always using the YYYY-MM-DD in API responses.

Maximum list size

User-defined lists can include up to 20,000 records. Multiple lists can be added to the same policy.

List IDs

To identify a list in GET, PUT and DELETE requests, the list can be identified by its UUID (immutable) or name (subject to change, via the API or Admin Portal)