This document describes the integration process of the ThreatSTOP DNS Defense with a BIND 9 DNS server running on Ubuntu.

Overview

This document describes the integration process of the ThreatSTOP DNS Firewall with a BIND 9 DNS server running on Ubuntu.

A birds-eye view of the setup procedure is:

  • Open a ThreatSTOP account if you have not already done so.
  • Using the Portal, configure a new device - Manufacturer: DNS Server and Model: BIND 9.8+ (Ubuntu)
  • Installing BIND on Ubuntu if you don’t have a running instance already
  • Configure BIND itself to act as a slave server for the zone that contains your policy.
  • Configure BIND Log upload
  • Configure the client machines to be protected to use the ThreatSTOP DNS Firewall for address resolution.

Compatibility

Supported Systems

  • Ubuntu 14.04
  • Ubuntu 16.04

Supported BIND Servers

  • BIND 9.8.2+
  • BIND 9.9.x
  • BIND 9.10.x
  • BIND 9.11.x
  • BIND 9.12.x

Device Settings

You will need the following settings to complete the installation. You can retrieve the RPZ Zone name, TSIG Key name, TSIG Key secret and Device ID via the settings of the device in the Admin Portal.

Setting Value
DNS Server IP Address 192.124.129.51
Device ID Retrieved from device settings
RPZ Zone Name Retrieved from device settings
TSIG Key Name Retrieved from device settings
TSIG Key Secret Retrieved from device settings

Prerequisites

System

The ThreatSTOP BIND-based DNS Firewall on Ubuntu requires a system that meets at least these specifications.

You will need root access on the Ubuntu system.

Connectivity

To retrieve its configuration and policy, and to upload log data, the machine needs the following connectivity:

  • DNS over TCP
    • IP Range: 192.124.129.0/24
    • Outbound TCP port 53
  • HTTPS
    • Hostname: logs.threatstop.com
    • IP range: 204.68.99.208/28
    • Outbound TCP port 443

Setup instructions

The following steps will walk you through the configuration of BIND to enable the ThreatSTOP DNS Firewall.

ThreatSTOP Portal setup

  • If you want to use a custom DNS Firewall policy, please read DNS Firewall Policies
  • Create a new Device Entry: Click on Devices and then on Add Device.
    • The Manufacturer is: DNS Server
    • The Model is: BIND 9.8+ (Ubuntu)
  • Select the DNS Firewall policy - either a pre-defined policy or a custom policy
  • Note: It can take up to 30 minutes for a new device to become available after it is created in the Portal. Once the device is available, its IP address will be recognized in the output of the following command:
$ curl https://www.threatstop.com/cgi-bin/validip.pl
Your IP address: <ip address>
Address is in the list of authorized hosts

Configuring BIND

The following procedure will extend a default installation of BIND (BIND 9.8.2 and greater) to integrate with ThreatSTOP’s DNS Defense. We strongly recommend using the latest versions of BIND 9 and keeping it up-to-date with the latest security fixes.

If you don’t already have an instance of BIND, please see Installing BIND on Ubuntu

You will need root access - via sudo or su. The instructions below will use sudo but you can run them without sudo if you are logged in as root.

Create directories and set permissions

  • Make a directory for the named log files using the following command:
    sudo mkdir /var/log/named/
    
  • Set permissions and ownership for the log file directory:
    sudo chown -R bind:bind /var/log/named/
    

Edit the BIND configuration files

You will need the following settings to configure BIND:

Setting Value
DNS Server IP Address 192.124.129.51
RPZ Zone Name Retrieved from device settings
TSIG Key Name Retrieved from device settings
TSIG Key Secret Retrieved from device settings
  • Edit /etc/bind/named.conf.options and add the following in the options block:
    include "/etc/bind/threatstop.options.conf";
    
  • For example:
    options {
      directory "/var/cache/bind";
      // other options - either standard or your customized configuration
      include "/etc/bind/threatstop.options.conf";
    };
    
  • Change the dnssec validation setting from auto to yes
    options {
      ....
      dnssec-validation yes;
      ....
    };
    
  • Create /etc/bind/threatstop.options.conf and add a response-policy setting with the ThreatSTOP Zone Name:
response-policy {
    zone " [Zone name retrieved from device settings] ";
};
  • Edit /etc/bind/named.conf.local and add the following include at the end of the file:
    include "/etc/bind/threatstop.rpz.conf";
    
  • Create /etc/bind/threatstop.rpz.conf with the following content
key  [TSIG Key name retrieved from device settings]  {
    algorithm hmac-md5;
    secret " [TSIG Key secret retrieved from device settings] ";
};
server 192.124.129.51 {
    keys {  [TSIG Key name retrieved from device settings]  ; };
};
zone " [Zone name retrieved from device settings] " {
    type slave;
    masters { 192.124.129.51; };
    file "/var/cache/bind/ [Zone name retrieved from device settings] ";
};
  • Add the following line to the logging section, typically in /etc/bind/named.conf.local
    include "/etc/bind/threatstop.logging.conf";
    
  • If you don’t have a logging section (e.g. vanilla ubuntu install), add one to /etc/bind/named.conf.local
    logging {
      include "/etc/bind/threatstop.logging.conf";
    };
    
  • Create /etc/bind/threatstop.logging.conf with the following content
    channel named-rpz {
      file "/var/log/named/rpz.log";
      severity debug;
      print-time yes;
      print-category yes;
      print-severity yes;
    };
    category rpz {
      named-rpz;
    };
    
  • Restart Bind and your initial policy will be downloaded within a couple of minutes in /var/cache/bind. Check BIND’s log in /var/log/syslog if not.
    sudo service bind9 restart
    
  • Test that your configuration is working as expected:
    dig @127.0.0.1 bad.threatstop.com  should return NXDOMAIN
    ;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 5611
    ;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 2
    
  • Check that a log entry was added to /var/log/named/rpz.log

Configuring log upload

After configuring BIND to use ThreatSTOP’s Policy Zone, you can configure the system to send the RPZ logs to ThreatSTOP to report on the blocked queries.

You will need your device ID to configure log upload.

Setting Value
Device ID Retrieved from device settings
  • Create a logrotate configuration for threatstop
    sudo vi /etc/logrotate.d/threatstop
    
  • Copy and paste the example below to /etc/logrotate.d/threatstop
/var/log/named/rpz.log
{
    rotate 7
    size 100k
    missingok
    notifempty
    delaycompress
    compress
    su bind bind
    create 0644 bind bind
    postrotate
    /usr/sbin/service bind9 reload > /dev/null
    /usr/bin/curl -v -F "upfile=@$1.1" -F "upfile_size=`/usr/bin/stat -c %s $1.1`" -F "md5_client=`/usr/bin/md5sum $1.1|/usr/bin/cut -d' ' -f 1`" -F "fw_tdid=[Device ID retrieved from device settings]" https://logs.threatstop.com/cgi-bin/logupload.pl 
    endscript
}
  • Check the logrotate configuration. The following command should show a successful file upload (HTTP/1.1 200 OK)
    sudo /usr/sbin/logrotate -f /etc/logrotate.d/threatstop
    
  • Finally, add the log rotation to cron. Create and edit /etc/cron.d/threatstop and add the following entry. This uploads logs at 55 minutes past the hour but you can send adjust the crontab frequency to your preference
    55 * * * *      root /usr/sbin/logrotate -f /etc/logrotate.d/threatstop
    

Additional Information