A recursive DNS resolver built from scratch in Python.
It manually parses DNS packets, follows DNS referrals from root servers, caches responses, and serves DNS queries over UDP. It handles real DNS queries with caching, TCP fallback, and EDNS0 support.
- Full DNS Protocol Support — A, AAAA, CNAME, MX, NS, TXT records while preserving unsupported records
- Recursive Resolution — Starts from root servers and traverses TLD and authoritative name servers
- Smart Caching — TTL-aware with a thread-safe key-value store
- UDP + TCP Fallback — Automatically retries over TCP when UDP responses are truncated
- EDNS0 Support — Supports larger UDP packets and the DNSSEC OK (DO) bit
- Concurrent Processing — 64 worker threads using
ThreadPoolExecutor -
- Defensive Packet Parsing
- Compression-pointer loop detection
- Packet bounds checking
- DNS transaction ID validation
- Recursive lookup depth limits
- Request timeout handling
- Root Server Rotation — Automatically switches to another root server if one times out
┌─────────────────────┐
│ DNS Client │
│ dig / nslookup │
└──────────┬──────────┘
│
│ UDP :2053
▼
┌───────────────────────────────────┐
│ Local DNS Resolver │
│ │
│ ┌─────────────────────────────┐ │
│ │ UDP Server │ │
│ │ ThreadPoolExecutor │ │
│ └──────────────┬──────────────┘ │
│ │ │
│ ┌──────────────▼──────────────┐ │
│ │ DNS Packet Parser │ │
│ │ Header / Questions │ │
│ │ Records / Compression │ │
│ └──────────────┬──────────────┘ │
│ │ │
│ ┌──────────────▼──────────────┐ │
│ │ TTL Cache │ │
│ └──────────────┬──────────────┘ │
│ │ │
│ ┌──────────────▼──────────────┐ │
│ │ Iterative Resolver │ │
│ └──────────────┬──────────────┘ │
└─────────────────┼─────────────────┘
│
DNS queries to port 53
│
┌───────────────────────▼──────────────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Root Servers │ ───── referrals ─────▶ │ TLD Servers │
└──────────────────┘ │ .com, .org ... │
└────────┬─────────┘
│
│ referral
▼
┌──────────────────┐
│ Authoritative DNS│
│ Servers │
└──────────────────┘
DNS packet flow :
Client query
│
▼
Parse DNS packet
│
▼
Validate request
│
▼
Check cache
│
├── Cache hit ──────► Return cached answer
│
└── Cache miss
│
▼
Query root server
│
▼
Follow referrals
│
▼
Query authoritative server
│
▼
Store response in cache
│
▼
Send response to client
BytePacketBuffer— Handles binary packet parsing- Compression pointer support
- Bounds checking and security validations
DnsHeader— 12-byte header parsing and serializationDnsQuestion— Query encoding and decodingDnsRecord— Supports A, AAAA, CNAME, MX, NS, TXT, and moreDnsPacket— Complete packet assembly and disassembly
recursive_lookup()— Walks the DNS hierarchylookup()— Queries a single DNS server with retries- TTL-based cache
- Automatic TCP fallback for large responses
handle_query()— Processes incoming DNS requests- Thread pool for concurrent clients
- Proper DNS error codes:
SERVFAILFORMERRNXDOMAIN
# Run the server
python dns_server.py
# Test with dig
dig @127.0.0.1 -p 2053 google.com
# Or use nslookup
nslookup -port=2053 google.com 127.0.0.1DNS Queries------------------------------------------------------------------------------------------Server
| Feature | Value |
|---|---|
| Concurrency | 64 worker threads |
| Cache | TTL-aware (30s–3600s) |
| Retries | 3 attempts per server |
| TCP Fallback | Automatic for truncated responses |
For a query such as:
example.com → ?
The resolver performs the following steps:
- Receives the query from a client.
- Checks the local cache.
- If the answer is not cached, contacts a root DNS server.
- Receives a referral to the
.comname servers. - Contacts a
.comTLD server. - Receives a referral to the authoritative server for
example.com. - Contacts the authoritative server.
- Receives the final answer.
- Stores the response in the cache using its TTL.
- Sends the answer back to the client.
Contributions are always welcome!
- ⭐ Give the repository a star if you like it.
- 🐛 Open an issue if you find a bug.
- 🔧 Submit a Pull Request to fix bugs or add new features.