Configuring a Passive DNS sensor

A quick introduction to DNSTAP

DNSTAP is a performant method for logging DNS traffic in a binary format. The Spamhaus dnstap-sensor reads this DNSTAP data from the nameserver through a socket and relays it to our collectors. The data collected provides rapid insight into DNS infrastructure, enabling investigators to locate new threats from a single point and block related menaces to further protect you.

To provide us with this valuable data, you will need to take the following steps:

  1. Download the dnstap-sensor package

  2. Install the dnstap-sensor package

  3. Configure the dnstap-sensor.

  4. Compile the nameserver to support DNSTAP and modify the configuration to enable it.

  5. Send us the IP addresses you will be sending the data from, using the email below. This is to ensure our protected systems will accept your data.

Support

Contact us at data-team@spamhaus.org

Step 1 - Download the sensor package

The latest versions of the sensor can always be downloaded here https://docs.spamhaus.com/pdns/docs/source/000-WO/pdns-sensor.html.

Choose the correct version for your system. If you require a different version, please contact us and will endeavor to make this available.

If you’re not sure which version you need, run “uname -a” on the command line and you should see something that matches one of the files in the following table:

Package Architecture Common Operating Systems
linux-amd64.tar.gz Linux amd64(x86_64) Debian/Ubuntu/Redhat/Fedora/Amazon Linux
linux-arm64.tar.gz Linux arm64 Raspberry Pi OS
linux-arm32.tar.gz Linux arm32 Raspberry Pi OS
solaris-amd64.tar.gz Solaris amd64 Solaris
freebsd-amd64.tar.gz FreeBSD amd64 FreeBSD
openbsd-amd64.tar.gz OpenBSD amd64 OpenBSD
netbsd-amd64.tar.gz NetBSD amd64 NetBSD

Step 2 - Install the sensor package

What is in the sensor package?

The package is provided as a tar.gz file, which contains the following three files:

  • dnstap-sensor – the program binary

  • sensor.conf – the base configuration file

  • dnstap-sensor.service – the systemd unit file

The default location for the executable and configuration file is “/etc/dnstap/”.

How to install the dnstap-sensor:

  • Untar the file

  • Copy the program binary and configuration file to “/etc/dnstap”.

(Using the -c option you can locate them elsewhere.)

 dnstap-sensor -c /path/to/config/file

The dnstap-sensor creates a Unix socket, the location of which is specified in the configuration file.

Please note: The account running your nameserver must have write privileges to that file.

Step 3 - Edit the configuration file

The default configuration file location is:

/etc/dnstap/sensor.conf

[user] This is a required field and is used for authentication. The username must be enclosed with quotation marks (”).

Spamhaus will provide this information to you.

[password] Your secret password which is used for authentication. The password must be enclosed with quotation marks (”).

Spamhaus will provide this information to you.

[destination] dnstap data is transmitted to Spamhaus using a web socket. The destination must be enclosed with quotation marks (”). This field contains a DNS hostname that provides SRV DNS records that are unique to each sensor operator.

Spamhaus will provide this information to you.

[listener_type] This specifies the type of listener the sensor will use to accept DNSTAP information from the nameserver program. The valid options are “tcp” or “socket”.

  • Use “tcp” if the nameserver is configured to send DNSTAP data to a TCP address, such as “127.0.0.1:8503”.

  • Use “socket” if the nameserver is configured to send
    DNSTAP data to a Unix socket, such as “/etc/dnstap/dnstap.socket”. If this setting is not specified, the default is “socket”. Not all nameservers support sending DNSTAP data to a TCP address.

[listener_endpoint] This specifies the location where the sensor listens to accept DNSTAP information from the nameserver program. The value must be enclosed in quotation marks (”). The nameserver must be configured to match this setting.

The value can be either a Unix socket path or a TCP address. Ensure that the nameserver has write permissions for the configured location.

For a TCP listener, the format should be “IP:Port”. To listen on all available addresses, use “:PORT”. If [listener_type] is set to “tcp” and this setting is not specified, the default is “:8503”.

[srcip] The ‘srcip’ setting is optional. This is the source IP that the sensor uses to send dnstap information to our collectors. The IP must be enclosed with quotation marks (”). If the setting is not set the dnstap-sensor will use the preference of the server

Step 4 - Configure your name server BIND

Bind must first be compiled from source with dnstap support. Instructions to on how to do this can be found here.

After compilation the following lines must be added in named.conf, under the options section:

dnstap {
    resolver response;
};
dnstap-output unix "/etc/dnstap/dnstap.sock";

If you are using a custom socket location you will have to alter the “dnstap-output” field to reflect this.

After the configuration file has been updated a simple “rndc reload” will make the changes take effect.

UNBOUND

Unbound must first be compiled from source with dnstap support. Instructions on how to do this can be found here.

After compilation the following lines must be added to unbound.conf:

dnstap:
    dnstap-enable: yes
    dnstap-socket-path: "/etc/dnstap/dnstap.sock"
    dnstap-send-identity: yes
    dnstap-send-version: yes
    dnstap-log-resolver-response-messages: yes

If you are using a custom socket location you will have to alter the “dnstap-socket-path” field to reflect this.

By default Unbound runs with a chroot option enabled. If the chroot option is enabled make sure that the socket is within the chroot.

After the configuration file has been updated a simple “unbound-control reload” will make the changes take effect.

Step 5 - Submit your server IP addresses to Spamhaus

Access to the dnstap collectors is restricted by a firewall. You must provide the public IP addresses of your nameservers to Spamhaus so we can provision our firewall.

Step 6 - Starting the dnstap-sensor

The dnstap-sensor should be configured to automatically start when the server boots up. This can be done on most Linux systems either by adding the program to your rc.local file or systemd. See the section below entitled “SYSTEMD” for instructions on how to configure systemd.

Once you receive confirmation from Spamhaus that your account has been activated you can turn on the collector. Execute the following command on your server:

 [/path/to/]dnstap-sensor -c [/path/to/]sensor.conf &

To check the version of the dnstap-sensor run:

dnstap-sensor -v

SYSTEMD (optional)

The Linux packages come with a dnstap-sensor.service file that can be used. You must edit this file if you are not using the default locations. To set up the dnstap-sensor service place this file under “/etc/systemd/system/”

Then run:

systemctl daemon-reload
systemctl enable dnstap-sensor.service

Once the configuration file has been filled out and the dnstap-sensor binary has been put in place run:

systemctl start dnstap-sensor.service

There is no PII or personally identifiable information within this data.