Overview of the domain user list features

Domain User-defined lists are lists of domain names 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 hostnames and domains.

User-defined domain lists can be added to DNS Policies (to block records from being resolved or to whitelist records). They can not be used in IP Policies.

Records can be for a FQDN or a domain name. Wildcard domains are supported.

Policy action

Unlike IP lists, Domain lists don’t have a type (block or allow). The action associated with the list is defined by the RPZ Behavior attached to the list in the DNS Policy.

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 are DNS record names, either FQDN, domain names or Name server RPZ records. Domain names can have a leading wildcard. For example:

  • www.threatstop.com
  • threatstop.com
  • *.threatstop.com

Note: wildcards are only valid at the start of the record. www.*.example.com is not valid.

For RPZ-compatible devices, records are added using the QNAME trigger.

Domain names must be less than 200 characters long in total. The length of any label (subsection) must not exceed 63 characters.

Domain names containing underscores are not supported.

IDN support

Internationalized domains are supported using the Punycode encoding.

Name server records

Name servers records will block DNS responses that were provided by the DNS servers identified by the record.

  • For IP addresses of DNS servers (e.g. a.b.c.d/32), the record must be written with the netmask, with 4 digits of the IP address written backwards, followed by the rpz-nsip suffix: netmask.d.b.c.a.rpz-nsip (e.g. 32.4.3.2.1.rpz-nsip). It is allowed to specify a subnet.
  • For FQDNs of DNS Servers (e.g. host.domain.tld), the FQDN must be followed by the rpz-nsdname suffix: host.domain.tld.rpz-nsdname (e.g. ns1.example.com.rpz-nsdname).

Forbidden values

The system enforces the correct syntax of a domain name but doesn’t restrict domain names.

Warning: Be careful with wildcards and TLDs to avoid over-blocking.

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.