dnstest – skrypt do testowania DNS i walidacji list domen dla Pi-hole i AdGuard

dnstest to narzędzie wiersza poleceń napisane w Pythonie, przeznaczone do testowania i walidowania list domen, używanych powszechnie przez blokery reklam na poziomie DNS, takie jak Pi-hole czy AdGuard. Program umożliwia pobieranie list domen z plików lokalnych, zdalnych URL-i oraz plików zawierających wiele adresów URL, walidację ich formatu, a następnie testy rozpoznawania DNS i pingi ICMP.

GitHub: github.com/IgorBrzezek/dnstest

Do czego służy dnstest?

dnstest rozwiązuje problem weryfikacji działania list blokujących używanych w sieci. Administratorzy Pi-hole czy AdGuard często korzystają z list zewnętrznych zawierających domeny reklamowe, śledzące lub złośliwe. Zanim taka lista trafi do użycia, dobrze jest sprawdzić jej poprawność strukturalną oraz to, czy domeny w niej zawarte faktycznie rozpoznawane są jako zablokowane. Program przydaje się w wielu scenariuszach:

• Walidacja list blokujących – sprawdzenie składni listy przed zaaplikowaniem.
• Testowanie skuteczności blokowania – określenie, które domeny są blokowane (0.0.0.0), a które nadal są rozpoznawane.
• Porównywanie resolverów – sprawdzenie, który serwer DNS odpowiedział na zapytanie (z opcją –showdns).
• Pomiar czasu odpowiedzi – pingowanie domen w celu sprawdzenia szybkości łącza.
• Zautomatyzowane monitorowanie – tryb cichy –batch pozwala na użycie skryptu w cronie lub innych skryptach.

Jak to działa – mechanizm wewnętrzny

dnstest wczytuje listę domen z wybranego źródła (plik lokalny, URL lub plik z listą URL-i), po czym dla każdej domeny wykonuje następujące kroki:

1. Sprawdza poprawność linii za pomocą wyrażeń regularnych – akceptuje formaty 0.0.0.0 domena.pl oraz domena.pl.
2. Wykonuje zapytanie DNS za pomocą biblioteki socket lub dnspython (jeśli jest zainstalowana).
3. Dla adresów IP różnych od 0.0.0.0 wykonuje próbę ping ICMP o zadanej liczbie powtórzeń.
4. Podsumowuje statystyki: liczba domen zablokowanych, rozpoznanych, nieosiągalnych oraz czas odpowiedzi.
5. Zapisuje statystyki użycia resolverów DNS – który serwer DNS ile zapytań obsłużył.

Całość obsługiwana jest z poziomu wiersza poleceń, a wyniki mogą być wyświetlane na konsoli, zapisywane do pliku, lub jedno i drugie. Program obsługuje ograniczanie szybkości zapytań (--rate), dzięki czemu można uniknąć blokowania przez serwery DNS przy testowaniu dużych list.

Wymagania

• Python 3.x
• Biblioteka requests (pip install requests)
• Biblioteka colorama – opcjonalnie, dla kolorowego wyjścia w terminalu Windows (pip install colorama)
• Biblioteka dnspython – opcjonalnie, dla dokładnego wykrywania resolvera DNS w opcji –showdns (pip install dnspython)

Instalacja i uruchomienie

Pobierz plik z repozytorium GitHub i uruchom bezpośrednio z poziomu Pythona:

pip install requests colorama dnspython
python dnstest.py [opcje]

Opcje wiersza poleceń – szczegółowy opis

Opcja	Opis	Uwagi
-h	Krótka pomoc	–
--help	Pełna dokumentacja z przykładami i metadanymi	–
-i PLIK	Ładuj listę domen z pliku lokalnego	Wymagana, jeśli nie podano -u ani –list
-u URL	Ładuj listę domen ze zdalnego adresu URL	HTTP lub HTTPS
--list PLIK	Ładuj plik zawierający listę URL-i do list domen	Jeden URL na linię
-p N	Wykonaj N prób pingów dla każdej domeny	Wyświetla statystyki
-d	Sprawdź tylko rozpoznawanie DNS (bez pingów)	Wynik: RESOLVED / NO DNS NAME / BLOCKED
--check [stat]	Tylko walidacja struktury listy	Dodaj stat dla pełnego raportu
-w PLIK	Zapisz wyniki do pliku	Pyta przed nadpisaniem
--overwrite	Nadpisuj plik bez pytania	Działa z -w
-b, --batch	Tryb cichy – bez wyświetlania na konsoli	Automatycznie włącza –overwrite
--live	Z -p: na żywo wyświetla wyniki pingów	Dla -d jest domyślne
--rate X[s/m]	Ogranicz szybkość zapytań do X na sekundę/minutę	Np. 10s lub 600m
--noip	Traktuj 0.0.0.0 jako poprawne rozpoznanie DNS	Domyślnie 0.0.0.0 = BLOCKED
--showdns	Wyświetl adres IP serwera DNS udzielającego odpowiedzi	Wymaga dnspython
--color	Włącz kolorowe wyjście ANSI	Lepsza czytelność wyniku

Ograniczanie szybkości zapytań – opcja –rate

Przy testowaniu dużych list domen (nawet kilkudziesięciu tysięcy wpisów) istnieje ryzyko, że serwer DNS uzna aktywność za atak i zablokuje adres IP. Opcja --rate pozwala ograniczyć liczbę zapytań na jednostkę czasu:

• --rate 10s – 10 zapytań na sekundę.
• --rate 600m – 600 zapytań na minutę (czyli 10 na sekundę).
• Domyślnie (0) – maksymalna prędkość, bez ograniczeń.

Program automatycznie oblicza i wyświetla przewidywany czas trwania testu przed jego rozpoczęciem.

Obsługa adresu 0.0.0.0 – opcja –noip

W listach blokujących domeny złośliwe często mają przypisany adres 0.0.0.0, co oznacza, że są zablokowane. Domyślnie dnstest traktuje taki adres jako BLOCKED i nie zalicza go do udanych rozpoznań DNS. Jeśli jednak chcesz, aby adres 0.0.0.0 był uznawany za poprawny wynik rozpoznania (np. przy testowaniu, czy lista w ogóle działa), użyj opcji --noip.

Statystyki resolverów DNS – opcja –showdns

Włączenie opcji --showdns powoduje wyświetlenie w dodatkowej kolumnie adresu IP serwera DNS, który udzielił odpowiedzi na zapytanie o każdą domenę. Jest to możliwe dzięki bibliotece dnspython. Jeśli nie jest ona zainstalowana, program wyświetli napis „System Default”. Na końcu testu program prezentuje zbiorcze statystyki użycia resolverów – który serwer ile zapytań obsłużył i jaki to procent wszystkich zapytań.

Walidacja listy domen – opcja –check

Opcja --check pozwala na sprawdzenie struktury listy domen bez wykonywania testów DNS. Program akceptuje dwa formaty:

• IP/Domena: 0.0.0.0 przyklad.pl – adres IP, spacja, nazwa domeny.
• Sama domena: przyklad.pl – tylko nazwa domeny.

Linie zaczynające się od # są traktowane jako komentarze i pomijane. Użycie --check stat wyświetla szczegółowe statystyki: liczbę linii ogółem, komentarzy, poprawnych wpisów (z podziałem na format IP/domena i domena tylko) oraz błędów. W przypadku wykrycia błędnych linii program wyświetla ich numery i treść.

Zapisywanie wyników do pliku i tryb wsadowy

Opcja -w PLIK zapisuje pełne wyniki testu do pliku. Domyślnie program pyta o zgodę na nadpisanie istniejącego pliku. Flaga --overwrite pomija to pytanie.

Tryb -b lub --batch wyłącza całkowicie wyświetlanie na konsoli (poza krytycznymi błędami) i automatycznie włącza --overwrite jeśli użyto -w. Jest to idealne rozwiązanie do użycia skryptu w cronie, skryptach powłoki czy innych zautomatyzowanych środowiskach.

Przykłady użycia

1. Walidacja lokalnej listy domen z pełnymi statystykami

python dnstest.py -i /sciezka/do/lista.txt --check stat

2. Test rozpoznawania DNS dla zdalnej listy z zapisem do pliku

python dnstest.py -u https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts -d -w wyniki.txt --color

3. Pingowanie każdej domeny 3 razy z ograniczeniem do 10 zapytań na sekundę

python dnstest.py -i domeny.txt -p 3 --rate 10s --live

4. Przetworzenie pliku z listą URL-i, 2 pingi na domenę, zapis do pliku

python dnstest.py --list /sciezka/do/adresy_url.txt -p 2 -w wyniki_laczone.log --overwrite

5. Wyświetlenie adresów IP serwerów DNS podczas testu

python dnstest.py -i domeny.txt -d --showdns --color

6. Test DNS z opcją –noip, aby 0.0.0.0 liczyć jako sukces

python dnstest.py -u https://hole.cert.pl/domains/domains.txt -d --noip

7. Tryb cichy dla automatyzacji (np. cron)

python dnstest.py -i domeny.txt -p 2 -b -w raport.log

Formaty plików wejściowych

dnstest akceptuje dwa formaty linii w plikach wejściowych:

Format	Przykład	Opis
IP/Domena	0.0.0.0 example.com	Standardowy format pliku hosts
Sama domena	example.com	Zwykła lista domen
Komentarz	# To jest komentarz	Linie zaczynające się od # są pomijane

Zatrzymywanie programu

Wciśnij Ctrl+C w oknie terminala. Program wyświetli podsumowanie dotychczas wykonanych testów, liczbę przetworzonych domen oraz statystyki resolverów DNS, po czym zakończy działanie.

Podsumowanie

dnstest to funkcjonalne narzędzie dla każdego, kto administruje blokowaniem reklam na poziomie DNS za pomocą Pi-hole, AdGuard lub podobnych rozwiązań. Dzięki obsłudze wielu źródeł danych (pliki lokalne, zdalne URL-e, listy URL-i), walidacji struktury, testom rozpoznawania DNS, pingom ICMP, ograniczaniu szybkości zapytań i elastycznym opcjom wyjścia (konsola, plik, tryb cichy), program sprawdzi się zarówno w codziennej pracy, jak i w zautomatyzowanych procesach monitorowania.

Dodatkowo statystyki resolverów DNS umożliwiają analizę tego, które serwery DNS są używane i w jakim stopniu, co może być przydatne przy diagnostyce sieci. Obsługa opcji --color znacząco poprawia czytelność wyników w terminalu.

Źródła: github.com/IgorBrzezek/dnstest