Skip to content

README.md

Latest commit

 

History

History
89 lines (63 loc) · 2.3 KB

README.md

File metadata and controls

89 lines (63 loc) · 2.3 KB
Raw

esp-sinker 🌐

A DNS sinkhole running on an ESP32 microcontroller, built with Rust and esp-idf-svc.

What it does

The ESP32 creates its own Wi-Fi access point. Devices connect to it and all DNS queries go through the ESP32, which can block unwanted domains (ads, trackers) and forward legitimate ones upstream.

Hardware

  • ESP32 (any variant — tested on ESP32-U)
  • USB cable for flashing

Setup

Prerequisites

# Install the ESP Rust toolchain
espup install

# Add to your shell profile
echo '. $HOME/export-esp.sh' >> ~/.zshrc
source ~/.zshrc

# Install flashing tools
cargo install espflash ldproxy

Build & Flash

git clone <your-repo>
cd esp-sinker
cargo run

Connect

  1. On your device (phone, laptop), connect to Wi-Fi network esp-sinker
  2. Password: 12345678
  3. Your device gets IP 192.168.71.2, the ESP32 is at 192.168.71.1

Test

nslookup google.com 192.168.71.1

You should see the query appear in the serial monitor.

What's implemented ✅

  • Wi-Fi Access Point — ESP32 broadcasts its own network, DHCP assigns IPs to connected clients
  • UDP socket on port 53 — listens for incoming DNS queries
  • DNS packet parsing — extracts the queried domain name from raw UDP bytes using dns-parser
  • Serial logging — prints every DNS query to the monitor for debugging

What's next 🔜

  • Blocklist check — compare queried domain against blocklist.txt (embedded at compile time)
  • NXDOMAIN response — craft and send a "domain not found" response for blocked domains
  • Upstream forwarding — forward allowed queries to 1.1.1.1 and relay the response back
  • Subdomain matching — block ads.example.com if example.com is in the blocklist

Project structure

esp-sinker/
├── src/
│   └── main.rs        # Wi-Fi init, UDP loop, DNS parsing
├── blocklist.txt      # One domain per line, embedded at compile time
├── build.rs           # embuild linker setup
├── Cargo.toml
├── sdkconfig.defaults
└── .cargo/
    └── config.toml    # Target triple, linker config

Dependencies

Crate Purpose
esp-idf-svc Wi-Fi, NVS, peripherals
dns-parser Parse raw DNS UDP packets
anyhow Error handling
log Logging