Skip to content

example-usage.md

Latest commit

 

History

History
527 lines (402 loc) · 12 KB

example-usage.md

File metadata and controls

527 lines (402 loc) · 12 KB
Raw

Example Usage

Complete examples for all CLI commands with full syntax.

Table of Contents

Blocklist Commands

Fetch Blocklists

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

# Specific categories
python dns_benchmark.py fetch blocklists --categories ads
python dns_benchmark.py fetch blocklists --categories ads --categories malware
python dns_benchmark.py fetch blocklists --categories ads --categories malware --categories tracking

# All categories
python dns_benchmark.py fetch blocklists --all

# Force refresh (ignore cache)
python dns_benchmark.py fetch blocklists --refresh
python dns_benchmark.py fetch blocklists --categories ads --refresh

# Dry run (preview only)
python dns_benchmark.py fetch blocklists --dry-run
python dns_benchmark.py fetch blocklists --all --dry-run

Cache Management

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

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

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

Service Commands

List Services

# All services
python dns_benchmark.py services list

# Filtered only
python dns_benchmark.py services list --filtered-only

# Unfiltered only
python dns_benchmark.py services list --unfiltered-only

Test Single Query

# Basic query
python dns_benchmark.py services test "Google DNS" google.com
python dns_benchmark.py services test "Quad9 Filtered" facebook.com
python dns_benchmark.py services test "AdGuard DNS" ads.google.com

# With query type
python dns_benchmark.py services test "Google DNS" google.com --query-type A
python dns_benchmark.py services test "Google DNS" google.com --query-type AAAA
python dns_benchmark.py services test "Google DNS" google.com --query-type MX
python dns_benchmark.py services test "Google DNS" google.com --query-type TXT

# Test DoH services
python dns_benchmark.py services test "Cloudflare DoH" example.com
python dns_benchmark.py services test "Google DoH" example.com

# Test DoT services
python dns_benchmark.py services test "Quad9 DoT" example.com
python dns_benchmark.py services test "AdGuard DoT" example.com

Benchmark Commands

Quick Test

# Quick test (10 domains)
python dns_benchmark.py test --quick

# Quick test with scan all
python dns_benchmark.py test --quick --scan-all

Standard Benchmark

# Full default benchmark
python dns_benchmark.py test

# Scan all services and categories
python dns_benchmark.py test --scan-all
python dns_benchmark.py test --scan-all --domains 50

Custom Categories

# Single category
python dns_benchmark.py test --categories ads

# Multiple categories
python dns_benchmark.py test --categories ads --categories malware
python dns_benchmark.py test --categories ads --categories malware --categories tracking
python dns_benchmark.py test --categories adult --categories gambling

# Short form
python dns_benchmark.py test -cat ads -cat malware

Custom Services

# Single service
python dns_benchmark.py test --services "AdGuard DNS"

# Multiple services
python dns_benchmark.py test --services "AdGuard DNS" --services "Quad9 Filtered"
python dns_benchmark.py test --services "AdGuard DNS" --services "Quad9 Filtered" --services "Cloudflare Family"

# Short form
python dns_benchmark.py test -s "AdGuard DNS" -s "Quad9 Filtered"

Custom Domain Count

# 50 domains per category
python dns_benchmark.py test --domains 50
python dns_benchmark.py test -n 50

# 200 domains per category
python dns_benchmark.py test --domains 200

# 500 domains per category
python dns_benchmark.py test --domains 500

Skip Options

# Skip baseline comparison
python dns_benchmark.py test --no-baseline

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

# Skip both
python dns_benchmark.py test --no-baseline --no-legitimate

Output Formats

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

# JSON only
python dns_benchmark.py test --output-format json
python dns_benchmark.py test -f json

# Multiple formats
python dns_benchmark.py test -f html -f json
python dns_benchmark.py test -f html -f json -f csv

# All formats
python dns_benchmark.py test -f html -f json -f csv -f md

Complete Examples

# Ad blocker benchmark
python dns_benchmark.py test \
    --categories ads \
    --categories tracking \
    --services "AdGuard DNS" \
    --services "NextDNS" \
    --services "Mullvad Ad Block" \
    --domains 200 \
    -f html -f json

# Family DNS benchmark
python dns_benchmark.py test \
    --categories adult \
    --categories gambling \
    --services "AdGuard Family" \
    --services "CleanBrowsing Family" \
    --services "OpenDNS FamilyShield" \
    --services "Cloudflare Family" \
    --domains 100 \
    -f html

# Security benchmark
python dns_benchmark.py test \
    --categories malware \
    --services "Quad9 Filtered" \
    --services "Cloudflare Malware Only" \
    --services "CleanBrowsing Security" \
    --domains 500 \
    -f html -f json

# DoH benchmark
python dns_benchmark.py test \
    --services "Cloudflare DoH" \
    --services "Google DoH" \
    --services "Quad9 DoH" \
    --services "AdGuard DoH" \
    --categories ads \
    --categories malware \
    --domains 100 \
    -f html

# Full comprehensive scan
python dns_benchmark.py test \
    --scan-all \
    --domains 50 \
    -f html -f json -f csv

Compare Commands

Basic Comparison

# Compare against Google DNS
python dns_benchmark.py compare \
    --baseline "Google DNS" \
    --targets "Quad9 Filtered"

# Short form
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "Quad9 Filtered"

Multiple Targets

# Compare multiple services
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "Quad9 Filtered" \
    -t "AdGuard DNS"

python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "Quad9 Filtered" \
    -t "AdGuard DNS" \
    -t "Cloudflare Family"

python dns_benchmark.py compare \
    -b "Cloudflare DNS" \
    -t "AdGuard Family" \
    -t "CleanBrowsing Family" \
    -t "OpenDNS FamilyShield"

With Categories

# Ad blocking comparison
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "AdGuard DNS" \
    -t "NextDNS" \
    --categories ads

# Security comparison
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "Quad9 Filtered" \
    -t "Cloudflare Malware Only" \
    --categories malware

# Family DNS comparison
python dns_benchmark.py compare \
    -b "Cloudflare DNS" \
    -t "AdGuard Family" \
    -t "CleanBrowsing Family" \
    --categories adult \
    --categories gambling

With Domain Count

python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "AdGuard DNS" \
    --categories ads \
    --domains 200

python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "Quad9 Filtered" \
    --categories malware \
    --domains 500

Report Commands

List Runs

# Default (last 10)
python dns_benchmark.py report list

# More history
python dns_benchmark.py report list --limit 25
python dns_benchmark.py report list --limit 50
python dns_benchmark.py report list --limit 100

Generate Reports

# From specific run ID
python dns_benchmark.py report generate --run-id 1
python dns_benchmark.py report generate --run-id 5
python dns_benchmark.py report generate --run-id 10

# From latest run
python dns_benchmark.py report generate --latest

# With format
python dns_benchmark.py report generate --run-id 5 --format html
python dns_benchmark.py report generate --run-id 5 --format json
python dns_benchmark.py report generate --latest --format html

# Multiple formats
python dns_benchmark.py report generate --run-id 5 -f html -f json
python dns_benchmark.py report generate --latest -f html -f json -f csv

# With charts
python dns_benchmark.py report generate --run-id 5 --format html --charts
python dns_benchmark.py report generate --latest -f html -f json --charts

Complete Workflows

Workflow 1: First Time Setup

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

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

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

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

# 5. View cache info
python dns_benchmark.py fetch cache-info

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

# 7. View reports
dir reports\                 # Windows
ls reports/                  # Linux/macOS

Workflow 2: Ad Blocker Evaluation

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

# 2. Test ad-blocking services
python dns_benchmark.py test \
    --categories ads \
    --categories tracking \
    --services "AdGuard DNS" \
    --services "NextDNS" \
    --services "Mullvad Ad Block" \
    --services "Control D Ads & Tracking" \
    --domains 200 \
    -f html -f json

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

Workflow 3: Family DNS Evaluation

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

# 2. Test family 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 \
    -f html

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

Workflow 4: Security Testing

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

# 2. Test security DNS
python dns_benchmark.py test \
    --categories malware \
    --services "Quad9 Filtered" \
    --services "Cloudflare Malware Only" \
    --services "CleanBrowsing Security" \
    --domains 500 \
    -f html -f json

# 3. Compare protection
python dns_benchmark.py compare \
    -b "Google DNS" \
    -t "Quad9 Filtered" \
    -t "Cloudflare Malware Only" \
    --categories malware \
    --domains 300

Workflow 5: Full Comprehensive Scan

# 1. Fetch all blocklists
python dns_benchmark.py fetch blocklists --all

# 2. Run full scan (may take 10-30 minutes)
python dns_benchmark.py test --scan-all --domains 50

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

# 4. View results
start reports\report_*.html  # Windows
open reports/report_*.html   # macOS

Workflow 6: Historical Analysis

# 1. List all previous runs
python dns_benchmark.py report list --limit 50

# 2. Regenerate report from specific run
python dns_benchmark.py report generate --run-id 5 --format html --charts

# 3. Export to multiple formats
python dns_benchmark.py report generate --run-id 5 -f html -f json -f csv

Global Options

# Verbose mode (debug logging)
python dns_benchmark.py --verbose test --quick
python dns_benchmark.py --verbose fetch blocklists

# Custom config file
python dns_benchmark.py --config path/to/config.yaml test
python dns_benchmark.py --config custom.yaml fetch blocklists

# Help
python dns_benchmark.py --help
python dns_benchmark.py test --help
python dns_benchmark.py fetch --help
python dns_benchmark.py compare --help
python dns_benchmark.py report --help