ESP32-S3 · DNS SINKHOLE
A Pi-hole–style sinkhole on a tiny ESP32-S3. Blocklisted domains die with a black-hole answer; everything else is forwarded and cached — and if blocking ever fails, the network keeps resolving. Fail-open by design. Un sinkhole estilo Pi-hole en un diminuto ESP32-S3. Los dominios en lista mueren con una respuesta de agujero negro; el resto se reenvía y se cachea — y si el bloqueo falla, la red sigue resolviendo. Fail-open por diseño.
InstallInstalar
Plug an ESP32-S3 into your computer over USB and click. No ESP-IDF, no drivers to hunt down — the whole firmware (app + web UI) is written over Web Serial. Works in desktop Chrome or Edge. Conecta un ESP32-S3 al ordenador por USB y pulsa. Sin ESP-IDF ni drivers que buscar — el firmware entero (app + web) se escribe por Web Serial. Funciona en Chrome o Edge de escritorio.
On first boot it starts the ESPHole-XXXX Wi-Fi AP (key on the serial console) so you can set your network — see the README. Prefer the command line? Download the merged image from Releases and run esptool write-flash 0x0 esphole-factory-esp32s3.bin. En el primer arranque levanta el AP Wi-Fi ESPHole-XXXX (clave en la consola serie) para configurar tu red — ver el README. ¿Prefieres la terminal? Descarga la imagen combinada de Releases y ejecuta esptool write-flash 0x0 esphole-factory-esp32s3.bin.
What it isQué es
Every DNS query on your LAN passes through ESPHole. It runs the full fast path — parse, block, cache — inside a single non-blocking thread, so resolution stays instant while TLS, HTTP and OTA happen off to the side. Built spec-by-spec with strict test-driven development and on-hardware verification. Cada consulta DNS de tu red pasa por ESPHole. Ejecuta la ruta rápida completa — parsear, bloquear, cachear — en un solo hilo que nunca bloquea, así la resolución es instantánea mientras el TLS, el HTTP y el OTA ocurren aparte. Construido spec a spec con TDD estricto y verificación en hardware.
FeaturesFuncionalidades
UDP + TCP :53, A/AAAA suffix blocking, upstream failover, cache, rate-limiting.UDP + TCP :53, bloqueo A/AAAA por sufijo, failover, caché, límite de tasa.
The LAN keeps resolving even if blocking, cache or every upstream fails.La red sigue resolviendo aunque fallen el bloqueo, la caché o todos los upstreams.
Encrypted upstream over DNS-over-TLS with a fail-closed guarantee — never plaintext.Upstream cifrado por DNS-over-TLS con garantía fail-closed — nunca en claro.
Download a HOSTS list over HTTPS and rebuild in place — no reboot.Descarga una lista HOSTS por HTTPS y la reconstruye en caliente — sin reboot.
HTTPS firmware updates that revert automatically if the new build won't boot.Actualizaciones HTTPS que vuelven atrás solas si la nueva no arranca.
Dashboard, config, health. Challenge-response login — the password never travels.Panel, config, salud. Login desafío-respuesta — la contraseña nunca viaja.
Which IPs query, how much, how many blocked — ephemeral, bounded.Qué IPs consultan, cuánto, cuántas bloqueadas — efímero, acotado.
Optional DHCP server. Implemented, but not yet tested end-to-end (see status).Servidor DHCP opcional. Implementado, pero aún sin probar de extremo a extremo (ver estado).
Full EN/ES UI and a light/dark neon redesign that follows your system.Interfaz EN/ES completa y un rediseño neón claro/oscuro que sigue a tu sistema.
ArchitectureArquitectura
Pure logic (wire parsing, matching, cache, framing) is ESP-IDF-free and unit-tested on a PC; hardware modules are thin glue. Slow work runs in dedicated tasks — the tcpip thread only ever enqueues. La lógica pura (parseo wire, coincidencia, caché, framing) no depende de ESP-IDF y se testea en PC; los módulos de hardware son pegamento fino. El trabajo lento va en tareas dedicadas — el hilo tcpip solo encola.
StatusEstado
| # | FeatureFuncionalidad | StatusEstado |
|---|---|---|
| 001 | DNS coreNúcleo DNS | ✓ verified on hardwareverificado en hardware |
| 002 | Wi-Fi provisioningAprovisionamiento Wi-Fi | ✓ implementedimplementada |
| 003 | HTTP API + web adminAPI HTTP + web | ✓ verifiedverificada |
| 004 | Blocklists from URLListas desde URL | ✓ verifiedverificada |
| 005 | OTA + rollbackOTA + rollback | ✓ rollback provokedrollback provocado |
| 006 | DHCP server (optional)Servidor DHCP (opcional) | ⚠ not tested end-to-endsin probar end-to-end |
| 007 | Encrypted upstream (DoT)Upstream cifrado (DoT) | ✓ fail-closed verifiedfail-closed verificado |
| 008 | Per-client statsStats por cliente | ✓ verifiedverificada |
| 009 | Bilingual UI (EN/ES)Interfaz bilingüe (EN/ES) | ✓ verifiedverificada |
| 010 | UX/UI redesignRediseño de UX/UI | ✓ verifiedverificada |
SecuritySeguridad
QuickstartInicio rápido
# ESP-IDF v6.0.1 · ESP32-S3-N16R8 cd firmware idf.py set-target esp32s3 idf.py build # firmware + web UI (www.bin) idf.py -p /dev/ttyACM0 flash monitor
First boot starts a captive AP (ESPHole-XXXX, key on the serial console). Join it, set your Wi-Fi at 192.168.4.1, then create your admin password on first visit. Full guide in the README (EN/ES). El primer arranque levanta un AP cautivo (ESPHole-XXXX, clave en la consola serie). Conéctate, configura tu Wi-Fi en 192.168.4.1 y crea tu contraseña de admin en la primera visita. Guía completa en el README (EN/ES).
RoadmapPróximos pasos