Skip to content

About

Multi-tenant DNS filtering service with per-profile privacy, security, parental controls, DDNS and DoH

Resources

Stars

8 stars

Watchers

0 watching

Forks

Repository files navigation

ShieldDNS

Multi-tenant DNS filtering service for adblock-dns.click. Every user owns one or more isolated profiles. Each profile has its own configuration ID, protection settings, allow/deny rules, network links, and query retention policy. Verified DDNS links are refreshed approximately once per minute in bounded concurrent batches.

Runtime

  • Node.js 18+, Express, server-rendered EJS
  • MySQL 8 with foreign keys and profile-scoped indexes
  • Database-backed secure sessions
  • Native UDP/TCP DNS resolver on port 53 and DNS-over-HTTPS endpoint
  • In-memory profile/list cache backed by MySQL
  • Weekly atomic blocklist refresh through systemd
  • Nginx terminates TLS and proxies to 127.0.0.1:3001

Setup

  1. Copy .env.example to .env and replace every example address and empty secret. Generate SESSION_SECRET with openssl rand -hex 32.
  2. Run npm ci.
  3. Create the configured MySQL database and user, then run npm run migrate.
  4. Run npm run update:lists to generate data/blocklists/.
  5. Run npm run check.
  6. Start the dashboard with pm2 start ecosystem.config.cjs.
  7. Adapt the service user and /opt/shielddns path in deploy/, then install and enable the resolver service and blocklist timer.

Never commit .env, database exports, TLS private keys, query logs, or runtime cache files. Rotate credentials immediately if they are exposed.

Tenant isolation

Dashboard profile lookups always require both config_id and the authenticated user_id. Child records reference an internal profile ID and are deleted through foreign-key cascades. A public IP or DDNS hostname can belong to only one profile because unencrypted DNS cannot distinguish multiple configurations behind the same public address.

Encrypted DNS uses the profile configuration ID in /dns-query/{configId}. The DNS data plane enforces that identifier independently and never forwards browser session cookies to the resolver.

Blocklists

Run npm run update:lists to download, normalize, deduplicate, and atomically replace the supported public lists. New profiles enable the balanced nextdns_recommended and hagezi_light privacy lists by default. Security intelligence, native-device trackers, affiliate tracking, and parental-control lists are applied by their separate profile switches. The social parental category also includes an in-resolver TikTok/ByteDance service map so the native app and router search-suffix retries are covered, not only tiktok.com. Disguised trackers are detected by inspecting upstream CNAME answers against the profile's active lists.

List data lives in data/blocklists/ and is intentionally excluded from source control. The production timer refreshes it weekly and restarts the resolver only after a successful update.

Verification

  • npm run check: syntax checks and unit tests
  • npm run smoke: live registration, CSRF, tenant isolation, rules, DoH, UDP/TCP IPv4, UDP IPv6, unique-IP enforcement, and health checks
  • npm audit --omit=dev: production dependency audit

About

Multi-tenant DNS filtering service with per-profile privacy, security, parental controls, DDNS and DoH

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages