README.md
1[![Build Status](https://travis-ci.org/farrokhi/dnsdiag.svg)](https://travis-ci.org/farrokhi/dnsdiag) [![PyPI](https://img.shields.io/pypi/v/dnsdiag.svg?maxAge=8600)](https://pypi.python.org/pypi/dnsdiag/) [![PyPI](https://img.shields.io/pypi/l/dnsdiag.svg?maxAge=8600)]() [![PyPI](https://img.shields.io/pypi/pyversions/dnsdiag.svg?maxAge=8600)]() [![Docker Pulls](https://img.shields.io/docker/pulls/farrokhi/dnsdiag)](https://hub.docker.com/r/farrokhi/dnsdiag) [![GitHub stars](https://img.shields.io/github/stars/farrokhi/dnsdiag.svg?style=social&label=Star&maxAge=8600)](https://github.com/farrokhi/dnsdiag/stargazers)
2
3DNS Measurement, Troubleshooting and Security Auditing Toolset
4===============================================================
5
6Ever been wondering if your ISP is [hijacking your DNS traffic](https://medium.com/decentralize-today/is-your-isp-hijacking-your-dns-traffic-f3eb7ccb0ee7)? Ever observed any
7misbehavior with your DNS responses? Ever been redirected to wrong address and
8suspected something is wrong with your DNS? Here we have a [set of tools](http://github.com/farrokhi/dnsdiag) to
9perform basic audits on your DNS requests and responses to make sure your DNS is
10working as you expect.
11
12You can measure the response time of any given DNS server for arbitrary requests
13using `dnsping`. Just like traditional ping utility, it gives you similar
14functionality for DNS requests.
15
16You can also trace the path your DNS request takes to destination to make sure
17it is not being redirected or hijacked. This can be done by comparing different
18DNS queries being sent to the same DNS server using `dnstraceroute` and observe
19if there is any difference between the path.
20
21`dnseval` evaluates multiple DNS resolvers and helps you choose the best DNS
22server for your network. While it is highly recommended using your own DNS
23resolver and never trust any third-party DNS server, but in case you need to
24choose the best DNS forwarder for your network, `dnseval` lets you compare
25different DNS servers from performance (latency) and reliability (loss) point
26of view.
27
28# Installation
29
30There are several ways that you can use this toolset. However, using the source code is always recommended.
31
32## Source Code
33
341. Check out the git repository and install dependencies:
35
36```
37git clone https://github.com/farrokhi/dnsdiag.git
38cd dnsdiag
39pip3 install -r requirements.txt
40```
41
422. You can alternatively install the package using pip:
43
44```
45pip3 install dnsdiag
46```
47
48## Binary Package
49
50From time to time, binary packages will be released for Windows, Mac OS X and Linux. You can grab the latest release from [releases page](https://github.com/farrokhi/dnsdiag/releases).
51
52## Docker
53
54If you don't want to install dnsdiags on your local machine, you may use the docker image and run programs in a container. For example:
55
56```
57docker run -it --rm farrokhi/dnsdiag ./dnsping.py
58```
59
60# dnsping
61dnsping pings a DNS resolver by sending an arbitrary DNS query for given number of times.
62A complete explanation of supported command line flags is shown by using `--help`. Here are a few useful flags:
63
64- Using `--tcp`, `--tls` and `--doh` to select transport protocol. Default is UDP.
65- Using `--flags` to display response flags for each response
66- Using `--dnssec` to request DNSSEC if available
67
68In addition to UDP, you can ping using TCP, DoT (DNS over TLS) and DoH (DNS over HTTPS) using `--tcp`, `--tls` and `--doh` respectively.
69
70```
71% ./dnsping.py -c 5 --dnssec --flags --tls -t AAAA -s 9.9.9.9 ripe.net
72dnsping.py DNS: 9.9.9.9:853, hostname: ripe.net, proto: TLS, rdatatype: AAAA, flags: RD
73233 bytes from 9.9.9.9: seq=1 time=186.202 ms [QR RD RA AD]
74233 bytes from 9.9.9.9: seq=2 time=191.233 ms [QR RD RA AD]
75233 bytes from 9.9.9.9: seq=3 time=105.455 ms [QR RD RA AD]
76233 bytes from 9.9.9.9: seq=4 time=111.053 ms [QR RD RA AD]
77233 bytes from 9.9.9.9: seq=5 time=110.329 ms [QR RD RA AD]
78
79--- 9.9.9.9 dnsping statistics ---
805 requests transmitted, 5 responses received, 0% lost
81min=105.455 ms, avg=140.854 ms, max=191.233 ms, stddev=43.782 ms
82```
83
84It also displays statistics such as minimum, maximum and average response time as well as
85jitter (stddev) and lost packets.
86
87There are several interesting use cases for dnsping, including:
88
89- Comparing response times using different transport protocols (e.g. UDP vs DoH)
90- Measuring how reliable your DNS server is, by measuring Jitter and packet loss
91- Measuring responses times when DNSSEC is enabled using `--dnssec`
92
93# dnstraceroute
94dnstraceroute is a traceroute utility to figure out the path that your DNS
95request is passing through to get to its destination. You may want to compare
96it to your actual network traceroute and make sure your DNS traffic is not
97routed to any unwanted path.
98
99In addition to UDP, it also supports TCP as transport protocol, using `--tcp` flag.
100
101```
102% ./dnstraceroute.py --expert --asn -C -t A -s 8.8.4.4 facebook.com
103dnstraceroute.py DNS: 8.8.4.4:53, hostname: facebook.com, rdatatype: A
1041 192.168.0.1 (192.168.0.1) 1 ms
1052 192.168.28.177 (192.168.28.177) 4 ms
1063 192.168.0.1 (192.168.0.1) 693 ms
1074 172.19.4.17 (172.19.4.17) 3 ms
1085 dns.google (8.8.4.4) [AS15169 GOOGLE, US] 8 ms
109
110=== Expert Hints ===
111 [*] public DNS server is next to a private IP address (possible hijacking)
112```
113
114Using `--expert` will instruct dnstraceroute to print expert hints (such as
115warnings of possible DNS traffic hijacking).
116
117# dnseval
118dnseval is a bulk ping utility that sends an arbitrary DNS query to a give list
119of DNS servers. This script is meant for comparing response time of multiple
120DNS servers at once.
121
122You can use `dnseval` to compare response times using different transport
123protocols such as UDP (default), TCP, DoT and DoH using `--tcp`, `--tls` and
124`--doh` respectively.
125
126```
127% ./dnseval.py --dnssec -t AAAA -f public-servers.txt -c10 ripe.net
128server avg(ms) min(ms) max(ms) stddev(ms) lost(%) ttl flags response
129----------------------------------------------------------------------------------------------------------------------------
1301.0.0.1 36.906 7.612 152.866 50.672 %0 300 QR -- -- RD RA AD -- NOERROR
1311.1.1.1 7.752 7.512 8.132 0.183 %0 298 QR -- -- RD RA AD -- NOERROR
1322606:4700:4700::1001 7.661 7.169 8.102 0.240 %0 297 QR -- -- RD RA AD -- NOERROR
1332606:4700:4700::1111 7.802 7.000 8.128 0.312 %0 296 QR -- -- RD RA AD -- NOERROR
134195.46.39.39 14.723 7.024 78.239 22.362 %0 300 QR -- -- RD RA -- -- NOERROR
135195.46.39.40 7.524 6.972 10.897 1.191 %0 300 QR -- -- RD RA -- -- NOERROR
136208.67.220.220 70.519 6.694 180.229 66.516 %0 300 QR -- -- RD RA AD -- NOERROR
137208.67.222.222 37.868 6.663 107.601 41.178 %0 300 QR -- -- RD RA AD -- NOERROR
1382620:0:ccc::2 31.471 6.768 178.647 56.546 %0 299 QR -- -- RD RA AD -- NOERROR
1392620:0:ccd::2 20.651 6.699 145.029 43.702 %0 300 QR -- -- RD RA AD -- NOERROR
140216.146.35.35 19.338 6.713 131.198 39.306 %0 300 QR -- -- RD RA AD -- NOERROR
141216.146.36.36 107.741 73.421 266.969 58.003 %0 299 QR -- -- RD RA AD -- NOERROR
142209.244.0.3 14.717 7.015 80.329 23.058 %0 300 QR -- -- RD RA -- -- NOERROR
143209.244.0.4 7.184 7.003 8.197 0.361 %0 300 QR -- -- RD RA -- -- NOERROR
1444.2.2.1 7.040 6.994 7.171 0.052 %0 299 QR -- -- RD RA -- -- NOERROR
1454.2.2.2 14.358 6.968 79.964 23.052 %0 300 QR -- -- RD RA -- -- NOERROR
1464.2.2.3 7.083 6.945 7.265 0.091 %0 299 QR -- -- RD RA -- -- NOERROR
1474.2.2.4 7.103 6.990 7.238 0.086 %0 299 QR -- -- RD RA -- -- NOERROR
1484.2.2.5 7.100 7.025 7.267 0.074 %0 299 QR -- -- RD RA -- -- NOERROR
14980.80.80.80 149.924 53.310 247.395 97.311 %0 299 QR -- -- RD RA AD -- NOERROR
15080.80.81.81 144.262 53.360 252.564 97.759 %0 298 QR -- -- RD RA AD -- NOERROR
1518.8.4.4 9.196 7.160 10.974 1.484 %0 299 QR -- -- RD RA AD -- NOERROR
1528.8.8.8 7.847 7.056 9.866 0.836 %0 299 QR -- -- RD RA AD -- NOERROR
1532001:4860:4860::8844 31.819 7.194 155.761 50.671 %0 299 QR -- -- RD RA AD -- NOERROR
1542001:4860:4860::8888 7.773 7.200 9.814 0.777 %0 298 QR -- -- RD RA AD -- NOERROR
1559.9.9.9 21.894 6.670 81.434 30.299 %0 300 QR -- -- RD RA AD -- NOERROR
1562620:fe::fe 21.177 6.723 80.046 30.062 %0 300 QR -- -- RD RA AD -- NOERROR
157```
158
159### Author
160
161Babak Farrokhi
162
163- twitter: [@farrokhi](https://twitter.com/farrokhi)
164- github: [github.com/farrokhi](https://github.com/farrokhi/)
165- website: [farrokhi.net](https://farrokhi.net/)
166
167
168### License
169
170dnsdiag is released under a 2 clause BSD license.
171