DNSGuard

March 18, 2026

GitHub Repository

DNSGuard is a lightweight DNS filtering service designed to block known advertising and risky domains at the DNS layer.

What it does

• Listens for DNS queries on configurable host/port (default localhost:53).
• Parses requests and checks domains against a blacklist.
• Resolves and forwards allowed queries, while blocked entries are denied by policy.
• Reloads blacklist data automatically when blacklist files are modified.

How it is built

• UDP DNS server loop in DNSGuard.py handles packet parse, policy check, and response writeback.
• Domain policy lives in blacklist.py with n-gram style suffix matching.
• Uses filesystem watch events to refresh blacklist data without restart.
• Includes ops scripts for install, log rotation copy/remove, and optional S3 log upload testing.

Tech stack

Python, dnslib, dnspython, pyinotify, Linux ops scripts.