Python Dnstap receiver
Project description
Dnstap receiver
This Python module acts as a DNS tap receiver and streams as JSON, YAML or text payload to remote tcp address or directly to stdout.
Table of contents
- Installation
- Show help usage
- Start dnstap receiver
- Output formats
- Tested DNS servers
- Tested Logs Collectors
- Systemd service file configuration
- 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 [-v] [-y] [-j] [-d D]
optional arguments:
-h, --help show this help message and exit
-u U read dnstap payloads using framestreams from unix socket
-v verbose mode
-y write YAML-formatted output
-j write JSON-formatted output
-d D send dnstap message to remote tcp/ip address
Start dnstap receiver
The 'dnstap_receiver' binary takes in input a unix socket In this case the output will be print directly to stdout with short text format.
dnstap_receiver -u /var/run/dnstap.sock
If you want to send the dnstap message as json to a remote tcp collector, type the following command:
dnstap_receiver -u /var/run/dnstap.sock -j -d 10.0.0.2:8192
Output formats
Severals outputs format are supported:
- short text output
- JSON
- YAML
Short text
2020-09-12 14:15:00.551 CLIENT_QUERY NOERROR 192.168.1.114 46528 IP4 TCP 43b www.google.com. A
2020-09-12 14:15:00.551 CLIENT_RESPONSE NOERROR 192.168.1.114 46528 IP4 TCP 101b www.google.com. A
JSON-formatted
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
}
YAML-formatted
CLIENT_QUERY / FORWARDER_QUERY / RESOLVER_QUERY
code: NOERROR
length: 49
message: RESOLVER_QUERY
protocol: IP4
query-name: dns4.comlaude-dns.eu.
query-type: AAAA
source-ip: '-'
source-port: '-'
timestamp: '2020-09-12 14:13:53.948'
transport: UDP
CLIENT_RESPONSE / FORWARDER_RESPONSE / RESOLVER_RESPONSE
code: NOERROR
length: 198
message: RESOLVER_RESPONSE
protocol: IP4
query-name: dns3.comlaude-dns.co.uk.
query-type: AAAA
source-ip: '-'
source-port: '-'
timestamp: '2020-09-12 14:13:54.000'
transport: UDP
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 be 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"
}
}
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
About
Author | Denis Machard d.machard@gmail.com |
License | MIT |
PyPI | https://pypi.org/project/dnstap_receiver/ |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dnstap_receiver-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 983699f02f6890f4cab814c77a040be136aabf0a01e2cafbfa3b13c8a8c8b34a |
|
MD5 | d7ea8eac36a7e8e17f18424d524a2a41 |
|
BLAKE2b-256 | 256be7c23054cd76102568340d2d682a728f13e804292e7b92a121c7daf68b24 |