🕳️ ESPHole

ESP32-S3 · DNS SINKHOLE

Ad-blocking DNS
that never goes dark
DNS con bloqueo
que nunca se apaga

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.

RFC 1035 + EDNS0 DoT fail-closed OTA + rollback MIT

⚡ Flash from your browser⚡ Flashea desde el navegador

0%
blockedbloqueado

InstallInstalar

Flash it from your browser — no toolchainFlashéalo desde el navegador — sin toolchain

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.

This browser can't flash over USB — open it in desktop Chrome or Edge.Este navegador no puede flashear por USB — ábrelo en Chrome o Edge de escritorio. Web Serial needs a secure origin — this only works over https://.Web Serial requiere origen seguro — solo funciona por https://.

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

A whole ad-blocker in 2 MB of firmwareUn bloqueador entero en 2 MB de firmware

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

Ten specs, one applianceDiez specs, un aparato

DNS coreNúcleo DNS

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.

Fail-openFail-open

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.

DoT

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.

Blocklists from URLListas desde URL

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.

OTA + rollbackOTA + rollback

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.

Web admin + APIWeb + API

Dashboard, config, health. Challenge-response login — the password never travels.Panel, config, salud. Login desafío-respuesta — la contraseña nunca viaja.

Per-client statsStats por cliente

Which IPs query, how much, how many blocked — ephemeral, bounded.Qué IPs consultan, cuánto, cuántas bloqueadas — efímero, acotado.

DHCP ⚠️

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).

Bilingual + themesBilingüe + temas

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

The fast path never blocksLa ruta rápida nunca bloquea

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.

clientsLAN net_dnsfast path · tcpip blocked → 0.0.0.0 cache hit miss → forward upstream (UDP) net_dot · DoT 853 upstreamresolvers webapiHTTP :80 net_dhcp :67optional · ⚠ untested

StatusEstado

Built and verified, spec by specConstruido y verificado, spec a spec

#FeatureFuncionalidadStatusEstado
001DNS coreNúcleo DNS✓ verified on hardwareverificado en hardware
002Wi-Fi provisioningAprovisionamiento Wi-Fi✓ implementedimplementada
003HTTP API + web adminAPI HTTP + web✓ verifiedverificada
004Blocklists from URLListas desde URL✓ verifiedverificada
005OTA + rollbackOTA + rollback✓ rollback provokedrollback provocado
006DHCP server (optional)Servidor DHCP (opcional)⚠ not tested end-to-endsin probar end-to-end
007Encrypted upstream (DoT)Upstream cifrado (DoT)✓ fail-closed verifiedfail-closed verificado
008Per-client statsStats por cliente✓ verifiedverificada
009Bilingual UI (EN/ES)Interfaz bilingüe (EN/ES)✓ verifiedverificada
010UX/UI redesignRediseño de UX/UI✓ verifiedverificada
⚠️ The DHCP server is experimental.El servidor DHCP es experimental. Its pure logic is unit-tested and the API/UI exist, but it has not been exercised on a live network — a rogue DHCP server can hand out IPs and disrupt other devices. Validate it on an isolated LAN (with the router's own DHCP disabled) before relying on it. Su lógica pura está testeada y la API/UI existen, pero no se ha ejercitado en una red real — un DHCP no controlado puede repartir IPs y perturbar otros dispositivos. Valídalo en una LAN aislada (con el DHCP del router desactivado) antes de confiar en él.

SecuritySeguridad

Hostile input is the default assumptionLa entrada hostil es el supuesto por defecto

QuickstartInicio rápido

Build & flashCompilar y flashear

# 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

Where it's headedHacia dónde va

Validate DHCP on an isolated LANValidar el DHCP en LAN aislada DoH DoT/DoH server for clientsServidor DoT/DoH para clientes Historical graphsGráficas históricas Per-client policiesPolíticas por cliente Signed OTA imagesOTA firmado More languagesMás idiomas