DNS Benchmarking Tool - Example Usage

Comprehensive usage guide with practical examples for all CLI commands and workflows.

Quick Start
Blocklist Management
DNS Service Operations
Benchmarking
Service Comparison
Report Management
Common Workflows
Configuration Reference
Advanced Usage
Output Reference

Quick Start

# 1. Activate virtual environment
venv\Scripts\activate        # Windows
source venv/bin/activate     # Linux/Mac

# 2. Verify installation
python dns_benchmark.py --help

# 3. Fetch blocklists
python dns_benchmark.py fetch blocklists

# 4. Run quick test
python dns_benchmark.py test --quick

# 5. View reports in reports/ directory

Blocklist Management

Fetch Blocklists

# Fetch default categories (ads, malware, adult, gambling)
python dns_benchmark.py fetch blocklists

# Fetch specific categories
python dns_benchmark.py fetch blocklists --categories ads --categories malware

# Fetch all available categories
python dns_benchmark.py fetch blocklists --all

# Force refresh cache (bypass 24-hour expiry)
python dns_benchmark.py fetch blocklists --refresh

# Dry run - preview what would be downloaded
python dns_benchmark.py fetch blocklists --dry-run

Available Categories

Category	Description	Sources
`ads`	Advertising domains	StevenBlack, AdGuard, OISD, hagezi
`malware`	Malware & phishing	URLhaus, Phishing Army, ThreatFox
`adult`	Adult content	StevenBlack Porn, BlocklistProject
`gambling`	Gambling sites	StevenBlack, BlocklistProject
`tracking`	Trackers & analytics	EasyPrivacy, hagezi TIF

Cache Operations

# View cache statistics and blocklist info
python dns_benchmark.py fetch cache-info

# Clear all cached blocklists
python dns_benchmark.py fetch clear-cache

# Clear specific category cache
python dns_benchmark.py fetch clear-cache --categories ads

DNS Service Operations

List Configured Services

# Show all configured DNS services
python dns_benchmark.py services list

# Show only filtered DNS services
python dns_benchmark.py services list --filtered-only

# Show only unfiltered (baseline) services
python dns_benchmark.py services list --unfiltered-only

Test Individual Queries

# Test if a service blocks a domain
python dns_benchmark.py services test "Quad9 Filtered" facebook.com

# Test with specific query type (A, AAAA, CNAME, MX, TXT)
python dns_benchmark.py services test "AdGuard DNS" tracker.example.com --query-type AAAA

# Test against ad domain
python dns_benchmark.py services test "AdGuard DNS" ads.google.com

# Test against unfiltered baseline
python dns_benchmark.py services test "Google DNS" ads.google.com

Available DNS Services

Unfiltered (Baseline)

Google DNS (8.8.8.8) - UDP
Cloudflare DNS (1.1.1.1) - UDP
Quad9 Unfiltered (9.9.9.10) - UDP
Cloudflare DoH - DNS over HTTPS

Filtered Services

Cloudflare Family (1.1.1.3) - Blocks malware + adult
Cloudflare Malware Only (1.1.1.2) - Blocks malware
Quad9 Filtered (9.9.9.9) - Blocks malware + phishing
AdGuard DNS (94.140.14.14) - Blocks ads + trackers
AdGuard Family (94.140.14.15) - Blocks ads + trackers + adult
CleanBrowsing Family (185.228.168.168) - Family filter
OpenDNS FamilyShield (208.67.222.123) - Adult filter
Control D (76.76.2.0) - Multiple filter options
Mullvad DNS (194.242.2.3) - Privacy + ad blocking
NextDNS (45.90.28.0) - Configurable filtering
DNS0.eu (193.110.81.0) - GDPR compliant

IPv6 Services

Google DNS IPv6 (2001:4860:4860::8888)
Cloudflare IPv6 (2606:4700:4700::1111)
Quad9 Filtered IPv6 (2620:fe::fe)
AdGuard Family IPv6 (2a10:50c0::bad1:ff)

Benchmarking

Quick Test

# Fast test with 10 domains (for verification)
python dns_benchmark.py test --quick

# Quick test with ALL servers and ALL categories
python dns_benchmark.py test --all --quick

Standard Benchmark

# Run full benchmark with defaults
# - 100 domains per category
# - All default categories (ads, malware, adult, gambling)
# - All filtered services
# - Baseline comparison enabled
# - False positive testing enabled
python dns_benchmark.py test

Custom Benchmark Configurations

# Test specific categories only
python dns_benchmark.py test --categories ads --categories malware

# Test specific services only
python dns_benchmark.py test --services "Quad9 Filtered" --services "AdGuard DNS"

# Test with more domains per category
python dns_benchmark.py test --domains 200

# Skip baseline comparison (faster, fewer queries)
python dns_benchmark.py test --no-baseline

# Skip false positive testing
python dns_benchmark.py test --no-legitimate

# Comprehensive scan: ALL DNS servers × ALL blocklist categories
python dns_benchmark.py test --all

# Quick comprehensive scan (10 domains per category)
python dns_benchmark.py test --all --quick

Output Format Options

# Generate HTML report only
python dns_benchmark.py test --output-format html

# Generate multiple formats
python dns_benchmark.py test --output-format html --output-format json --output-format csv

# All format options: html, json, csv, md
python dns_benchmark.py test -f html -f json -f csv -f md

Complete Benchmark Example

# Full custom benchmark with all options
python dns_benchmark.py test \
    --categories ads \
    --categories malware \
    --categories tracking \
    --services "Quad9 Filtered" \
    --services "AdGuard DNS" \
    --services "Cloudflare Family" \
    --domains 150 \
    --output-format html \
    --output-format json

CLI Options Reference

Option	Short	Default	Description
`--categories`	`-cat`	All default	Categories to test
`--services`	`-s`	All filtered	Specific services to test
`--domains`	`-n`	100	Domains per category
`--no-baseline`		False	Skip baseline comparison
`--no-legitimate`		False	Skip false positive testing
`--quick`		False	Quick test (10 domains)
`--all`		False	Test ALL DNS servers with ALL categories
`--output-format`	`-f`	html, json	Report formats

Service Comparison

Compare Against Baseline

# Compare filtered services against Google DNS baseline
python dns_benchmark.py compare -b "Google DNS" -t "Quad9 Filtered" -t "AdGuard DNS"

# Compare with Cloudflare as baseline
python dns_benchmark.py compare -b "Cloudflare DNS" -t "Cloudflare Family" -t "OpenDNS FamilyShield"

# Compare multiple ad-blocking services
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "AdGuard DNS" \
    -t "NextDNS" \
    -t "Mullvad Ad Block"

Category-Specific Comparison

# Compare ad blocking effectiveness
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "AdGuard DNS" \
    -t "Quad9 Filtered" \
    --categories ads \
    --domains 200

# Compare family safety filters
python dns_benchmark.py compare \
    -b "Cloudflare DNS" \
    -t "AdGuard Family" \
    -t "CleanBrowsing Family" \
    -t "OpenDNS FamilyShield" \
    --categories adult \
    --categories gambling

Report Management

List Previous Runs

# Show last 10 benchmark runs
python dns_benchmark.py report list

# Show more history
python dns_benchmark.py report list --limit 25

# Show all runs
python dns_benchmark.py report list --limit 100

Regenerate Reports from History

# Generate report from specific run ID
python dns_benchmark.py report generate --run-id 5 --format html

# Generate from latest run
python dns_benchmark.py report generate --latest --format html

# Generate multiple formats with charts
python dns_benchmark.py report generate --run-id 5 --format html --format json --charts

# Generate all formats
python dns_benchmark.py report generate --latest --format html --format json --format csv --charts

Common Workflows

Workflow 1: First-Time Setup & Verification

# 1. Activate environment
venv\Scripts\activate

# 2. Check available services
python dns_benchmark.py services list

# 3. Fetch all blocklists
python dns_benchmark.py fetch blocklists

# 4. View blocklist cache info
python dns_benchmark.py fetch cache-info

# 5. Run quick test to verify setup
python dns_benchmark.py test --quick

# 6. Check generated reports
dir reports\

Workflow 2: Regular Benchmarking Session

# 1. Refresh blocklists (if needed)
python dns_benchmark.py fetch blocklists --refresh

# 2. Run comprehensive benchmark
python dns_benchmark.py test --domains 150

# 3. View results in browser
start reports\benchmark_*.html

Workflow 3: Ad Blocker Evaluation

# 1. Fetch ad-specific blocklists
python dns_benchmark.py fetch blocklists --categories ads --categories tracking

# 2. Test ad-blocking services specifically
python dns_benchmark.py test \
    --categories ads \
    --categories tracking \
    --services "AdGuard DNS" \
    --services "NextDNS" \
    --services "Mullvad Ad Block" \
    --domains 200

# 3. Compare against unfiltered baseline
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "AdGuard DNS" \
    -t "NextDNS" \
    --categories ads

Workflow 4: Family Safety DNS Evaluation

# 1. Fetch family-relevant blocklists
python dns_benchmark.py fetch blocklists --categories adult --categories gambling

# 2. Test family-focused DNS services
python dns_benchmark.py test \
    --categories adult \
    --categories gambling \
    --services "AdGuard Family" \
    --services "CleanBrowsing Family" \
    --services "OpenDNS FamilyShield" \
    --services "Cloudflare Family" \
    --domains 100

# 3. Generate detailed comparison
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "AdGuard Family" \
    -t "CleanBrowsing Family" \
    -t "OpenDNS FamilyShield" \
    --categories adult

Workflow 5: Security-Focused Evaluation

# 1. Fetch malware/phishing blocklists
python dns_benchmark.py fetch blocklists --categories malware

# 2. Test security-focused DNS services
python dns_benchmark.py test \
    --categories malware \
    --services "Quad9 Filtered" \
    --services "Cloudflare Malware Only" \
    --services "CleanBrowsing Security" \
    --services "Comodo Secure" \
    --domains 200

Workflow 6: DoH (DNS over HTTPS) Testing

# Test encrypted DNS services
python dns_benchmark.py test \
    --services "Cloudflare DoH" \
    --services "Google DoH" \
    --services "Quad9 DoH" \
    --services "AdGuard DoH" \
    --categories ads \
    --categories malware

Configuration Reference

Configuration File

Edit config/config.yaml to customize:

# Test settings
test_settings:
  queries_per_domain: 3          # Queries per domain for stats
  query_timeout: 5               # Timeout in seconds
  max_concurrent: 50             # Concurrent query limit
  query_delay_ms: 10             # Delay between queries
  max_retries: 2                 # Retry attempts
  domains_per_category: 100      # Default domains per category
  false_positive_domains: 50     # Legitimate domains to test

# Report settings  
reporting:
  output_dir: "reports"
  default_formats: ["html", "json"]
  include_details: true
  charts:
    enabled: true
    theme: "plotly_dark"

# Cache settings
cache:
  blocklist_dir: "data/blocklists"
  expiry_hours: 24
  enabled: true

Verbose Mode

# Enable verbose logging for debugging
python dns_benchmark.py --verbose test --quick

# Use custom config file
python dns_benchmark.py --config path/to/custom-config.yaml test

Advanced Usage

Programmatic Usage (Python API)

from src.blocklist import BlocklistManager
from src.dns import DNSResolver, create_query_engine_from_config
from src.testing import BenchmarkRunner
from src.reporting import ReportGenerator

# Initialize components
blocklist_manager = BlocklistManager()
query_engine = create_query_engine_from_config()

# Load blocklists
blocklist_manager.load_blocklists_sync(categories=["ads", "malware"])

# Run benchmark
runner = BenchmarkRunner(blocklist_manager, query_engine)
results = runner.run_benchmark_sync(
    categories=["ads", "malware"],
    domains_per_category=100
)

# Generate reports
generator = ReportGenerator()
generator.generate(results, formats=["html", "json"])

Export Domains

from src.blocklist import BlocklistManager

manager = BlocklistManager()
manager.load_blocklists_sync(categories=["ads"])

# Export to file
manager.export_domains(
    output_file="data/ads_domains.txt",
    categories=["ads"],
    format="txt"  # txt, json, or csv
)

Query Engine Direct Usage

from src.dns import DNSResolver

async with DNSResolver() as resolver:
    # Query single service
    response = await resolver.query_by_name(
        domain="example.com",
        service_name="Quad9 Filtered"
    )
    print(f"Blocked: {response.is_blocked}")
    print(f"Latency: {response.latency_ms}ms")
    
    # Query all services
    results = await resolver.query_all_services(
        domain="ads.example.com",
        filtered_only=True
    )
    for name, response in results.items():
        print(f"{name}: {'Blocked' if response.is_blocked else 'Allowed'}")

Output Reference

Output Locations

Output Type	Location
HTML Reports	`reports/benchmark_YYYYMMDD_HHMMSS.html`
JSON Reports	`reports/benchmark_YYYYMMDD_HHMMSS.json`
CSV Reports	`reports/benchmark_YYYYMMDD_HHMMSS.csv`
Markdown Reports	`reports/benchmark_YYYYMMDD_HHMMSS.md`
Charts	`reports/charts/`
Database	`data/results.db`
Cached Blocklists	`data/blocklists/`
Logs	`data/dns_benchmark.log`

Metrics Explained

Metric	Description
Block Rate	% of blocklist domains blocked by the DNS service
False Positive Rate	% of legitimate domains incorrectly blocked
Accuracy	(True Positives + True Negatives) / Total
Precision	True Positives / (True Positives + False Positives)
Recall	True Positives / (True Positives + False Negatives)
Latency (avg)	Average response time in milliseconds
Latency (P95)	95th percentile response time

Troubleshooting

Common Issues

# If imports fail
pip install -r requirements.txt

# If blocklists fail to fetch
python dns_benchmark.py fetch blocklists --refresh

# If DNS queries timeout
# Edit config/config.yaml: increase query_timeout

# View debug output
python dns_benchmark.py --verbose test --quick

Verify Setup

# Check services are configured
python dns_benchmark.py services list

# Test single query
python dns_benchmark.py services test "Google DNS" google.com

# Check cache status
python dns_benchmark.py fetch cache-info

FilesExpand file tree

example_usage.md

Latest commit

History

example_usage.md

File metadata and controls

DNS Benchmarking Tool - Example Usage

Table of Contents

Quick Start

Blocklist Management

Fetch Blocklists

Available Categories

Cache Operations

DNS Service Operations

List Configured Services

Test Individual Queries

Available DNS Services

Benchmarking

Quick Test

Standard Benchmark

Custom Benchmark Configurations

Output Format Options

Complete Benchmark Example

CLI Options Reference

Service Comparison

Compare Against Baseline

Category-Specific Comparison

Report Management

List Previous Runs

Regenerate Reports from History

Common Workflows

Workflow 1: First-Time Setup & Verification

Workflow 2: Regular Benchmarking Session

Workflow 3: Ad Blocker Evaluation

Workflow 4: Family Safety DNS Evaluation

Workflow 5: Security-Focused Evaluation

Workflow 6: DoH (DNS over HTTPS) Testing

Configuration Reference

Configuration File

Verbose Mode

Advanced Usage

Programmatic Usage (Python API)

Export Domains

Query Engine Direct Usage

Output Reference

Output Locations

Metrics Explained

Troubleshooting

Common Issues

Verify Setup