dohctl - Controlling Windows DNS over HTTPS Policy

dohctl is a PowerShell utility for controlling Windows DNS over HTTPS policy from a repeatable command-line workflow. It disables DoH behavior by writing the same registry-backed policy values Windows uses for Group Policy, reports the resulting state, and flushes the DNS client cache so the change applies immediately.

Source code: github.com/connorcarro/dohctl

The project is built for administrators, lab environments, and security-focused Windows configurations where DNS traffic needs to stay visible to existing monitoring, filtering, or compliance controls. It also includes a restore mode so the restrictive policy values can be removed without manually editing the registry.

Why I built it

DNS over HTTPS can be useful because it encrypts DNS queries by sending them over HTTPS instead of normal DNS transport. That can improve privacy in some environments, but it can also bypass network controls that depend on seeing traditional DNS traffic.

For managed Windows machines, labs, or home networks that use DNS-based filtering, that behavior can be a problem. If a computer silently switches to DoH, router-level filters or DNS monitoring tools may no longer see the queries they are supposed to handle.

I wanted a small tool that made the policy change repeatable and auditable. Instead of documenting a list of registry edits and hoping they are applied consistently, dohctl keeps the behavior in one PowerShell script with clear output before and after changes.

What it does

Running dohctl without arguments applies machine-wide Windows policy values that disable DNS over HTTPS behavior:

.\dohctl.ps1

Running it with -Restore removes the managed policy values it controls:

.\dohctl.ps1 -Restore

The script checks for administrator privileges before making changes, displays the current and final DoH policy state, flushes the DNS client cache, and exits with a nonzero status if a registry operation or cache flush fails.

How it works

dohctl writes policy values under these Windows registry paths:

HKLM:\SOFTWARE\Policies\Microsoft\Windows NT\DNSClient
HKLM:\SOFTWARE\Policies\Microsoft\Windows\Networking
HKLM:\SYSTEM\CurrentControlSet\Services\Dnscache\Parameters

The main values it manages are:

When restore mode is used, the script removes those values instead of setting them. That makes the tool reversible without requiring someone to manually browse through HKLM and clean up each policy entry.

CI validation

The repository includes a GitHub Actions workflow that runs on a Windows runner and tests the behavior end to end.

The workflow parses the PowerShell script, installs it into a temporary folder, configures the runner to use Cloudflare DNS over HTTPS with UDP fallback disabled, and blocks outbound TCP and UDP port 53 so plaintext DNS cannot satisfy the test.

From there, the test verifies that Windows name resolution works through DoH before policy changes, runs dohctl.ps1, checks that the expected registry values exist, confirms name resolution fails while DoH is disabled and port 53 is blocked, then runs dohctl.ps1 -Restore and verifies name resolution works again after the policy values are removed.

That test setup only changes DNS and firewall settings inside the disposable GitHub Actions runner, then restores the original DNS configuration during cleanup.

Security notes

Disabling DoH makes DNS traffic visible to network administrators, DNS filtering tools, and upstream network operators. That may be exactly what a managed environment needs, but it also means DNS queries are no longer protected by DoH encryption.

This is not a security product, privacy product, compliance service, or managed protection system. It is an educational and administrative utility that changes local Windows policy values. Its behavior can still depend on Windows version, domain policy, application-level DNS behavior, network configuration, user permissions, and future platform changes.

Use it only on systems you own or administer, test it in the environment where you plan to use it, and understand the effect before applying it broadly.

Result

The result is intentionally small: one auditable PowerShell script, restore support, clear status output, focused error handling, and CI coverage that exercises the real Windows DNS behavior the tool is meant to control.

The repository is public here:

github.com/connorcarro/dohctl