Binary reference

dns-leak

DNS leak detection and analysis for Kodachi OS

Version10.0.3Size9.8MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://digi77.com

File Information

Property	Value
Binary Name	dns-leak
Version	10.0.3
Build Date	Not disclosed
Rust Version	1.99.1
File Size	9.8MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	DNS leak detection and analysis for Kodachi OS
Git Commit	965cdb7bfc3f8b5a82dfb9534585333fc4fb9283
Metadata Generated	2026-11-13T16:19:53Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

583cccb34bbe7c95905a8c061f2890f50c939e4d4e22abaddb041375bd31ce42

Features

#	Feature
1	Network interface discovery and validation
2	DNS leak detection via challenge-response testing
3	Geolocation-based leak analysis
4	Multi-interface simultaneous testing
5	Detailed test reporting with JSON export
6	System resolver configuration analysis

Security Features

Feature	Description
Authentication	Secure authentication for sensitive operations
Encryption	HTTPS for all external API communications
Input Validation	All interface names and IDs are sanitized and validated
Rate Limiting	Built-in retry limits and timeouts for DNS queries

System Requirements

Requirement	Value
OS	Linux (Debian-based, specifically Kodachi OS)
Privileges	root/sudo for network interface access
Dependencies	Network interfaces, DNS resolver access, Internet connectivity for leak testing

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output
`-V, --discover-verbose`	Verbose interface details (discover only, repeat -VV for more)
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--timeout <SECS>`	Set timeout (default: 30)
`--retry <COUNT>`	Retry attempts (default: 3)
`--dns-timeout <SECS>`	DNS query timeout (default: 5)
`-i, --interface <IF>`	Specify network interface to test
`--show-public-ip`	Show unmasked public IP in output and saved files (default: masked)
`--keep-all`	Keep all result files (default: older files pruned for privacy)
`--provider <NAME>`	Leak test service: kodachi (default, kodachi.cloud's own test, no third party sees the lookups) or bash.ws (third-party)

Commands

Network Discovery

`discover`

Discover network interfaces available for testing (no root, no authentication needed)

Usage:

dns-leak discover [OPTIONS]

Options:

-V, --discover-verbose: Verbose interface details, repeat (-VV) for more. The global --verbose flag does NOT affect this command

Examples:

dns-leak discover

dns-leak discover --json

dns-leak discover -V

DNS Leak Testing

`test`

Run DNS leak test on specified interface or all interfaces (requires prior online-auth authentication; this is also what a bare `dns-leak` runs)

Usage:

dns-leak test [OPTIONS]

Options:

-i, --interface <INTERFACE>: Specify a network interface to test
--dns-timeout <SECONDS>: DNS query timeout, 1-60 seconds
--show-public-ip: Print and save the unmasked public IP (masked by default)
--keep-all: Keep every result file (by default older result files are pruned)
--provider <kodachi|bash.ws>: DNS leak service that confirms the test: kodachi is kodachi.cloud's own test (no third party sees the lookups), bash.ws the third-party one; no automatic fallback

Examples:

dns-leak test

dns-leak test --provider kodachi

dns-leak test --provider bash.ws

dns-leak test --interface tun0

dns-leak test --json

dns-leak test --provider bash.ws --json

dns-leak test --keep-all

Reporting

`report`

Generate a detailed report of a previous test (run the test with --keep-all if you want old result files to survive)

Usage:

dns-leak report -r <ID>

Options:

-r, --id <ID>: Test ID to generate report for

Examples:

dns-leak report --id dns_leak_results_<TIMESTAMP>

dns-leak report --id dns_leak_results_<TIMESTAMP> --json

`results`

Display results from a previous DNS leak test (run the test with --keep-all if you want old result files to survive)

Usage:

dns-leak results --file <FILE>

Options:

-f, --file <FILE>: Path to the results JSON file

Examples:

dns-leak results --file test_results.json

dns-leak results --file test_results.json --json

`udp-leak`

Check whether UDP traffic (WebRTC, calls, games) can leave outside Tor or the VPN: sends ONE UDP packet to stun.cloudflare.com, so if UDP is not blocked Cloudflare sees the address it leaves from (the leak being tested); compared with the public TCP address. With no UDP answer the same server is asked over TCP, and only its answer proves UDP is blocked; otherwise the result is unknown. IPv4 only (UDP over IPv6 is not tested). Runs only when you start it

Usage:

dns-leak udp-leak [--json]

Examples:

dns-leak udp-leak

dns-leak udp-leak --json

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Quick Start

List the interfaces you can test, then test them for DNS leaks. No root is needed for any dns-leak command, but the leak test itself needs an active online-auth session.

Step 1: See which network interfaces can be tested

dns-leak discover

Expected Output: One block per interface with its name, type, IP addresses, DNS resolution state and configured DNS servers (loopback is excluded)

Step 2: Run the default DNS leak test on every active interface (identical to `dns-leak test`)

dns-leak

Expected Output: Per-interface DNS servers with their country, plus a leak verdict for each interface

Note

Needs an authenticated session and internet access. Without a session it exits with 'Authentication required for command: test'; run `online-auth authenticate` first.

Step 3: Check that a VPN tunnel is not leaking DNS to the ISP resolver

dns-leak test --interface tun0

Expected Output: DNS servers observed through tun0 and a leak verdict for that interface

Step 4: Run the leak test and emit machine-readable JSON

dns-leak test --json

Expected Output: A result envelope whose data carries the per-interface findings and the potential_leak_detected flag

Scenario 2: Interface Discovery

Find out which interfaces exist before you test one. Loopback (lo) is always excluded. Discovery needs no authentication.

Step 1: List all interfaces available for DNS leak testing

dns-leak discover

Expected Output: Interface names with type, IP addresses, DNS resolution state and DNS servers, for example eth0, wlan0 and tun0

Step 2: Same list with the extra per-interface detail

dns-leak discover -V

Expected Output: Interface list plus is-up, loopback, interface-type and address-count fields

Note

-V is short for --discover-verbose and can be repeated (-VV) for more detail. The global --verbose flag does NOT change discovery output.

Step 3: List interfaces as JSON for automation

dns-leak discover --json

Expected Output: JSON envelope with data.interfaces[] and data.total_count

Step 4: Extract only interface names, ready to loop over in a script

dns-leak discover --json | jq '.data.interfaces[].name'

Expected Output: One quoted interface name per line

Scenario 3: DNS Leak Testing

Test every active interface, or one interface by name. Interface names follow the usual Linux schemes: eth0, ens33, enp2s0 and eno1 (wired), wlan0 and wlx<mac> (wireless), tun0 and tailscale0 (VPN), br0 (bridge). Take the exact name from `dns-leak discover`. Every test needs an authenticated session and internet access.

Step 1: Test all active non-loopback interfaces for DNS leaks

dns-leak test

Expected Output: A block per interface listing the DNS servers that answered, their country, and a leak verdict

Note

Needs an active online-auth session and internet access. The exit code is 0 whether or not a leak was found: read the leak verdict, or data.potential_leak_detected with --json.

Step 2: Test a single named interface instead of all of them

dns-leak test --interface eth0

Expected Output: DNS leak test result for eth0 only

Note

Replace eth0 with any name reported by `dns-leak discover` (wlan0, tun0, enp2s0, tailscale0, br0, ...). Unknown or malformed names are rejected before the test runs.

Step 3: Verify a VPN tunnel: confirm DNS queries leave through the tunnel and not through the ISP resolver

dns-leak test --interface tun0

Expected Output: DNS servers seen through tun0 with their country, compared against your visible exit location

Note

This is the check worth running right after connecting a VPN or Tor.

Step 4: Reduce a full test to a single true/false for scripting

dns-leak test --json | jq '.data.potential_leak_detected'

Expected Output: true or false

Scenario 4: Which Service Confirms the Test (--provider)

The test looks up unique names through your system resolver, then asks a DNS leak service which resolvers really looked them up. kodachi (the default) is kodachi.cloud's own test: its nameserver records the resolvers, so no third party sees the lookups. bash.ws is the third-party test. The result always names the provider, and there is no automatic fallback.

Step 1: Run the test confirmed by kodachi.cloud's own DNS leak test (the same as `dns-leak test`)

dns-leak test --provider kodachi

Expected Output: Provider: kodachi.cloud (Kodachi's own DNS leak test), the resolvers kodachi.cloud saw with their networks, and the leak verdict

Note

If kodachi.cloud cannot confirm the test, the result says so with the reason and names `dns-leak test --provider bash.ws` as the next step.

Step 2: Run the same test confirmed by the third-party bash.ws service

dns-leak test --provider bash.ws

Expected Output: Provider: bash.ws (third-party DNS leak test) and the usual leak report

Note

bash.ws sees the test names your resolvers look up. Use it as a second opinion, or when kodachi.cloud cannot be reached.

Step 3: Show which provider confirmed the test and kodachi.cloud's resolver report

dns-leak test --json | jq '.data.provider, .data.kodachi_report'

Expected Output: "kodachi", then the report: resolvers with their network, whether each is in your address's network, and any subnet a resolver passed on

Note

data.provider is always present. data.kodachi_report is present only when kodachi.cloud answered; data.provider_next_step only when it could not confirm the test.

Step 4: Machine-readable result confirmed by bash.ws

dns-leak test --provider bash.ws --json

Expected Output: A result envelope whose data carries "provider": "bash.ws" and the usual findings

Scenario 5: Privacy and Result Files

By default dns-leak masks your public IP and prunes older result files. Both flags below opt out of that, so reach for them deliberately.

Step 1: Show the real public IP instead of the masked one

dns-leak test --show-public-ip

Expected Output: The usual leak report, but the public IP is printed in full rather than partially masked

Note

PRIVACY: the unmasked IP is also written into the saved JSON result file, which stays on disk. Use it only when you need the exact address, for example when filing a bug, and delete the result file afterwards.

Step 2: Keep every result file instead of pruning the older ones

dns-leak test --keep-all

Expected Output: The test runs normally and no previous dns_leak_results_*.json file is removed

Note

Without this flag a text-mode test prunes older result files, so the files that `results --file` and `report --id` need can vanish. Kept files record DNS servers and timestamps, so clean them up yourself.

Step 3: Keep the result file of a tunnel test so you can report on it later

dns-leak test --interface tun0 --keep-all --json

Expected Output: JSON envelope for tun0, with its dns_leak_results_<TIMESTAMP>.json file left in the results directory

Scenario 6: Reports and Saved Results

Re-open a test you already ran. Both commands read the dns_leak_results_*.json files in the results directory, so the test that produced them must have been run with --keep-all if it is not the most recent one.

Step 1: Print a saved test result again, without re-running the test

dns-leak results --file dns_leak_results_<TIMESTAMP>.json

Expected Output: The same per-interface DNS servers and leak verdict as the original run

Note

Replace <TIMESTAMP> with a real filename from a prior run. The file is looked up in the current directory first, then in the results directory, so a bare filename is enough.

Step 2: Re-emit a saved result as JSON

dns-leak results --file dns_leak_results_<TIMESTAMP>.json --json

Expected Output: JSON envelope holding the stored test result

Step 3: Build a shareable HTML report from a saved test

dns-leak report --id dns_leak_results_<TIMESTAMP>

Expected Output: Report generated successfully: <results directory>/dns_leak_report_<TIMESTAMP>.html

Note

The ID is the result filename without the .json extension. A partial ID also works: the first result file whose name contains it is used.

Step 4: Report on the first matching saved test and print the status as JSON

dns-leak report --id dns_leak_results --json

Expected Output: JSON envelope with status success once the HTML report is written

Note

This is the partial-ID form: it matches the first dns_leak_results_*.json file in the results directory, so pass a full ID when it matters which.

Scenario 7: Timeouts and Retries

Slow links, captive portals and Tor exits can need longer waits than the defaults.

Step 1: Give the external leak-check calls more time and more attempts

dns-leak test --timeout=30 --retry=3

Expected Output: The usual leak report, just slower to give up

Note

Timeout range: 1-300 seconds. Retry count: 1-20. This bounds the HTTP calls, not the DNS queries.

Step 2: Wait longer for each individual DNS query to answer

dns-leak test --dns-timeout=10

Expected Output: The usual leak report, with slow resolvers given 10 seconds instead of the default

Note

DNS timeout range: 1-60 seconds. Separate from --timeout, which bounds the HTTP verification calls.

Step 3: Test one slow wireless link with both waits raised

dns-leak test --interface wlan0 --dns-timeout=15 --timeout=60

Expected Output: DNS leak test result for wlan0

Scenario 8: Program Information

Version, capabilities, help and examples, in text or JSON.

Step 1: Show the version number

dns-leak --version

Expected Output: dns-leak version <VERSION>

Step 2: Version with build date, commit and Rust version, as JSON

dns-leak --version --json

Expected Output: JSON envelope with name, version, buildDate, gitCommit

Step 3: Show what this tool does, its features and its requirements

dns-leak --info

Expected Output: Program description, feature list, security features and system requirements

Step 4: The same capability record, machine-readable

dns-leak --info --json

Expected Output: JSON envelope with the program info structure

Step 5: Show every command, option and exit code

dns-leak --help

Expected Output: Grouped command list with options and global flags

Step 6: Show the help for a single subcommand

dns-leak test --help

Expected Output: clap help for `test` with its own flags

Step 7: Show only the examples that apply to one subcommand

dns-leak test --examples

Expected Output: The test examples, without the discover/report/results ones

Step 8: All examples as JSON, for docs and tooling

dns-leak --examples --json

Expected Output: JSON envelope with categories[] and quickReference[]

Scenario 9: UDP Leak Check (WebRTC, calls, games)

Tor and many proxies carry TCP only. This check sends ONE UDP packet (a STUN request) to stun.cloudflare.com:3478 and compares the address Cloudflare sees with the address TCP traffic shows, so a UDP path around Tor or the VPN is found. If UDP is not blocked, Cloudflare sees the address the packet leaves from: that is the leak being tested. With no UDP answer the same server is asked over TCP, and only its answer proves UDP is blocked; otherwise the result is unknown, never a pass. It runs only when you start it.

Step 1: Find out whether UDP can leave outside Tor or the VPN

dns-leak udp-leak

Expected Output: UDP leak check : PASS (UDP blocked) Checked : IPv4 only: UDP over IPv6 is not tested by this check STUN server : stun.cloudflare.com:3478 UDP shows : nothing (no answer) TCP shows : 203.0.113.7 Route : tun0 (tunnel) No STUN answer over UDP while the same server answered over TCP: UDP cannot leave this machine, so WebRTC and other UDP traffic cannot reveal an address.

Note

PASS (UDP blocked) is the expected result while torrified. LEAK names the address UDP revealed; turn on torrify or the kill switch, or use a VPN that carries UDP. UNKNOWN means it was not proven either way (no UDP answer and no TCP answer either, or no TCP address to compare). Needs an authenticated session, like test.

Step 2: The same check as JSON, for the dashboard and scripts

dns-leak udp-leak --json

Expected Output: {"verdict":"blocked","checked":"IPv4 only: UDP over IPv6 is not tested by this check","leak":false,"stun_server":"stun.cloudflare.com:3478","udp_public_address":null,"tcp_public_ip":"203.0.113.7","egress_interface":"tun0","egress_is_tunnel":true,...}

Note

verdict is blocked, same_exit, leak or unknown: read verdict. leak is true for a confirmed leak, false for a proven pass and null when the verdict is unknown.

Environment Variables

Variable	Description	Default	Values
`RUST_LOG`	Set logging level	info	error\|warn\|info\|debug\|trace
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
0	Success; a finished test exits 0 whether or not it found a leak (read data.potential_leak_detected)
1	General error, including an authentication refusal (with --json, the error's code field names its kind)
2	Invalid arguments