Metadata-Version: 2.4
Name: dns-leak-detective
Version: 0.1.0
Summary: Detect DNS leaks: verify your queries go through your chosen DNS server
Project-URL: Homepage, https://blog.cuttle.af/adguard-home-nymvpn-dns/
Project-URL: Repository, https://git.cuttle.af/cuttle/adguard-home-nym-dns
Author-email: Cuttle <blog@cuttle.af>
License: MIT
Keywords: adguard,dns,leak,privacy,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: dnspython>=2.0
Description-Content-Type: text/markdown

# DNS Leak Detective

Verify your DNS queries go through your chosen DNS server — not some upstream resolver you never agreed to.

## Why?

You set up AdGuard Home, Pi-hole, or a custom DNS server. You pointed every device at it. But how do you *know* no queries are leaking past it to Google DNS or your ISP?

`dns-leak-detective` resolves real domains against your system's resolver and checks whether the responding server matches your expected DNS — locally, with zero API calls.

## Install

```bash
pip install dns-leak-detective
```

## Usage

```bash
# Basic: check against a single expected DNS server
dns-leak-detective --expected 192.168.1.50

# Multiple expected servers (e.g. primary + secondary)
dns-leak-detective --expected 192.168.1.50 192.168.1.51

# Verbose: see every query result
dns-leak-detective --expected 192.168.1.50 --verbose
```

## Example output

```
  System resolver: 192.168.1.50
  Expected DNS:    192.168.1.50
  Test domains:    10

  OK:      10/10
  Leaks:   0/10
  Timeout: 0/10

  ✓  No leaks detected. All queries went through expected DNS.
```

If a query hits an unexpected server:

```
  ⚠  DNS LEAK DETECTED!
  Queries reached unexpected DNS servers:
    8.8.8.8: example.com, google.com

  Your DNS queries are NOT all going through your expected server.
```

## How it works

- Reads your system resolver from `/etc/resolv.conf`
- Sends A-record queries for 10 well-known domains
- Checks the *responding* DNS server IP against your expected server(s)
- Reports leaks — all locally, no external API calls, no telemetry

## Requirements

- Python 3.10+
- `dnspython` (installed automatically)

## Related

- [Block Ads on Every Device With a DNS Server That Whispers](https://blog.cuttle.af/adguard-home-nymvpn-dns/) — the blog post that inspired this tool
- [Companion repo](https://git.cuttle.af/cuttle/adguard-home-nym-dns) — AdGuard Home + NymVPN setup guide
