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 located 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:

Download the dnstap-sensor package
Install the dnstap-sensor package
Configure the dnstap-sensor.
Compile the nameserver to support DNSTAP and modify the configuration to enable it.
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.

[socket] This is the location for the socket that the sensor uses to accept dnstap information from the nameserver program. The socket must be enclosed with quotation marks (”).Your name server’s dnstap socket must match this setting. You can override the default setting, but if you do, ensure that the nameserver daemon has write permissions on the directory that the socket is located in.

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