⚡ DNS Benchmarking Tool

A high-performance Python analytics suite for benchmarking filtered DNS services.
Measure block rates, latency, accuracy, and cache performance across dozens of providers.

Features • Quick Start • Workflows • CLI Reference • Metrics

---

🚀 Features

• 🌐 Multi-Protocol Support — Native support for UDP, TCP, DNS over HTTPS (DoH), and DNS over TLS (DoT).
• 🛡️ 50+ DNS Services — Pre-configured providers including Cloudflare, Google, Quad9, AdGuard, NextDNS, and more.
• 🚫 Automated Blocklists — Auto-fetch from GitHub sources: StevenBlack, hagezi, OISD, AdGuard, Phishing Army.
• 📊 Comprehensive Metrics — Block rate, False Positive rate, Precision, Recall, F1 score, Latency percentiles.
• 📈 Advanced Visualization — Generate interactive HTML reports containing:
  • Radar Charts for multi-metric service comparison.
  • Protocol Comparison (UDP vs DoH vs DoT).
  • Error Rate Analysis & Success Distribution.
• ⚡ Cache Analytics — Measure DNS cache hit rates, latency speedup (ms/%), and efficiency.
• 🚀 Async Engine — Built on asyncio for high-concurrency queries with per-service rate limiting.

---

⚡ Quick Start

Installation

git clone https://github.com/DNSdecoded/ResolverLab.git
cd dns_benchmarking
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windowssource venv/bin/activate # Linux/macOS# Install dependencies
pip install -e .# Optional: Install kaleido for static PNG chart export
pip install "kaleido<=0.2.1"

Basic Usage

# 1. Fetch blocklists
python dns_benchmark.py fetch blocklists
# 2. Run quick test (10 domains)
python dns_benchmark.py test --quick
# 3. Open the generated HTML report in 'reports/'

---

🛠 Usage Workflows

Goal	Command
🚫 Ads	python dns_benchmark.py test --categories ads --domains 200
🔒 Security	python dns_benchmark.py test --categories malware --domains 500
👨‍👩‍👧 Family	python dns_benchmark.py test --categories adult gambling --domains 100
🏎 Speed	python dns_benchmark.py test --services "Cloudflare" "Google" --domains 50

Workflow 1: Compare Ad-Blocking DNS Services

Find the best ad-blocking DNS for your network:

python dns_benchmark.py fetch blocklists --categories ads
python dns_benchmark.py test \
--categories ads \
--domains 200 \
--services "AdGuard DNS""NextDNS""Mullvad Ad Block"

Workflow 2: Protocol Performance Battle

Compare the speed and reliability of DoH vs UDP:

python dns_benchmark.py test \
--services "Cloudflare DNS""Cloudflare DoH""Cloudflare DoT" \
--domains 100

> Check the "Protocol Comparison" chart in the generated HTML report.

Workflow 3: Full Stress Test

Test ALL services against ALL blocklists.

Warning

This scan performs thousands of queries and may take 10-20+ minutes depending on your connection.

python dns_benchmark.py fetch blocklists --all
python dns_benchmark.py test --all --domains 50
python dns_benchmark.py report generate --latest --format html json csv

---

📖 CLI Reference

📥 Blocklist Management

Command	Description
fetch blocklists	Download blocklists from configured sources
fetch blocklists --all	Fetch ALL configured categories
fetch blocklists --categories ads malware	Fetch specific categories
fetch blocklists --refresh	Force re-download (ignore cache)
fetch cache-info	Show cached blocklist information
fetch clear-cache	Delete cached blocklists

📡 DNS Services

Command	Description
services list	List all configured DNS services
services list --filtered-only	Show only filtered DNS services
services test "Quad9 Filtered" example.com	Test single query
services test "Google DoH" example.com -t AAAA	Test specific record type

🔥 Benchmark Execution

Command	Description
test	Run full benchmark with default settings
test --quick	Quick test (10 domains)
test --all	Scan All: Test ALL services against ALL blocklists
test --categories ads --domains 200	Custom benchmark
test --services "AdGuard DNS" "Quad9 Filtered"	Specific services
test --no-baseline	Skip baseline (unfiltered) comparison

📊 Reports & Analysis

Command	Description
report list	List previous benchmark runs
report generate --run-id 5	Regenerate report from database
report generate --latest --format html json	Latest run, multiple formats
report generate --latest --no-charts	Generate report without charts
compare --baseline "Google" --targets "Quad9"	Compare services directly

---

📉 Metrics Explained

Metric	Formula	Description
Block Rate	blocked / total	Percentage of blocklist domains blocked
False Positive Rate	FP / (FP + TN)	Legitimate domains incorrectly blocked (Lower is better)
Precision	TP / (TP + FP)	Accuracy of blocks (Low FP means High Precision)
F1 Score	2 * (P * R) / (P + R)	Harmonic mean of precision and recall
Cache Hit Rate	improved / eligible	% of queries served faster than the baseline
Cache Speedup	baseline - latency	Latency saved by using the cache (ms and %)
Error Rate	errors / total	% of queries that failed (Timeout, Connection Refused)

---

📂 Project Structure

dns_benchmarking/
├── config/ # ⚙️ Configuration
│ └── config.yaml
├── data/ # 💾 SQLite DB & Cache
├── reports/ # 📄 Generated Reports
└── src/
├── blocklist/ # List management
├── dns/ # Protocol engines (UDP/TCP/DoH/DoT)
├── testing/ # Benchmark logic
├── reporting/ # Charts & HTML generation
└── utils/ # Helpers

---

⬆ Back to Top