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

Overview

This document describes the integration process of the ThreatSTOP DNS Firewall with a PowerDNS 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: PowerDNS 4.5+ (Ubuntu).
  • Installing Powerdns Recursor on Ubuntu if you don’t have a running instance already.
  • Configure PowerDNS act as a slave server for the zone that contains your policy using LUA.
  • Optionnally, install the provided service to collect and upload logs.
  • Configure the client machines to be protected to use the ThreatSTOP DNS Firewall for address resolution.

Compatibility

Supported Operating Systems

  • Any OS that can run PowerDNS Recursor (see packages https://repo.powerdns.com/) can load ThreatSTOP’s RPZ.
  • Log collection and upload to ThreatSTOP servers requires a ThreatSTOP-provided module currently available for Ubuntu 18.04 and Ubuntu 20.04. Please contact support@threatstop.com if you would like to upload logs on a different OS.

Supported PowerDNS Servers

  • PowerDNS Recursor 4.5.0 or later

Limitations

  • PowerDNS Recursor 4.5 or later is required for parsing of RPZ triggers (the domain or DNS that caused a DNS lookup to be blocked) and RPZ actions (the DNS action performed in response to the policy hit) in logs and ThreatSTOP reports.
  • Currently, PowerDNS doesn’t log RPZ details if the policy action is to drop the request (i.e. to not answer the client).
  • PowerDNS doesn’t support notifcations for updates of RPZ zones (see https://github.com/PowerDNS/pdns/issues/5284).

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 (tdid) 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 PowerDNS-based DNS Firewall on Ubuntu requires a system that meets at least these specifications.

  • 2 GB of RAM.
  • 10 GB of disk space.
  • Time synchronized (e.g. using NTP) - policy zones will not download if the server time is not correct.
  • Python 3 for logging.

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
  • HTTPS
    • Hostname: logs.threatstop.com
    • IP range: 204.68.99.208/28
    • Outbound TCP port 443

PowerDNS Installation

The PowerDNS installation documentation is available https://doc.powerdns.com/recursor/getting-started.html. This describes the installation of version 4.5, the first version which includes full RPZ logging capabilities. Using newer version than 4.5 should not cause issues. Repositories for other PowerDNS versions and other operating systems are documented https://repo.powerdns.com/.

Ubuntu 18.04

  • Create /etc/apt/sources.list.d/powerdns.list with this content
    deb [arch=amd64] http://repo.powerdns.com/ubuntu bionic-rec-45 main
    
  • Run the following commands
    curl https://repo.powerdns.com/FD380FBB-pub.asc | sudo apt-key add -
    apt update
    apt install pdns-recursor
    

Ubuntu 20.04

  • Create /etc/apt/sources.list.d/powerdns.list with this content
    deb [arch=amd64] http://repo.powerdns.com/ubuntu focal-rec-45 main
    
  • Run the following commands
    curl https://repo.powerdns.com/FD380FBB-pub.asc | sudo apt-key add -
    apt update
    apt install pdns-recursor
    

Setup instructions

The following steps will walk you through the configuration of PowerDNS 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: PowerDNS (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 PowerDNS

You will need the following settings to configure PowerDNS:

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

The RPZ feature is enabled using PowerDNS’s LUA feature as documented here. The default PowerDNS configuration file (/etc/powerdns/recursor.conf), the following entry should exist. Add it if you are using a custom configuration.

lua-config-file=/etc/powerdns/recursor.lua

Edit /etc/powerdns/recursor.lua (or your existing LUA configuration file) to add:

-- ThreatSTOP RPZ Configuration
rpzPrimary("192.124.129.51", "[Zone name retrieved from device settings]", { tsigname="Retrieved from device settings", tsigalgo="hmac-md5", tsigsecret="Retrieved from device settings"})

Next, restart PowerDNS and check that the Response Policy Zone is filtering:

$ sudo systemctl restart pdns-recursor
$ dig @127.0.0.1 bad.threatstop.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 11203
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;bad.threatstop.com.		IN	A

;; Query time: 1 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Oct 26 19:44:17 UTC 2020
;; MSG SIZE  rcvd: 47

The command should return no records. If an IP address is returned, review the PowerDNS configuration. You can also run the server with trace on (using --trace) to check for issues.

Logging and Log upload

Logging is optional. PowerDNS logs RPZ hits by sending Protobuf messages. A tool to receive and process the log messages is provided by ThreatSTOP. It will relay logs to a syslog server.

  • Add the following line to the PowerDNS LUA configuration file
    -- Logging
    protobufServer("127.0.0.1:8000", {logQueries=true, logResponses=true, exportTypes={'A', 'AAAA', 'CNAME', 'MX', 'PTR', 'NS', 'SPF', 'SRV', 'TXT'}} )
    
  • Add the ThreatSTOP repository: create /etc/apt/sources.list.d/threatstop.list with this content
    # Ubuntu 18.04
    deb https://debian.threatstop.com/ThreatSTOP/ bionic main
    
    # Ubuntu 20.04
    deb https://debian.threatstop.com/ThreatSTOP/ focal main
    
  • Download and install the PowerDNS Log service (ThreatSTOP package)
    curl https://debian.threatstop.com/GPG-KEY.asc | sudo apt-key add -
    sudo apt update
    sudo apt install pdns-rpz-log
    

This package will install:

  • a script named pdns-rpz-logger in /usr/local/bin.
  • a systemd config file to control it (systemctl <command> pdns-rpz-log).
  • a syslog configuration file named threatstop-pdns.conf in /etc/rsyslog.d/ to route syslog message.
  • a cron file named threatstop-pdns in /etc/cron.d/ to trigger the RPZ RPZ log rotation.
  • a logrotate configuration file named threatstop in /etc/logrotated.d to rotate and upload the RPZ logs.
  • a config file named /etc/ts-pdns-tdid which must edited to contain your device’s id (tdid).
    • Your tdid: retrieve it from the device settings page.

Syslog output will be written to /var/log/rpz.log, e.g.

Apr 20 18:03:28 ubuntu-focal 2021-04-20 18:03:27 client 127.0.0.1#39283 (bad.threatstop.com): rpz QNAME NXDOMAIN rewrite bad.threatstop.com via bad.threatstop.com.Policy.Account.rpz.threatstop.local

Log upload can be disabled by commenting out the curl command in /etc/logrotate.d/threatstop.

  • Restart PowerDNS

  • Test that your logging 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/rpz.log

  • 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-pdns
    

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).