dnstap-receiver 0.2.0

Python Dnstap to JSON stream receiver

Dnstap to JSON stream receiver

This Python module acts as a DNS tap receiver and streams as JSON payload to remote address or stdout.

Table of contents

• Installation
• Show help usage
• Start dnstap receiver
• Output JSON format
• Systemd service file configuration
• Tested DNS servers
• Tested Logs Collectors
• About

Installation

Deploy the dnstap receiver in your DNS server with the pip command.

pip install dnstap_receiver

Show help usage

dnstap_receiver --help
usage: dnstap_receiver.py [-h] -u U -j J

optional arguments:
  -h, --help  show this help message and exit
  -u U        read dnstap payloads from unix socket
  -j J        write JSON payload to tcp/ip address 

Start dnstap receiver

The 'dnstap_receiver' binary takes in input a unix socket

dnstap_receiver -u /var/run/dnstap.sock

You can also add a remote tcp json collector to forward the log to another destination

dnstap_receiver -u /var/run/dnstap.sock -j 10.0.0.2:8192

Output JSON format

CLIENT_QUERY / FORWARDER_QUERY / RESOLVER_QUERY

{
    "message": "CLIENT_QUERY",
    "s_family": "IPv4",
    "s_proto": "TCP",
    "q_addr": "127.0.0.1",
    "q_port": 43935, 
    "dt_query": "2020-09-12 10:41:36.591",
    "q_name": "www.google.com.",
    "q_type": "A"
}

CLIENT_RESPONSE / FORWARDER_RESPONSE / RESOLVER_RESPONSE

{
    "r_code": "NOERROR",
    "port": 52782,
    "q_name":"rpc.gandi.net.",
    "s_family":"IPv4",
    "r_bytes": 47,
    "dt_reply": "2020-05-24 03:30:01.411",
    "q_addr": "10.0.0.235",
    "host": "10.0.0.97",
    "message": "CLIENT_RESPONSE",
    "q_type": "A",
    "s_proto": "UDP",
    "dt_query": "2020-05-24 03:30:01.376",
    "q_port": 40311,
    "q_time": 0.035
}

Systemd service file configuration

System service file for CentOS:

vim /etc/systemd/system/dnstap_receiver.service

[Unit]
Description=Python DNS tap Service
After=network.target

[Service]
ExecStart=/usr/local/bin/dnstap_receiver -u /etc/dnsdist/dnstap.sock -j 10.0.0.2:8192
Restart=on-abort
Type=simple
User=root

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl start dnstap_receiver
systemctl status dnstap_receiver
systemctl enable dnstap_receiver

Tested DNS servers

This dnstap receiver has been tested with success with the following dns servers:

• PowerDNS - dnsdist
• NLnet Labs - unbound

dnsdist

The following file /etc/dnsdist/dnsdist.conf must be updated like below:

fsul = newFrameStreamUnixLogger("/var/run/dnstap.sock")
addAction(AllRule(), DnstapLogAction(fsul))
addResponseAction(AllRule(), DnstapLogResponseAction(fsul))

unbound

Unbound must build with dnstap support ./configure --enable-dnstap. The following file /etc/unbound/unbound.conf must be updated too:

dnstap:
    dnstap-enable: yes
    dnstap-socket-path: "dnstap.sock"
    dnstap-send-identity: yes
    dnstap-send-version: yes
    dnstap-log-resolver-query-messages: yes
    dnstap-log-resolver-response-messages: yes
    dnstap-log-client-query-messages: yes
    dnstap-log-client-response-messages: yes
    dnstap-log-forwarder-query-messages: yes
    dnstap-log-forwarder-response-messages: yes

Tested Logs Collectors

Logstash

vim /etc/logstash/conf.d/00-dnstap.conf

input {
  tcp {
      port => 8192
      codec => json
  }
}

filter {
  date {
     match => [ "dt_query" , "yyyy-MM-dd HH:mm:ss.SSS" ]
     target => "@timestamp"
  }
}

output {
   elasticsearch {
    hosts => ["http://localhost:9200"]
    index => "dnstap-lb"
  }
}

About

Author	Denis Machard [e-mail]
License	MIT
PyPI	https://pypi.org/project/dnstap_receiver/