DNS Leak Guide
Detect DNS queries escaping your VPN or Tor tunnel across every network interface, in real time. This guide walks audit scenarios; the CLI catalog holds every flag.
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
Binary Reference
dns-leak is version 10.0.3 (build 75), 9.8MB, Proprietary, authored by Warith Al Maawali. The full binary metadata, the SHA256 checksum, the raw JSON, global options, and the complete command catalog are generated on the dns-leak CLI reference, so I do not duplicate them here. This page stays focused on how to run leak audits.
Key Features
DNS Leak Detection & Analysis
| Feature | Description |
|---|---|
| Multi-Interface Testing | Tests every active non-loopback interface in one run, one after another |
| Leak Identification | Pinpoints exactly where DNS queries are leaking |
| Real-time Analysis | Sends unique challenge lookups and checks which DNS servers actually answered them |
| Comprehensive Reporting | Detailed reports with analysis and findings |
| UDP and WebRTC Leak Test | Checks whether UDP traffic, which Tor does not carry, can leave by another path than your web traffic |
Why DNS Leak Detection is Critical
| Benefit | Description |
|---|---|
| Privacy Protection | Even with VPN/Tor, DNS leaks can reveal your location |
| ISP Bypass Verification | Confirms DNS queries bypass your ISP |
| Configuration Validation | Verifies your privacy setup is correct |
| Continuous Monitoring | Regular testing ensures ongoing protection |
TL;DR - Essential Commands
# Discover available network interfaces
dns-leak discover
# Run DNS leak test on all interfaces
dns-leak test
# Test specific interface
dns-leak test -i eth0
# View results from previous test
dns-leak results --file dns_leak_results_<TIMESTAMP>.json
dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json
# Generate detailed report
dns-leak report --id dns_leak_results
The test confirms its result with Kodachi's own DNS leak test at kodachi.cloud unless you add --provider bash.ws, and its output always names the test it used. See Which Test Confirms the Result.
# Can UDP (WebRTC, calls, games) leave outside Tor or the VPN?
dns-leak udp-leak
Understanding DNS Leaks
What is a DNS Leak?
A DNS leak occurs when your DNS queries bypass your VPN or Tor connection and go directly to your ISP's DNS servers.
This reveals:
| Information Leaked | Description |
|---|---|
| Websites visited | All domains you're accessing |
| Real location | Your actual geographic location |
| ISP identity | Your Internet Service Provider |
How DNS Leak Detection Works
# Step 1: Discover network interfaces
dns-leak discover
This shows all network interfaces that could potentially leak DNS.
# Step 2: Run comprehensive test
dns-leak test
The test process:
| Step | Action |
|---|---|
| 1 | Sends DNS queries through each interface |
| 2 | Monitors where queries are routed |
| 3 | Identifies any leaks to ISP or public DNS |
| 4 | Reports which interfaces are secure |
Which Test Confirms the Result: kodachi.cloud or bash.ws
After its local checks, dns-leak test asks an outside service which DNS resolvers really answered for this machine. By default that service is Kodachi's own DNS leak test at kodachi.cloud, so no third party sees the lookups. The same test runs in a browser at kodachi.cloud/tools/dns.html.
Before you run it: log in to Kodachi first, from the dashboard's login or with sudo online-auth authenticate. Without a login the test stops and says so (exit code 1).
How the kodachi.cloud test works: dns-leak makes up a random token, looks up ten names under leak.kodachi.cloud through your normal resolver, then asks kodachi.cloud which resolvers asked for that token. The report names each resolver, its network (AS number and holder), whether it sits in your own network, and any subnet a resolver passed on with the query. kodachi.cloud looks up each resolver's network at RIPE NCC and nowhere else.
# Confirm with Kodachi's own test at kodachi.cloud (the default)
dns-leak test
dns-leak test --provider kodachi
# Confirm with the third-party bash.ws test instead
dns-leak test --provider bash.ws
# JSON for scripts: provider, provider_host and kodachi_report
dns-leak test --json
| Provider | Who runs it | Who sees the test lookups | How to choose it |
|---|---|---|---|
| kodachi.cloud (default) | Kodachi | Your resolvers and kodachi.cloud only | nothing, or --provider kodachi |
| bash.ws | A third party | Your resolvers and bash.ws | --provider bash.ws |
The output always names the test it used, as one line: Provider: kodachi.cloud (Kodachi's own DNS leak test) or Provider: bash.ws (third-party DNS leak test). In JSON the same answer is in provider (kodachi or bash.ws) and provider_host.
If kodachi.cloud cannot confirm the result (no connection, the site does not answer, or it saw no resolver ask for the test names, which happens when the lookups are blocked or answered on this machine by a hosts file or a filter), dns-leak does not switch to bash.ws on its own. It finishes with its local checks, says why kodachi.cloud could not confirm, and names the next step: dns-leak test --provider bash.ws. In JSON that step is in provider_next_step, beside inconclusive_reason.
Exit codes, for scripts: a test that finished exits 0, whether or not it found a leak and whether or not the outside service could confirm it, so read potential_leak_detected and inconclusive_reason in the JSON for the answer. 1 means the test could not finish (for example DNS does not resolve, or the time limit ran out; the JSON error names which), and 2 means an invalid option, such as a --provider other than kodachi or bash.ws.
Reading the kodachi.cloud report (kodachi_report in JSON): resolvers lists each resolver with asn, holder, same_network (true, false, or not known), queries and the subnets it passed on. all_in_your_network is true when every resolver sits in your own network. subnet_not_yours is a warning: a resolver passed on a subnet that does not hold your address, so a server further along learned where you are.
Testing Specific Interfaces
# Test VPN interface
dns-leak test -i tun0
# Test Tor transparent proxy
dns-leak test -i eth0
# Test with custom timeout
dns-leak test --dns-timeout 10
UDP and WebRTC Leaks
Tor carries TCP only, and many proxy setups do the same. A UDP packet that slips past them leaves through the real network, and any site that uses WebRTC can then see the real address even though every page loads through Tor or the VPN. udp-leak tests exactly that.
It sends one UDP packet (a STUN request) to stun.cloudflare.com:3478 and compares the address Cloudflare sees with the public address your TCP traffic shows. If UDP is not blocked, Cloudflare sees the address the packet leaves from: that exposure is the leak being tested, the same one a WebRTC site would see.
| Result | Meaning |
|---|---|
| PASS (UDP blocked) | No UDP answer while the same server answered over TCP: UDP cannot leave, so WebRTC cannot reveal an address |
| PASS (same exit as TCP) | UDP leaves through the same exit as your web traffic, for example a VPN tunnel that carries UDP |
| LEAK | UDP leaves with a different public address: it bypasses Tor or the VPN and can reveal that address |
| UNKNOWN | Not proven either way: no answer over TCP either (a down server cannot be told from blocked UDP), the check could not run, or the TCP address to compare with is unknown. Never shown as a pass |
It checks IPv4 only: UDP that leaves over IPv6 is not tested. It runs only when you start it; nothing in Kodachi runs it automatically. Like the other leak tests, udp-leak needs you to be logged in (online-auth).
Analyzing Results
# View test results
dns-leak results --file dns_leak_results_<TIMESTAMP>.json
# Get results in JSON format for scripts
dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json
# JSON output examples for automation
dns-leak test --json # Test with JSON output
dns-leak discover --json # Interface discovery in JSON
# Generate detailed report with analysis
dns-leak report --id dns_leak_results
dns-leak report --id dns_leak_results --json # Report in JSON format
Result Interpretation:
| Status | Meaning |
|---|---|
| No DNS leak detected | No answering DNS server was flagged (your configured resolvers and their operators, or the upstreams of a local encrypted resolver) |
| NOT in system resolv.conf (potential leak!) | Shown per server: this server answered the test lookups but is not one your resolver configuration lists |
| DNS LEAK DETECTED (N servers found) | The run flagged a potential leak (for example DNS reaching your real ISP's resolver); the detected servers are listed with their country and ASN |
Multi-NIC Examples and Common Leak Scenarios
Multi-Interface Testing Examples:
# Test laptop with WiFi and Ethernet
dns-leak test -i wlan0 # WiFi interface
dns-leak test -i eth0 # Ethernet interface
# Test system with VPN
dns-leak test -i tun0 # VPN tunnel interface
dns-leak test -i wg0 # WireGuard interface
# Test all discovered interfaces
dns-leak discover # Show: wlan0, eth0, tun0, lo
dns-leak test # Test all automatically
Common Leak Scenarios:
| Scenario | Description |
|---|---|
| Split Tunnel VPN | Some traffic bypasses VPN (eth0 leaks while tun0 secure) |
| IPv6 Leaks | IPv6 DNS not routed through VPN |
| WebRTC Leaks | Browser bypassing system DNS |
| Misconfigured Firewall | DNS allowed outside VPN tunnel |
Advanced Commands
Custom DNS-server testing, batch interface runs, extended timeouts, JSON filtering, and verbose debug output are all documented with their exact flags on the auto-generated dns-leak command reference. The scenarios below cover the operational patterns that matter most in practice.
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Connection Testing | Test after every VPN/Tor connection |
| Location Changes | Re-test when changing network locations |
| Interface Coverage | Check all interfaces, not just primary |
| Periodic Monitoring | Run tests periodically during long sessions |
| Audit Trail | Save reports for security audits |
| Choose Who Sees the Test | The default kodachi.cloud test keeps the lookups between your resolvers and Kodachi. Use --provider bash.ws only when you want a second opinion from a third party; a kodachi.cloud failure never switches to it on its own |
Performance
| Metric | Value |
|---|---|
| Test Duration | 5-10 seconds per interface |
| Memory Usage | ~15MB during testing |
| CPU Usage | < 5% during tests |
| Network Traffic | < 1KB per DNS query |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: VPN Tunnel Validation Before Sensitive Work
Verify VPN tunnel integrity and DNS leak protection before conducting sensitive operations.
# Step 1: Check current routing configuration
sudo routing-switch status
# Step 2: Verify VPN interface is active
dns-leak discover
# Expected: tun0 or wg0 listed in available interfaces
# Step 3: Test VPN interface for DNS leaks
dns-leak test --interface tun0
# Step 4: Verify DNS configuration matches VPN
sudo dns-switch status
# Step 5: Check IP geolocation to confirm VPN endpoint
ip-fetch
# Expected: Location matches VPN server, not your real location
# Step 6: Comprehensive network verification
sudo health-control net-check
Cross-binary workflow: routing-switch + dns-leak + dns-switch + ip-fetch + health-control
When to run: Before accessing sensitive resources or conducting privacy-critical work. Automate this with workflow-manager using the connectivity-dns-leak-verify profile.
Scenario 2: Multi-NIC System Audit (WiFi + Ethernet + VPN)
Audit all network interfaces on systems with multiple NICs to identify potential leak vectors.
# Step 1: Discover all available interfaces
dns-leak discover -V
# Expected: wlan0, eth0, tun0, br0, etc.
# Step 2: Test WiFi interface
dns-leak test --interface wlan0
# Step 3: Test Ethernet interface
dns-leak test --interface eth0
# Step 4: Test VPN tunnel interface
dns-leak test --interface tun0
# Step 5: Run comprehensive test on all interfaces
dns-leak test --json | tee all-interfaces-test.json
# Step 6: Extract leak detection status
dns-leak test --json | jq '.data.potential_leak_detected'
# Expected: false
# Step 7: Verify geolocation for each active interface
ip-fetch
Cross-binary workflow: dns-leak + ip-fetch
When to run: On systems with multiple network interfaces or when diagnosing intermittent connectivity issues.
Scenario 3: Split Tunnel VPN Leak Detection
Detect DNS leaks in split tunnel VPN configurations where some traffic bypasses the VPN.
# Step 1: Check routing configuration for split tunnel
sudo routing-switch status
# Step 2: Test physical interface (should show leak if split tunnel)
dns-leak test --interface eth0
# Step 3: Test VPN tunnel interface (should be secure)
dns-leak test --interface tun0
# Step 4: Compare results from both tests
dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json
# Step 5: If leak detected on physical interface, reconfigure DNS
sudo dns-switch random
dns-leak test --interface eth0
# Expected: DNS now routed through secure servers
# Step 6: Verify no leaks remain
dns-leak test --json | jq '.data | select(.potential_leak_detected)'
# Expected: Empty output (no leaks)
Cross-binary workflow: routing-switch + dns-leak + dns-switch
When to run: When using split tunnel VPN configurations or experiencing DNS resolution issues.
Scenario 4: Bridge/Container Interface Isolation Testing
Test bridge and container interfaces to ensure DNS isolation in virtualized environments.
# Step 1: Discover bridge and container interfaces
dns-leak discover
# Expected: br0, docker0, veth*, etc.
# Step 2: Test bridge interface
dns-leak test --interface br0
# Step 3: Test primary network interface for baseline
dns-leak test --interface eth0
# Step 4: Compare DNS servers used by each interface
dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json | jq '.data | {interfaces: .interfaces_tested, dns_servers: [.dns_servers_detected[].ip]}'
# Step 5: Check for cross-interface DNS leakage
sudo health-control net-check
# Step 6: Generate comprehensive report
dns-leak report --id dns_leak_results --json
Cross-binary workflow: dns-leak + health-control
When to run: When running containerized applications or virtual machines requiring network isolation.
Scenario 5: Post-Connection Comprehensive Verification
Complete network verification workflow after establishing Tor or VPN connection.
# Step 1: Check network connectivity
sudo health-control net-check
# Step 2: Fetch current IP and geolocation
ip-fetch
# Step 3: Verify Tor connection (if using Tor)
ip-fetch check-tor
# Expected: "Connected through Tor" message
# Step 4: Check routing status
sudo routing-switch status
# Step 5: Verify DNS configuration
sudo dns-switch status
# Step 6: Run comprehensive DNS leak test
dns-leak test
# Step 7: View detailed results
dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json
# Step 8: Generate verification report
dns-leak report --id dns_leak_results
Cross-binary workflow: health-control + ip-fetch + routing-switch + dns-switch + dns-leak
When to run: After establishing any VPN or Tor connection. Automate this with workflow-manager using the base-network-verification profile.
Scenario 6: Investigating and Fixing Detected DNS Leaks
Systematic approach to identify, analyze, and remediate DNS leak vulnerabilities.
# Step 1: Run comprehensive DNS leak test
dns-leak test --json | tee leak-investigation.json
# Step 2: Identify which interfaces are leaking
cat leak-investigation.json | jq '.data | select(.potential_leak_detected) | .interfaces_tested'
# Step 3: Check current DNS configuration
sudo dns-switch status
# Step 4: Switch to secure DNS servers
sudo dns-switch random
# Step 5: Verify DNS change took effect
sudo dns-switch status
# Step 6: Re-test for leaks
dns-leak test
# Step 7: If leaks persist, enable Tor DNS
sudo tor-switch start-tor
sudo tor-switch start-tor-dns-nftables
# Step 8: Verify Tor DNS is active
sudo tor-switch verify-tor-dns
# Step 9: Final leak verification
dns-leak test --json | jq '.data.potential_leak_detected'
# Expected: false
# Step 10: Generate security score
sudo health-control security-score
Cross-binary workflow: dns-leak + dns-switch + tor-switch + health-control
When to run: Immediately when leak detection test shows vulnerabilities. Automate this with workflow-manager using the tor-dns-verify-leak or tor-dns-fallback profiles.
Scenario 7: WebRTC and UDP Leak Check
Before a video call or a site that uses WebRTC, confirm that UDP cannot reveal your real address.
# Step 1: Test UDP
dns-leak udp-leak
# Expected: PASS (UDP blocked) when torrified, or PASS (same exit as TCP) behind a UDP-capable VPN
# Step 2: The same check as JSON, for scripts
dns-leak udp-leak --json
# Step 3: If it reports LEAK, route the system through Tor so UDP is blocked
sudo tor-switch torrify-system-nftables
dns-leak udp-leak
Cross-binary workflow: dns-leak + tor-switch
When to run: Before calls or WebRTC sites, and after changing the VPN or Tor setup.
Related Workflows
- DNS Switch Guide, DNS server configuration and management
- Tor Switch Guide, Tor network and DNS over Tor setup
- Routing Switch Guide, Network routing configuration
- IP Fetch Guide, IP geolocation and Tor verification
- Health Control Guide, Network connectivity and security checks
- Full CLI Reference: dns-leak commands