Nominum Vantio CacheServe - Native Integration

Overview

This integration allows a Nominum Vantio CacheServe server to retrieve a ThreatSTOP DNS Defense policy directly from the ThreatSTOP cloud over HTTPS, using CacheServe’s built-in HTTPS download capability. The policy is delivered as a single plain-text list of domain names to block, and your CacheServe policy applies a blocking action to the domains in the list.

This integration does not require installing any ThreatSTOP software or virtual machine. Telemetry and DNS Defense reports are not available for this integration.

This document describes the ThreatSTOP side of the integration: the policy URL, the credentials, the list format, and how to check that the download works. Use the Nominum Vantio CacheServe documentation for the CacheServe configuration steps.

Compatibility

† - Requires a CacheServe version that can download a list of domain names over HTTPS.

The maximum number of domains CacheServe can load depends on its version and on the resources of the server. Check the Nominum documentation for the limit, and use it for the Maximum Policy Size setting in Step 1.

Connectivity

To retrieve its policy, the Vantio CacheServe server needs the following connectivity:

• HTTPS - Policy service
  • Hostname: policies.threatstop.com
  • IP Addresses: not fixed. The service is load balanced, so allow it by hostname rather than by IP address
  • Outbound TCP port 443

Access to the policy service is also restricted by IP address: requests must come from the public IP address registered on the device entry in the ThreatSTOP Admin Portal. If the device uses a dynamic IP address (IP Type: dynamic), ThreatSTOP periodically resolves its domain name and updates the registered address. Requests from a new IP address may be rejected until the update has been applied.

Prerequisites

• Current active ThreatSTOP account
• Administrator account on the Vantio CacheServe server
• HTTPS (outbound TCP/443) from the CacheServe server to policies.threatstop.com

Installation Overview

1. Add and configure the device in the Admin Portal
2. Retrieve the policy URL and credentials from the Admin Portal
3. Check the policy download with curl (optional)
4. Configure the CacheServe HTTPS list download
5. Test the configuration

Setup

Step 1 - Portal device configuration

During this step, you will create a device entry on the Admin Portal.

To create the device entry:

• Log into the Admin Portal with your ThreatSTOP account
• Browse to the Device page and click Add Device
• Select the model:
  • Type: DNS Defense
  • Manufacturer: Nominum
  • Model: Vantio CacheServe
  • Integration Type: HTTPS Download

The Admin Portal will display a form to enter the device settings described below.

• Nickname: this is a mnemonic name used to identify the device. It can be set to any string (A-Z, 0-9, - and _). If you create multiple device entries, each entry must have a unique nickname.
• Policy: select a pre-defined policy or a customized policy. It must be a DNS Defense Policy.
• IP Type: Access to the ThreatSTOP services is controlled in part using an ACL allowing the device IP to connect. If your server has a static public IP address (the most common case), select static. If your server has a dynamic public IP address, the ThreatSTOP services can look up the IP address using a DNS fully-qualified name (FQDN).
• External IP Address: In static mode, this is the public IP address the CacheServe server uses to connect to the internet. If the server is behind a NAT device, use the NAT device’s public address.
• Domain name: In dynamic mode, this is a DNS FQDN which must be kept up to date as an A record pointing to the server’s dynamic IP.
• Note: An optional field to store a note of your choice about the device - location, identifiers, model…
• Maximum Policy Size: The maximum number of domains delivered to the server. The default is 100,000. Leave blank for no limit. See Compatibility for how to find your server’s limit.

If your policy is larger than the configured size, ThreatSTOP truncates it, keeping the highest-priority entries: user-defined lists first, then targets in ThreatSTOP’s priority order.

Upon saving the form, a device entry will be created in ThreatSTOP’s cloud.

Step 2 - Retrieve the policy URL and credentials

Once the device entry is saved, the device page in the Portal displays the values needed to configure CacheServe:

The Block List URL has the form https://policies.threatstop.com/policy/dns. The whole policy is delivered in a single download, so there is only one URL.

CacheServe authenticates to the policy service with the Device ID and the API Token. HTTP basic authentication, with the Device ID as the username and the API Token as the password, is recommended. Step 3 shows the other supported methods.

Step 3 - Check the policy download with curl (optional)

Before configuring CacheServe, you can check the URL and credentials with curl. Run the commands from a host that uses the same public IP address as the CacheServe server, otherwise the policy service rejects the request (see Connectivity).

The policy service accepts the credentials in any of the three ways below. Use the one your CacheServe version supports in Step 4.

When you open this page from the device’s documentation link in the Portal, the commands below are filled in with the device’s Device ID, API Token and Block List URL. Otherwise, replace tdid_XXXXXX and YourApiToken with the values from Step 2.

HTTP basic authentication, with the Device ID as the username and the API Token as the password:

curl -sS --fail -u 'tdid_XXXXXX:YourApiToken' \
  -o threatstop-blocklist.txt \
  'https://policies.threatstop.com/policy/dns'

An X-API-Token header, set to the Device ID and the API Token separated by a colon:

curl -sS --fail -H 'X-API-Token: tdid_XXXXXX:YourApiToken' \
  -o threatstop-blocklist.txt \
  'https://policies.threatstop.com/policy/dns'

An x-api-token URL parameter, with the colon URL-encoded as %3A:

curl -sS --fail -o threatstop-blocklist.txt \
  'https://policies.threatstop.com/policy/dns?x-api-token=tdid_XXXXXX%3AYourApiToken'

Then look at the downloaded list:

wc -l threatstop-blocklist.txt
head threatstop-blocklist.txt

The list is plain text, with one domain name per line:

example-malware-domain.com
*.example-phishing-domain.net
example-c2-domain.org

• The list only contains domains to block. Allowed (passthru) entries, and policy entries based on IP addresses or name servers, are not included.
• The list can contain wildcard entries, such as *.example-phishing-domain.net. If CacheServe rejects or misreads them, contact ThreatSTOP Support: the way wildcard entries are delivered can be changed for your device without any change on the CacheServe server.
• The list never contains more domains than the Maximum Policy Size set in Step 1. Wildcard entries count toward this size.
• If the policy is empty, the list contains a single test domain, bad.threatstop.com, so the download is never empty.

If curl reports an error, see Troubleshooting.

Step 4 - Configure the CacheServe HTTPS list download

Configure CacheServe to download the ThreatSTOP list, and apply a blocking action to the domains in the list. Use the settings below, and see the Nominum Vantio CacheServe documentation for where to enter them.

Step 5 - Test the configuration

Once CacheServe has downloaded the list, you can test the policy using bad.threatstop.com, a test domain included in most DNS Defense policies.

First, confirm that the domain is in the list you downloaded in Step 3:

grep -x 'bad.threatstop.com' threatstop-blocklist.txt

Then, from a client that uses the CacheServe server as its resolver, look up the domain. The response should be the blocking response configured in Step 4, rather than the domain’s real address:

dig bad.threatstop.com @<CacheServe server IP>

Uninstall

• Remove the ThreatSTOP list and its blocking action from the CacheServe configuration
• Delete the device entry in the Admin Portal

Troubleshooting

The list fails to download or contains only a placeholder

If ThreatSTOP has no entries for the policy, the list contains the single test domain bad.threatstop.com, so the download is never empty. This is expected, for example for a new policy with no targets. If the list contains only this domain but you expect more, check the policy assigned to the device in the Portal.

If the list fails to download, test the Block List URL from a computer behind the same public IP address as the CacheServe server, using the same credentials:

curl -s -o /dev/null -w '%{http_code}\n' -u 'tdid_XXXXXX:YourApiToken' 'https://policies.threatstop.com/policy/dns'

If the command does not return a response code, check the server’s DNS settings, default route, and any firewall between the server and policies.threatstop.com.

If the network connectivity is OK and 15 minutes have elapsed since the device entry was created, please contact ThreatSTOP Support at support@threatstop.com.

Related documents

• Creating custom policies
• RPZ devices

References

• Nominum Vantio CacheServe documentation, available from your Nominum / Akamai support portal