How udayk01/securedns works
What this project is (type + purpose)
SecureDNS is a single-process Python DNS server that:
• Listens for DNS queries (typically UDP/53),
• Checks queried domains against a remote blocklist (downloaded via requests),
• Responds with a blocked IP for blocked domains,
• Otherwise forwards the query to an upstream resolver and returns the response,
• Uses caching and some concurrency to improve throughput/latency.
How to read the file structure (and what it implies architecturally)
File tree:
• main.py → all runtime logic is here (DNS server, parsing, cache, forwarding, blocklist loading).
• README.md → documents configuration constants (HOST/PORT/BLOCKED_IP), remote blocklist, performance goals.
DNS Clients
Devices/apps sending DNS queries (OS resolver, browsers, routers, etc.)
Network / OS
UDP socket on port 53 (and possibly TCP/53 if implemented—verify in main.py).
Inside a big “SecureDNS (Python process)” container, split into:
DNS Listener / Server Loop
• Binds to HOST:PORT
• Receives packets
• Dispatches to worker/concurrency mechanism
Concurrency / Request Dispatcher
• Thread pool / asyncio tasks / per-request thread (depends on main.py)
DNS Message Parser/Serializer
• Parses DNS query to extract QNAME, QTYPE, etc.
• Constructs DNS responses (either blocked response or upstream response)
Domain Normalizer
• Canonicalization: lowercase, trailing dot handling, subdomain logic
• Important because blocklists and DNS queries vary in representation
Blocklist Manager
• Remote fetcher using requests
• Parser for hosts-format list
• In-memory set/trie/hash structure of blocked domains
• Update strategy: on startup, periodic refresh, manual refresh (depends on code)
Decision Engine (Allow vs Block)
• If domain matches blocklist => synthesize “blocked” DNS answer (A/AAAA?) pointing to BLOCKED_IP or 0.0.0.0
• If allowed => forward upstream
Cache
• Positive cache: domain -> response (respect TTL if implemented)
• Possibly negative cache
• Eviction policy (LRU/size/time) if present
• Cache lookup should appear *before* upstream forwarding in the flow
Upstream Resolver / Forwarder
• Sends query to external DNS (e.g., 8.8.8.8 or system resolver)
• Receives response and returns it to client
• This can be a UDP client socket separate from listener socket
Observability (Logging/Metrics)
• Even if it’s just logging, include it as a sidecar component: request logs, blocked counts, cache hit rate, errors fetching blocklist.
Remote Blocklist Source
• Steven Black Unified Hosts file URL (external HTTP(S) endpoint)
Upstream DNS Resolver
• Public DNS / enterprise resolver / ISP resolver
Worker → Cache lookup
• Cache hit: return cached response → Serializer → Client
If cache miss: Worker → Blocklist check
• Blocked: synthesize response with BLOCKED_IP → Serializer → Client
• Allowed: forward to Upstream Resolver → receive response → store in Cache → Serializer → Client
Flow 2: Blocklist acquisition (control path)
SecureDNS Blocklist Manager → (HTTP GET via requests) → Remote Blocklist Source
Then parse → update in-memory blocked-domain structure.
SecureDNS components → Logs/Metrics (stdout/file/metrics endpoint—whatever exists)
Include:
• DNS Clients
• SecureDNS (Python process)
• Remote Blocklist Source (HTTP)
• Upstream DNS Resolver (DNS)
Client → Listener → Worker → Parser → Cache → Blocklist → Forwarder → Upstream → back → Cache store → Client
An alternate branch for “Blocked domain”.
Notes to ensure you don’t miss important details (given the minimal repo)
• UDP only or UDP+TCP
• Upstream resolver address selection
• Cache: TTL-aware or naive; max size; eviction
• Blocklist refresh cadence (startup-only vs periodic timer/thread)
• Exact “blocked response” behavior (A only? NXDOMAIN? 0.0.0.0? configurable)
• Concurrency mechanism (threading vs asyncio vs multiprocessing)