How bhanupratapys/dnswarden works
Project type and purpose
• This repository is not a classic code-only application but rather the documentation and configuration “stamps” for a privacy-oriented, filterable DNS service (DNSWarden). It defines multiple DNS resolver endpoints (over DoT, DoH, DoQ, DNSCrypt) and provides per-client configuration files (“stamps”) for different filter profiles (uncensored, adblock, adult, custom).
File structure
• Top-level:
• .github/workflows/delete_workflows.yml – CI workflow managing stamp files.
• stamps/ – folders containing markdown templates that clients import to configure their DNS software.
• LICENSE, README.md – project metadata and service overview.
• No traditional “src” or “backend/frontend” code here; the repo’s function is to hold configuration artifacts and documentation for the running DNS infrastructure.
README for additional insights
• Describes four filter profiles (uncensored, adblock, adult, custom) and supported protocols (DNS-over-TLS, HTTPS, QUIC, DNSCrypt).
• Lists public endpoints per profile and protocol.
• Mentions upstream datacenter fallbacks, blocklists, DNSSEC/QNAME minimization.
• Client software support and “stamps” download URLs.
Main components and interactions (to be shown
a. Clients
• Various client apps or OS resolvers (Android apps, Knot, Unbound, dnscrypt-proxy, etc.)
b. Network transit
• The internet channel (TLS, HTTPS, QUIC, DNSCrypt tunnels)
c. Edge/Ingress layer
• Protocol listeners (DoT listener, DoH HTTP server, DoQ QUIC server, DNSCrypt server)
d. Filter engine
• Blocklist DB + policy engine applying the chosen filter profile (uncensored/adblock/adult/custom)
e. Resolver core
• Caching resolver logic with DNSSEC and QNAME minimization
f. Upstream fallback
• Datacenter DNS servers used when the resolver cannot answer from cache
g. Stamps repository & CI
• .github workflow that regenerates stamp files → stamps/ folder → clients pulling updated stamps
Relationships and data flows
• Clients → (protocol channel: DoT/DoH/DoQ/DNSCrypt) → Edge listeners
• Edge listeners → Filter engine (profile decision) → Resolver core
• Resolver core → Upstream DNS if cache miss → Resolver → Filter engine (optional re-check) → Edge listener → Client
• CI Pipeline → regenerates stamp configs → updates Git repo → clients pull new stamp files
Architectural patterns and design principles
• Micro-service style: separate protocol handlers and filter/resolver logic
• Config-driven profiles: one codebase, multiple filter profiles via policy engine
• Operator-managed CI: automated stamp-file publication
• Security & privacy: DNSSEC, QNAME minimization, no logging
Technologies and frameworks
• DNS servers (Unbound, Knot-resolver, or custom C/Go DNS code)
• TLS/QUIC libraries, HTTP servers for DoH
• GitHub Actions for CI/CD of stamps
• Markdown-based stamp templates