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 bird’s 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
  • Ubuntu 18.04
  • Ubuntu 20.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 Zone masters retrieved from device settings
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 or 5353
  • DNS over UDP (optional, but recommended for DNS notifications)
    • IP Range: 192.124.129.0/24
    • Inbound UDP 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.
    • Select DNS Defense
    • 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://logs.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.

Edit the BIND configuration files

You will need the following settings to configure BIND:

Setting Value
DNS Server IP Address Zone masters 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
  • 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";
    };
    
  • 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 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 { [Zone masters retrieved from device settings]; };
    file "/var/cache/bind/ [Zone name retrieved from device settings] ";
    allow-transfer { none; };
    allow-query { localhost; };
};
  • 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 syslog_local0 {
    syslog local0;
    severity info;
    print-time yes;
    print-category yes;
    print-severity yes;
};

category rpz { syslog_local0; };
  • Create rsyslog bind configuration file /etc/rsyslog.d/99-bind-rpz.conf with the following content
     # Log named generated RPZ log messages to file
    if $programname == 'named' and $syslogfacility-text == 'local0' and $msg contains 'rpz' then /var/log/named/rpz.log
    
  • Restart Bind and rsyslog. Your initial policy will be downloaded within a couple of minutes in /var/cache/bind. Check BIND’s log in /var/log/syslog if the policy does not download.
    sudo service bind9 restart
    sudo service rsyslog 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

BIND views

If your BIND instance is configured to use views, the RPZ zone must be included in every view. Instead of including /etc/bind/threatstop.rpz.conf in named.conf, include it in every view statement.

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
    create 0644 syslog adm
    postrotate
    /usr/sbin/service rsyslog restart > /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 every 15 minutes but you can send adjust the crontab frequency to your preference
    */15 * * * *      root /usr/sbin/logrotate -f /etc/logrotate.d/threatstop
    

Proxy support

If your network requires the use of an HTTP proxy, add the proxy option to the curl command in the logrotate config file: –proxy server:port. The proxy must be an HTTP proxy with support for HTTPS (CONNECT protocol).

Additional Information