Binary reference

dns-leak

DNS leak detection and analysis for Kodachi OS

Version9.8.4 (build 320)Size9.7MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://digi77.com

File Information

Property	Value
Binary Name	dns-leak
Version	9.8.4 (build 320)
Build Date	Not disclosed
Rust Version	1.97.0
File Size	9.7MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	DNS leak detection and analysis for Kodachi OS
Git Commit	380cf2105c2f50da0f6608989a43a29f3e6ad9ce
Metadata Generated	2026-08-10T13:22:55Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

9f3cf0acb4f2ffec50c9e36339a0640a3341a0d793df7ff66df6cefd6a2abdca

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)

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)

Examples:

dns-leak test

dns-leak test --interface tun0

dns-leak test --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

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. Exit code 7 signals that a DNS leak was detected.

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: 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 5: 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 6: 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 7: 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[]

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
1	General error
2	Invalid arguments
3	Permission denied
4	Network error
5	File not found
6	Authentication required
7	DNS leak detected