Project 10: DNS Sinkhole (Pi-hole Style)

A DNS forwarder that blocks requests for known ad or malware domains.

Quick Reference

Attribute	Value
Difficulty	Level 3: Advanced
Time Estimate	2 weeks
Main Programming Language	Python
Alternative Programming Languages	Go, Rust, C
Coolness Level	Level 4: Hardcore Tech Flex
Business Potential	3. The “Service & Support” Model
Prerequisites	See concepts below
Key Topics	Naming and Configuration Services (DNS, DHCP, mDNS), Operations, Diagnostics, and Security

1. Learning Objectives

Build and validate: A DNS forwarder that blocks requests for known ad or malware domains..
Explain protocol behavior and verify it with a capture or trace.
Handle edge cases and produce reproducible results.

2. All Theory Needed (Per-Concept Breakdown)

Naming and Configuration Services (DNS, DHCP, mDNS)

Fundamentals Before a connection happens, a device needs two things: an address configuration and a name-to-address mapping. DHCP provides configuration: IP address, subnet mask, default gateway, and DNS servers. DNS provides name resolution: it turns a human-friendly name into IP addresses. On small local networks without an authoritative DNS server, mDNS and DNS-SD allow devices to discover services on the local link. These services are essential because users do not type IP addresses and devices do not manually configure themselves in modern networks.

Deep Dive DNS is a hierarchical distributed database. When a client needs to resolve a name, it asks a recursive resolver (often provided by the ISP or a local router). The resolver performs iterative queries starting at the root, then the TLD, then the authoritative server for the zone. Responses are cached according to TTL values. This caching is why DNS queries can be fast, and also why changes can take time to propagate. DNS responses can arrive over UDP for small messages or TCP for larger responses or zone transfers. Understanding this distinction matters for debugging, since UDP truncation forces a TCP retry.

DHCP follows a discover-offer-request-acknowledge (DORA) exchange. A client with no address broadcasts a DHCPDISCOVER. A server replies with a DHCPOFFER. The client requests the offered address with DHCPREQUEST, and the server confirms with DHCPACK. Leases are time-limited and periodically renewed. This system allows dynamic reuse of addresses and centralized configuration. But it also introduces failure modes: multiple DHCP servers can fight, leases can expire if the server is unreachable, and clients can receive inconsistent options (like a wrong default gateway) that make the network appear partially broken.

mDNS and DNS-SD provide zero-configuration discovery. Instead of contacting a DNS server, devices send multicast queries to a well-known address on the local link. This allows discovery of printers, media devices, and local services without manual setup. The protocol reuses DNS message formats but changes the transport and scope. mDNS is powerful for home networks but can become noisy in larger environments. Understanding the scope and TTL settings for mDNS is essential when diagnosing why a device appears in a discovery list but is not reachable, or why service lists change frequently.

Naming and configuration services also intersect with security. DNS can be spoofed if you trust the wrong resolver or if a local attacker injects responses. DHCP can be abused by rogue servers. This is why managed networks often implement DHCP snooping and DNS security mechanisms. In home networks, the threat model is different, but the failure modes are similar. A misbehaving IoT device running a DHCP server can cause intermittent failures that look like random internet drops.

Finally, these services are the backbone of usability. When DNS or DHCP fails, users perceive that “the internet is down,” even if the physical link is fine. Your ability to build a DNS resolver or DHCP server from scratch is a demonstration that you truly understand how network configuration and naming work. It also makes you capable of implementing local overrides like DNS sinkholes, which are highly practical for security and ad-blocking.

How this fit on projects Projects 5-8, 10, and 16 are direct applications of DNS, DHCP, and mDNS.

Definitions & key terms

Resolver: The client-side DNS component that asks questions.
Recursive resolver: DNS server that walks the hierarchy on behalf of clients.
TTL: Time-to-live for cached DNS answers.
Lease: The time a DHCP address is valid.
mDNS: Multicast DNS on a local link.

Mental model diagram

Client -> Resolver -> Root -> TLD -> Authoritative
          ^ cache TTLs at each step

How it works

Client obtains an IP address and DNS server via DHCP.
Client asks resolver for a name.
Resolver walks the DNS hierarchy and caches answers.
Local devices use mDNS for link-local discovery. Invariants: DNS is cached and hierarchical. Failure modes: rogue DHCP, stale DNS cache, mDNS storms.

Minimal concrete example

DNS query/response (text):
Query: A example.com
Answer: example.com -> 93.184.216.34 (TTL 86400)

Common misconceptions

“DNS is always real-time.” It is cached by design.
“DHCP only gives IP addresses.” It also provides gateway and DNS servers.

Check-your-understanding questions

Why might a DNS change take hours to show up?
What happens if a DHCP lease expires and the server is down?

Check-your-understanding answers

Cached answers remain valid until TTL expires.
The client may lose connectivity or fall back to a self-assigned address.

Real-world applications

Local ad-blocking via DNS sinkholes.
Zero-configuration printer discovery.

Where you will apply it

Projects 5-8, 10, 16

References

RFC 1034/1035 (DNS), RFC 2131 (DHCP)
RFC 6762/6763 (mDNS, DNS-SD)

Key insights Naming and configuration are invisible until they fail, then everything fails.

Summary DNS and DHCP are the core control plane of a home network.

Homework/Exercises to practice the concept

Trace a DNS lookup from your device to the authoritative server.
Capture a DHCP DORA exchange and label each step.

Solutions to the homework/exercises

Use dig +trace and note each delegation.
Filter UDP ports 67 and 68 and identify discover, offer, request, ack.

Operations, Diagnostics, and Security

Fundamentals Diagnostics and security are where theory becomes practical. ICMP provides feedback about connectivity, latency, and routing failures. Tools like ping and traceroute rely on ICMP to make network paths visible. Packet capture reveals the truth of what is happening on the wire, which is essential when logs or assumptions are wrong. Security in home/office networks is built on segmentation, stateful filtering, and secure Wi-Fi configuration. Understanding these tools and controls lets you diagnose failures quickly and prevent common threats.

Deep Dive ICMP is often misunderstood as “just ping,” but it is the control plane of IP. It reports unreachable destinations, TTL expiry, and fragmentation requirements. Traceroute manipulates TTL values to force routers along a path to send ICMP Time Exceeded messages, which reveals hop-by-hop routing. Understanding ICMP types and codes lets you differentiate between “host unreachable” and “port unreachable,” which can save hours of guessing. But ICMP is not guaranteed to be delivered, so diagnostics must be combined with other evidence like TCP resets and packet captures.

Packet capture is the definitive tool for understanding network behavior. A capture shows headers at every layer, timestamps, retransmissions, and the exact sequence of events that produced a failure. It also reveals hidden behaviors, such as DNS retries, TCP window size changes, or unexpected multicast traffic. Effective capture requires careful filtering and knowledge of what you are looking for. On switched networks, you may only see traffic destined for your host, so you may need port mirroring or monitor mode on Wi-Fi. Without this awareness, you can falsely conclude that traffic is not present when you are simply not observing the right link.

Security in home networks is primarily about reducing attack surface and limiting trust. A stateful firewall tracks connection state and allows return traffic while blocking unsolicited inbound flows. This is different from NAT, though NAT produces a similar effect. Segmentation isolates devices so that a compromised IoT device cannot reach sensitive systems. Wi-Fi security must protect the air interface using WPA2 or WPA3, and should avoid legacy configurations like WEP or open networks. VPNs create encrypted tunnels across untrusted networks; they can be site-to-site (linking networks) or remote access (linking a device to a network). VPNs also alter routing by creating new routes over the tunnel interface, which is why they sometimes break local network access or change DNS behavior.

Operational visibility is not just about troubleshooting failures. It is about validating performance and policy. A bandwidth monitor can show whether a device is saturating the uplink. A DNS sinkhole can show which devices are contacting malicious domains. A firewall log can show attempted scans or misconfigured services. These tools are the foundation of a healthy home or office network.

Finally, security is a system property, not a single setting. A strong Wi-Fi passphrase is meaningless if devices are on the same flat network with no segmentation. A firewall rule is only as good as the routing table that feeds it. The projects in this guide are structured to force you to test and verify these properties, not just configure them.

How this fit on projects Projects 2-4, 9-20 use diagnostics and security concepts directly.

Definitions & key terms

ICMP: Control messages for IP.
Stateful firewall: Filters traffic based on connection state.
Segmentation: Separating devices into isolated networks.
VPN: Encrypted tunnel over untrusted networks.

Mental model diagram

Client -> Router -> Internet
   |        |         |
   |   firewall state |
   |   ICMP feedback  |
   +-> capture point  |

How it works

Use ICMP to test reachability and path.
Capture packets to confirm actual behavior.
Enforce policy with firewall and segmentation.
Use VPNs to extend trust securely. Invariants: ICMP is best-effort, not guaranteed. Failure modes: blocked ICMP, asymmetric routing, misapplied firewall rules.

Minimal concrete example

Traceroute logic:
TTL=1 -> ICMP Time Exceeded from hop 1
TTL=2 -> ICMP Time Exceeded from hop 2
...

Common misconceptions

“If ping fails, the host is down.” ICMP may be blocked.
“NAT equals firewall.” NAT does not express security policy.

Check-your-understanding questions

Why can traceroute fail even when the destination is reachable?
Why might a VPN break access to local printers?

Check-your-understanding answers

Routers or hosts may block ICMP Time Exceeded messages.
VPN routes may override local routes, sending traffic into the tunnel.

Real-world applications

Diagnosing intermittent Wi-Fi dropouts.
Segmenting IoT devices away from trusted systems.

Where you will apply it

Projects 2-4, 9-20

References

RFC 792 (ICMP)
“TCP/IP Illustrated, Vol 1” by Stevens - Ch. 6

Key insights You cannot secure or fix what you cannot observe.

Summary Diagnostics and security are practical disciplines that transform network theory into reliable systems.

Homework/Exercises to practice the concept

Capture a TCP handshake and annotate each packet.
Design a guest network segmentation plan for your home.

Solutions to the homework/exercises

Identify SYN, SYN-ACK, ACK, then the first data packet.
Create a separate VLAN or SSID with no access to LAN subnets.

3. Project Specification

3.1 What You Will Build

A DNS forwarder that blocks requests for known ad or malware domains.

Included:

CLI tool with clear output
Validation steps and logging
Documentation of assumptions

Excluded:

Production-grade performance tuning
Full security hardening

3.2 Functional Requirements

Core function: Implement the primary behavior described in the project goal.
Observable output: Produce deterministic output comparable to the Real World Outcome.
Error handling: Handle timeouts, invalid inputs, and unreachable hosts gracefully.

3.3 Non-Functional Requirements

Performance: Complete typical tasks within a few seconds on a LAN.
Reliability: Fail safely and clearly on errors.
Usability: Provide concise CLI flags and helpful messages.

3.4 Example Usage / Output

$ ./dns_sinkhole --listen 0.0.0.0:53
Blocked: ads.example.net -> 0.0.0.0
Allowed: example.com -> 93.184.216.34
Top blocked domains today:
  ads.example.net (245)
  tracker.example.org (188)

3.5 Data Formats / Schemas / Protocols

Protocols: Naming and Configuration Services (DNS, DHCP, mDNS), Operations, Diagnostics, and Security.

3.6 Edge Cases

Target unreachable or timing out
Malformed or unexpected responses
Multiple interfaces or subnets

3.7 Real World Outcome

$ ./dns_sinkhole --listen 0.0.0.0:53
Blocked: ads.example.net -> 0.0.0.0
Allowed: example.com -> 93.184.216.34
Top blocked domains today:
  ads.example.net (245)
  tracker.example.org (188)

3.7.1 How to Run (Copy/Paste)

Build: make (or create a virtual environment as needed)
Run: ./P10-dns-sinkhole
Config: update any constants in a config file or flags
Working directory: project root

3.7.2 Golden Path Demo (Deterministic)

Run against a known local target and compare with the expected output.

3.7.3 If CLI: provide an exact terminal transcript

$ ./dns_sinkhole --listen 0.0.0.0:53
Blocked: ads.example.net -> 0.0.0.0
Allowed: example.com -> 93.184.216.34
Top blocked domains today:
  ads.example.net (245)
  tracker.example.org (188)

4. Solution Architecture

4.1 High-Level Design

CLI Input -> Core Engine -> Output/Logs

4.2 Key Components

Component	Responsibility	Key Decisions
CLI Parser	Parse flags and inputs	Keep interface minimal
Core Engine	Protocol logic and state	Keep deterministic timing
Output/Logs	Present results and errors	Use consistent formatting

4.4 Data Structures (No Full Code)

Request:
  - target
  - protocol fields
Response:
  - status
  - timing
State:
  - retries
  - cache entries

5. Implementation Guide

5.1 Development Environment Setup

Ensure required tools (tcpdump, dig, ip) are installed.
Use elevated privileges where raw sockets are required.

5.2 Project Structure

project/
  README.md
  docs/
  src/
  tests/
  data/

5.3 The Core Question You’re Answering

“How can DNS be used as a control point to protect and shape network behavior?”

5.4 Concepts You Must Understand First

DNS forwarding
- How do you relay queries to upstream resolvers?
- Book Reference: “TCP/IP Illustrated, Vol 1” - Ch. 18
NXDOMAIN vs sinkhole
- Which response should you return and why?
- Book Reference: RFC 1035
Logging and privacy
- What should be logged, and what should not?
- Book Reference: “Computer Networks” - Ch. 8

5.5 Questions to Guide Your Design

Policy enforcement
- How do you match domains and subdomains efficiently?
Performance
- How do you avoid slowing down normal DNS resolution?

5.6 Thinking Exercise

Blocklist tradeoff

If you block ads.example.com, what happens to cdn.ads.example.com?

Questions to answer:

How should wildcard matching work?
What are the false positive risks?

5.7 The Interview Questions They’ll Ask

“What is a DNS sinkhole and how does it work?”
“How do you prevent blocking critical domains?”
“Why might returning NXDOMAIN break apps?”
“How can you measure the effectiveness of a sinkhole?”
“What privacy considerations exist when logging DNS queries?”

5.8 Hints in Layers

Hint 1: Start as a pure forwarder Forward all queries to an upstream resolver first.

Hint 2: Add a simple blocklist Block a fixed list of domains to validate logic.

Hint 3: Pseudocode outline

- receive DNS query
- if domain in blocklist: return sinkhole answer
- else: forward to upstream, return response
- log decision

Hint 4: Verification Use dig to confirm blocked vs allowed responses.

5.9 Books That Will Help

Topic	Book	Chapter
DNS forwarding	“TCP/IP Illustrated, Vol 1”	Ch. 18
DNS protocol	RFC 1035	Spec
Security context	“Computer Networks”	Ch. 8

5.10 Implementation Phases

Establish core protocol I/O and a minimal success path.
Add parsing, validation, and timeouts.
Add logging, metrics, and polish for output.

5.11 Key Implementation Decisions

Which interface and capture point provides visibility?
What timeout and retry strategy balances speed and accuracy?
How will results be validated against reference tools?

6. Testing Strategy

6.1 Test Categories

Unit: parsing and validation logic
Integration: protocol exchange with a real device
System: full run with reference tools

6.2 Critical Test Cases

Successful request/response path
Timeout and retry behavior
Invalid or unexpected input handling

6.3 Test Data

Local gateway IP and a known reachable host
A non-routable IP to trigger timeouts

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Problem 1: “Everything is blocked”

Why: Overly broad domain matching.
Fix: Use exact match and explicit wildcards.
Quick test: Query a known safe domain and verify.

Problem 2: “Responses are slow”

Why: No caching or slow upstream resolver.
Fix: Add a small cache and measure upstream latency.
Quick test: Compare with dig response times.

7.2 Debugging Strategies

Capture traffic with tcpdump or Wireshark.
Compare against a known-good tool.
Log timestamps and retry logic.

7.3 Performance Traps

Excessive retries causing long runtimes.
Inefficient parsing under high packet rates.

8. Extensions & Challenges

8.1 Beginner Extensions

Add basic configuration flags for interface and timeout.
Improve output formatting and sorting.

8.2 Intermediate Extensions

Add caching or state persistence.
Add CSV or JSON output export.

8.3 Advanced Extensions

Add concurrency with careful rate limiting.
Add visualization or integration with a dashboard.

9. Real-World Connections

9.1 Industry Applications

Network diagnostics and troubleshooting
Security monitoring and policy enforcement

tcpdump / Wireshark
nmap / dnsmasq / unbound (as applicable)

9.3 Interview Relevance

Explaining protocol behavior
Diagnosing failures by layer

10. Resources

10.1 Essential Reading

Topic	Book	Chapter
DNS forwarding	“TCP/IP Illustrated, Vol 1”	Ch. 18
DNS protocol	RFC 1035	Spec
Security context	“Computer Networks”	Ch. 8

10.2 Video Resources

Wireshark or tcpdump walkthroughs (search for recent tutorials)
Vendor or RFC explainers for the relevant protocol

10.3 Tools & Documentation

RFCs for the protocols used in this project
man tcpdump, man ip, man ss