dohctl

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 that Windows uses for Group Policy, then reports the resulting state and flushes the DNS client cache so changes are applied immediately.

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

This repository is small by design: one auditable PowerShell script, clear usage examples, and documentation that explains exactly which system settings are changed.

Disclaimer

dohctl is provided solely as an educational and administrative utility, without warranty of any kind and without any representation that it is complete, reliable, secure, compliant, or suitable for any particular purpose. It is not a security product, privacy product, compliance service, managed protection system, or substitute for professional review. Its behavior can vary based on Windows version, domain policy, application-level DNS behavior, network configuration, user permissions, and future platform changes.

Use of this project is entirely at your own risk. You are responsible for deciding whether to run it, testing it in your own environment, understanding its effects, and accepting any consequences that result from use, misuse, failure, misconfiguration, policy conflict, network interruption, data exposure, security incident, or other outcome. The author is not responsible or liable for damages, losses, claims, penalties, legal issues, operational problems, security failures, privacy failures, or any other consequences related to this software.

Contents

• Overview
• Disclaimer
• Requirements
• Installation
• Usage
• Features
• Exit Behavior
• Security Notes
• How It Works
• Continuous Integration
• Development
• Project Structure
• Troubleshooting
• License

Overview

DNS over HTTPS encrypts DNS queries by sending them over HTTPS instead of standard DNS transport. That can improve privacy in some environments, but it can also bypass network controls that depend on traditional DNS visibility.

dohctl applies local machine policy values that tell Windows not to use DoH automatically or through configured policy. It also provides status output before and after changes so the operator can see which policy values are currently present.

Requirements

• Windows 10 version 1903 or later, Windows 11, or Windows Server 2019/2022
• PowerShell 5.1 or later
• Administrator privileges
• Local permission to modify HKLM registry policy keys

Installation

Clone the repository with the connorcarro SSH host alias:

git clone git@connorcarro:connorcarro/dohctl.git
cd dohctl

If you downloaded the script manually, unblock it before first use:

Unblock-File -Path ".\dohctl.ps1"

Usage

Run PowerShell as Administrator before executing the script.

Disable DNS over HTTPS:

.\dohctl.ps1

Restore DNS over HTTPS policy behavior:

.\dohctl.ps1 -Restore

Run with a temporary execution policy bypass:

powershell.exe -ExecutionPolicy Bypass -NoProfile -File ".\dohctl.ps1"

Features

• Applies Windows DNS over HTTPS policy through registry-backed Group Policy values
• Supports restore mode for removing the policy values it manages
• Checks for administrator privileges before making system changes
• Displays current and final DoH policy state
• Flushes the DNS client cache after changes
• Exits with a nonzero status if registry changes or DNS cache flushing fail
• Uses focused error handling for registry writes, removals, and cache reset
• Keeps the implementation in a single PowerShell script for easy review

Exit Behavior

dohctl exits with code 0 when the requested action and DNS cache flush complete successfully. It exits with code 1 when administrator privileges are missing, an unexpected exception occurs, a managed registry value cannot be written or removed, or the DNS cache cannot be flushed.

Security Notes

Disabling DoH can make DNS traffic visible to network administrators, DNS filtering tools, and upstream network operators. That may be desired in managed environments, but it also means DNS queries are no longer protected by DoH encryption.

Use this tool only on systems you own or administer. Domain-level Group Policy can override local settings, and some applications may implement their own DNS behavior outside of Windows DNS Client policy.

How It Works

dohctl writes policy values under these registry paths:

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

The main policy values are:

Value	Setting	Purpose
DoHPolicy	3	Disables DNS over HTTPS name resolution policy
EnableAutoDoh	0	Prevents automatic DoH behavior
DoHFlags	0	Clears DoH-related policy flags
DisableDoH	1	Explicitly disables DoH at the Windows networking policy level

When restore mode is used, the script removes those values instead of setting them.

Continuous Integration

The GitHub Actions workflow runs on a Windows runner and checks the project end to end:

• Parses dohctl.ps1 with PowerShell's parser
• Installs the script into a temporary folder
• Configures the Windows runner to use Cloudflare DNS over HTTPS with UDP fallback disabled
• Blocks outbound TCP and UDP port 53 so plaintext DNS cannot satisfy the test
• Verifies Windows name resolution succeeds through DoH before policy changes
• Runs dohctl.ps1 and asserts the expected registry policy values exist
• Verifies Windows name resolution fails while DoH is disabled and port 53 is blocked
• Runs dohctl.ps1 -Restore and asserts those values were removed
• Verifies Windows name resolution succeeds again after DoH policy is restored

The CI test changes DNS settings and firewall rules only inside the disposable GitHub Actions runner, then restores the original DNS configuration in cleanup.

Development

The repository intentionally avoids dependencies. Changes should keep the script readable, reversible, and easy to audit.

Recommended checks before publishing changes:

powershell.exe -NoProfile -Command "$null = [System.Management.Automation.PSParser]::Tokenize((Get-Content -Raw .\dohctl.ps1), [ref]$null)"

For manual validation, run the script in an elevated PowerShell session on a non-production Windows machine and confirm the displayed final status matches the expected policy state.

Project Structure

dohctl/
+-- .github/
|   +-- workflows/
|       +-- test.yml
+-- assets/
|   +-- banners/
|       +-- banner.svg
+-- tests/
|   +-- Test-Dohctl.ps1
+-- dohctl.ps1
+-- README.md

Troubleshooting

PowerShell says script execution is disabled

Use a temporary execution policy bypass:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
.\dohctl.ps1

PowerShell says the file is not digitally signed

Unblock the local file:

Unblock-File -Path ".\dohctl.ps1"

Or run it with an execution policy bypass:

powershell.exe -ExecutionPolicy Bypass -NoProfile -File ".\dohctl.ps1"

Registry access is denied

Run PowerShell as Administrator. The script modifies HKLM policy keys, which require elevated privileges.

Changes do not appear immediately

The script flushes the DNS client cache automatically. If an application still appears to use old resolver behavior, restart the application or reboot the machine.

License

This project is licensed under the MIT License. See LICENSE.