DNS Filtering Integration Guide - Web Filtering Database

The Resolution Path

How DNS-Based Content Filtering Works

DNS-based content filtering intercepts the domain resolution process to enforce access policies before a network connection is ever established.

1

Query Check

When a client device requests the IP address for a domain, the filtering DNS resolver first checks the domain against a categorization database.

2

Policy Response

If the domain falls into a blocked category, the resolver returns a block page IP or an NXDOMAIN response instead of the actual address.

This approach is fundamentally different from proxy-based filtering. Because DNS resolution happens before any HTTP connection, DNS filtering works across all protocols -- not just web traffic.

It blocks access to domains used by unsafe content command-and-control channels, peer-to-peer applications, and any other protocol that relies on DNS for name resolution.

The Database Behind the Filter

The web filtering database provides domain-to-category mappings for over 100 million domains across 59 categories.

These mappings can be loaded into DNS resolver software as Response Policy Zones (RPZ), local zone overrides, or queried via API in real time for each DNS request.
For pre-classifying existing zone data, bulk URL categorization processes entire domain lists in one pass.
The choice of integration method depends on query volume, latency requirements, and operational preferences.

DNS-layer filtering is especially popular in education: districts deploy DNS filtering optimized for K-12 school environments, and the same architecture delivers CIPA compliant DNS filtering for education networks that must protect E-Rate funding.

Platform Guides

DNS Resolver Integration Examples

Step-by-step integration guides for the most popular DNS resolver platforms

BIND 9 with Response Policy Zones

BIND 9 natively supports Response Policy Zones (RPZ), making it the most straightforward platform for DNS-based filtering.

RPZ allows you to define policy actions for specific domains -- such as returning NXDOMAIN, redirecting to a block page, or dropping the query entirely.
The web filtering database exports its category data in RPZ zone file format, enabling direct import into BIND.
The RPZ zone file contains one record per blocked domain.
When BIND receives a query matching an RPZ entry, it applies the configured policy action before consulting upstream resolvers.
Zone transfers (AXFR/IXFR) keep the local RPZ data synchronized with the master database, ensuring new categorizations propagate within minutes.

named.conf

// named.conf - RPZ configuration
options {
  response-policy {
    zone "rpz.webfilteringdb.com"
      policy nxdomain
      min-update-interval 300;
  };
};

zone "rpz.webfilteringdb.com" {
  type secondary;
  primaries { feeds.webfilteringdb.com; };
  file "rpz-webfilter.db";
};

1

Unbound with Local Zones

Unbound supports local zone definitions and the unbound-control interface for dynamic updates.

Convert the web filtering database into Unbound local-zone directives.
Each blocked domain is declared as a "static" local zone returning either a redirect address or NXDOMAIN.
For large-scale deployments, use the Python module interface to query the categorization API in real time, caching results locally for configurable TTL periods.
Unbound's built-in prefetching ensures that popular domain lookups remain fast even with filtering enabled.

2

PowerDNS Recursor with Lua Scripting

PowerDNS Recursor offers a Lua scripting hook that executes custom logic on every DNS query.

The preresolve() function can query the web filtering database API, check the returned category against the active policy, and modify the DNS response accordingly.
PowerDNS's Lua environment supports HTTP requests, enabling real-time API lookups with local LRU caching.
This approach is ideal for organizations that need dynamic, per-user or per-group filtering policies that change without restarting the resolver.

3

Pi-hole for Small Networks

Pi-hole uses gravity lists to block domains at the DNS level.

The web filtering database can export category-specific blocklists in Pi-hole-compatible format -- one domain per line, grouped by category.
Administrators select which categories to block through Pi-hole's web interface and subscribe to the corresponding list URLs.
Pi-hole's FTL engine handles the lookups efficiently, making this approach suitable for home networks, small offices, and branch locations with up to a few hundred users.

4

CoreDNS with Plugin Architecture

CoreDNS, the default DNS server in Kubernetes environments, supports a plugin chain architecture.

A custom filtering plugin can intercept queries, check domains against the web filtering database, and return policy-appropriate responses.
This is particularly valuable for filtering DNS within container orchestration platforms where traditional DNS servers are not deployed.
The plugin can be compiled into the CoreDNS binary or loaded as an external plugin.

Deployment Models

DNS Filtering Architecture Patterns

Choose the right architecture for your scale and requirements

Local Database vs. API Lookup

The fundamental architectural decision in DNS filtering is whether to maintain a local copy of the categorization database or query the API for each DNS request. Each approach has distinct advantages depending on your deployment scenario.

01

Local RPZ / Zone File

Recommended for High Volume

Download the full database as RPZ zone files updated via IXFR every 15 minutes. Zero external latency on lookups. Best for ISPs and large enterprises processing millions of queries per second.

02

API with Local Cache

Best for Flexibility

Query the REST API on cache miss, store results locally with configurable TTL (default 1 hour). Balances freshness with performance. Ideal for medium-scale deployments needing real-time category updates.

03

Hybrid Approach

Maximum Coverage

Maintain local RPZ for the top 10 million most-queried domains. Fall back to API lookup for domains not in the local database. Combines the speed of local lookups with the completeness of 100 million domain coverage.

04

Forwarding Chain

Simplest Deployment

Forward all DNS queries to the web filtering database's filtering DNS servers. No local configuration required beyond changing the resolver address. Best for small offices and quick proof-of-concept deployments.

At Runtime

Latency, Updates, and Failover

Sub-Millisecond Lookups

Local RPZ delivers filtering decisions in under 1ms with no external dependencies

Real-Time Updates

IXFR zone transfers propagate new categorizations within 15 minutes globally

Graceful Failover

Local cache ensures filtering continues even if the API is temporarily unreachable

DoH / DoT

Handling Encrypted DNS (DoH / DoT)

The rise of DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) presents a challenge for traditional DNS filtering because encrypted DNS queries bypass the local resolver entirely. When a browser sends DNS queries directly to Cloudflare or Google over HTTPS, your filtering resolver never sees the request.

There are several strategies to maintain DNS filtering coverage in an encrypted DNS environment.

1

Own the Endpoint

First, deploy your filtering resolver as a DoH/DoT endpoint itself. Configure endpoint devices to use your internal DoH server, providing both encryption and filtering.

2

Close the Bypass

Second, block outbound DoH/DoT traffic to external resolvers at the firewall level, forcing all DNS through your filtered resolver.

3

Push the Config

Third, use DHCP option 114 (DDR) or enterprise MDM profiles to configure devices to use your encrypted filtering resolver automatically.

For environments where you cannot control endpoint DNS configuration, complement DNS filtering with SNI-based filtering at the TLS layer. The Server Name Indication field in TLS handshakes reveals the target domain before encryption begins, providing a second filtering opportunity even when DNS is encrypted.

DoH Endpoint Deployment

Run your filtering resolver behind an HTTPS endpoint. Tools like dnsdist and nginx can terminate TLS and forward queries to your BIND or Unbound instance. Clients configure https://dns.yourcompany.com/dns-query as their DoH resolver.

External DoH Blocking

Maintain a firewall rule that blocks outbound connections to known public DoH providers (1.1.1.1, 8.8.8.8, etc.) on port 443. This forces devices to fall back to the system DNS resolver, which routes through your filtering infrastructure.

SNI Inspection Fallback

When DNS filtering cannot be enforced, inspect the TLS Client Hello for the SNI field. This reveals the target domain before encryption, allowing category-based blocking at the network layer as a complementary filtering mechanism.

Operations

Performance Tuning & Monitoring

DNS filtering adds a lookup step to every domain resolution. Proper tuning ensures this overhead remains imperceptible to end users while maintaining comprehensive coverage. The same domain resolution data can serve additional analytical purposes, such as helping to find companies with owners nearing retirement by examining web presence patterns.

Cache Sizing

Allocate sufficient memory for the resolver cache.

A cache holding 500,000 entries covers the vast majority of repeated queries.
For BIND, set max-cache-size to at least 256MB.
For Unbound, configure msg-cache-size and rrset-cache-size proportionally.
RPZ entries are held separately and do not count against the resolver cache.

Prefetching

Enable query prefetching to refresh popular cache entries before they expire.

Both BIND (prefetch option) and Unbound (prefetch: yes) support this.
Prefetching eliminates cold-cache latency spikes for frequently accessed domains.

Query Logging

Log all DNS queries along with their filtering decisions to a dedicated log store.

This data feeds compliance reporting, security investigations, and usage analytics.
Query logs can also support efforts to identify businesses with aging owners through domain activity analysis.
Use dnstap for high-performance binary logging that does not impact resolver throughput.

Health Monitoring

Monitor resolver query rate, cache hit ratio, RPZ match rate, and response latency.

Alert on anomalies such as sudden spikes in RPZ blocks (indicating a unsafe content outbreak) or drops in cache hit ratio (indicating a configuration problem).
Export metrics via Prometheus, StatsD, or SNMP for integration with your monitoring stack.

Start Filtering at the DNS Layer

Integrate 100 million categorized domains into your DNS infrastructure. RPZ feeds, REST API, and Pi-hole-compatible lists available today.

Access DNS Filtering Feeds