Neuwerk

DNS Handling

Hostname-based policy works by proxying DNS on the Neuwerk and turning approved answers into a dynamic allowlist.

Use this guide when you want to enforce policy by hostname rather than by fixed IP alone.

The important model is:

  1. clients send DNS to the Neuwerk
  2. the Neuwerk evaluates the query against DNS policy
  3. allowed answers are forwarded upstream
  4. successful IPv4 answers are added to a dynamic allowlist
  5. later packet traffic to those resolved IPs can pass the dataplane policy

What To Configure

Hostname-based policy depends on two runtime inputs:

  • one or more --dns-target-ip values
  • one or more --dns-upstream resolvers

Client DNS traffic is only treated as managed DNS traffic when:

  • the destination port is 53
  • the protocol is TCP or UDP
  • the source IP is internal
  • the destination IP matches one of the configured DNS target IPs

In practice, point clients at the Neuwerk for DNS or route DNS traffic to the configured target IPs that the Neuwerk will intercept.

How DNS Decisions Work

The DNS proxy listens on the management IP at port 53 and evaluates:

  • the client source IP
  • the requested hostname
  • the compiled DNS policy derived from your source groups and rules

If the DNS rule is denied, the client receives NXDOMAIN.

If the DNS rule is allowed, the Neuwerk forwards the query to an upstream resolver and validates the reply before accepting it.

Important Difference From Packet Policy

DNS fallback is stricter than packet-policy fallback.

Once a source group claims the source IP:

  • a matching DNS rule decides the result
  • no matching DNS rule means deny

This is the most common surprise when teams first enable hostname-based policy. A broad packet allow rule does not automatically grant DNS permission.

What The Dynamic Allowlist Does

Successful IPv4 answers are inserted into:

  • the dynamic dataplane allowlist
  • the diagnostic DNS cache

The allowlist is what makes later packet flows to the resolved IPs pass policy. The DNS cache is a diagnostic surface that helps explain what the Neuwerk most recently resolved.

What To Check After A Change

After updating DNS policy, verify:

  • GET /ready
  • GET /api/v1/dns-cache
  • GET /api/v1/stats
  • GET /api/v1/audit/findings

Use the DNS cache to confirm that allowed names are resolving and feeding the allowlist. Use audit findings to confirm whether the Neuwerk is denying the query or the later traffic.

Current Limits

  • IPv4 answers populate the allowlist; AAAA answers do not currently create allowlist entries.
  • Non-IPv4 client DNS queries are denied.
  • The Neuwerk accepts DNS over TCP from clients, but upstream forwarding currently uses UDP.
  • The DNS cache is a diagnostic map, not a full recursive cache.

Warning

If clients continue using a resolver that is outside the Neuwerk’s managed DNS path, hostname policy will not behave the way you expect. The Neuwerk must see the DNS query so it can build the allowlist that the dataplane later relies on.