findns

Languages: English | فارسی

findns

A fast, multi-protocol DNS resolver scanner for finding resolvers compatible with DNS tunneling.

Supports both UDP and DoH (DNS-over-HTTPS) resolvers with end-to-end tunnel verification through DNSTT and Slipstream.

Built for restricted networks where finding a working resolver is the difference between connectivity and isolation.

---

✨ Features

Feature	Description
UDP + DoH Scanning	Test both plain DNS (port 53) and DNS-over-HTTPS (port 443)
Full Scan Pipeline	Ping → Resolve → NXDOMAIN → EDNS → Tunnel → E2E in one command
️ Hijack Detection	Detect DNS resolvers that inject fake answers (NXDOMAIN check)
EDNS Payload Testing	Find resolvers that support large DNS payloads (faster tunnels)
E2E Tunnel Verification	Actually launches DNSTT/Slipstream clients to verify real connectivity
Resolver List Fetcher	Auto-download thousands of resolvers from public sources
Regional Resolver Lists	Built-in support for regional intranet resolver lists (7,800+ IPs)
⚡ High Concurrency	50 parallel workers by default — scans thousands of resolvers in minutes
JSON Pipeline	Output from one scan feeds into the next for multi-stage filtering
CIDR Input	Accept IP ranges like 185.51.200.0/24 — auto-expanded to individual hosts
️ Interactive TUI	Full terminal UI with guided setup — no flags to remember
Fully Offline	Zero-config: auto-loads bundled resolvers, no -i or -o needed

---

️ How It Works

          Restricted Network                   |     Open Internet
                                               |
   Client ──[UDP:53]──→ Resolver ──[UDP:53]──→ ️ DNSTT Server
   Client ──[HTTPS:443]──→ DoH Resolver ────→ ️ DNSTT Server
                                               |
           ↑ scanner tests this part ↑

Why DoH Matters

Transport	Port	Visibility	Restricted Networks
UDP DNS	53	Fully visible to DPI	Monitored, often blocked
DoT	853	TLS on known port	Often blocked
DoH	443	Looks like HTTPS	Hard to detect
DoQ	443/UDP	QUIC-based	Often disabled

The DNSTT server always listens on port 53 — that never changes. But the client can talk to the middleman resolver using different transports. DoH wraps DNS queries inside regular HTTPS, making it nearly invisible to firewalls.

---

Install

From Source

git clone https://github.com/SamNet-dev/findns.git
cd findns
go build -o findns ./cmd

Go Install

go install github.com/SamNet-dev/findns/cmd@latest

Download Binary

Pre-built binaries for Linux, macOS, and Windows are available on the Releases page.

# Example: Linux x64
curl -LO https://github.com/SamNet-dev/findns/releases/latest/download/findns-linux-amd64
chmod +x findns-linux-amd64
./findns-linux-amd64 --help

Requirements

• Go 1.24+ for building from source
• dnstt-client — only for e2e tunnel tests (--pubkey). Install: go install www.bamsoftware.com/git/dnstt.git/dnstt-client@latest
• slipstream-client — only for e2e Slipstream tests (--cert)
• curl — for e2e connectivity verification

Finding binaries: findns automatically searches for dnstt-client and slipstream-client in three places: 1) PATH 2) current directory 3) next to the findns executable. The simplest approach: place the binary next to findns.

Without --pubkey, the scanner still finds resolvers compatible with DNS tunneling — it tests ping, resolve, NXDOMAIN, EDNS, and tunnel delegation without needing dnstt-client.

---

Windows Guide

Windows is fully supported. Two ways to get started:

Option 1: Download Binary (Easiest)

1. Go to the Releases page
2. Download findns-windows-amd64.exe
3. Rename it to findns.exe (optional, for convenience)
4. Open cmd or PowerShell in the same folder
5. Run:

.\findns.exe --help

No Go installation needed — just download and run.

Option 2: Build from Source

Requires Go 1.24+ installed from go.dev/dl.

git clone https://github.com/SamNet-dev/findns.git
cd findns
go build -o findns.exe ./cmd

Run

Use .\findns.exe instead of findns in all commands:

# Fetch resolvers
.\findns.exe fetch -o resolvers.txt

# Full scan
.\findns.exe scan -i resolvers.txt -o results.json --domain t.example.com

# With e2e test
.\findns.exe scan -i resolvers.txt -o results.json ^
  --domain t.example.com --pubkey 

Tip: In PowerShell, use backtick ` for line continuation instead of ^.

Prerequisites

• curl — included by default in Windows 10/11
• dnstt-client.exe — place next to findns.exe or in a folder in your PATH (only for e2e DNSTT tests)
• slipstream-client.exe — same as above (only for e2e Slipstream tests)

Common Issues

Issue	Fix
ping shows 0% loss but scan fails	Run as Administrator — Windows ICMP requires elevated privileges
dnstt-client not found	Place dnstt-client.exe next to findns.exe or add its folder to PATH
PowerShell blocks execution	Use cmd.exe or run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Long commands break	Use backtick ` (PowerShell) or ^ (cmd) for line continuation

---

Quick Start

️ Interactive Mode (Easiest)

findns tui

Launches a full terminal UI that guides you through mode selection, resolver input, and scan configuration. No flags needed — just follow the prompts.

0️⃣ Zero-Config Offline Scan (Easiest)

No flags needed — findns auto-loads 7,800+ bundled Iranian resolvers and saves to results.json:

# Scan with just a domain — everything else is automatic
findns scan --domain t.example.com

# With e2e verification
findns scan --domain t.example.com --pubkey 

No -i flag? Uses bundled resolvers. No -o flag? Saves to results.json. Also auto-generates results_ips.txt with a plain IP list.

1️⃣ Get Resolver Lists

#  Download global UDP resolvers
findns fetch -o resolvers.txt

#  Include 7,800+ known regional resolvers (embedded, offline)
findns fetch -o resolvers.txt --local

#  Download DoH resolver URLs
findns fetch -o doh-resolvers.txt --doh

If the online download fails (e.g. GitHub is blocked), fetch automatically falls back to bundled resolvers — no internet needed.

2️⃣ Run Full Scan

…

3️⃣ Check Results

Results are saved as JSON with an auto-generated _ips.txt companion file. The passed array contains resolvers that survived all steps, sorted by performance:

{
  "passed": [
    {"ip": "1.1.1.1", "metrics": {"ping_ms": 4.2, "resolve_ms": 15.3, "edns_max": 1232}},
    {"ip": "8.8.8.8", "metrics": {"ping_ms": 12.7, "resolve_ms": 22.1, "edns_max": 1232}}
  ]
}

---

Commands

️ tui — Interactive Terminal UI

findns tui

A guided terminal interface for the full scan workflow. No flags or files needed — the TUI walks you through everything:

1. Mode selection — Choose UDP or DoH scanning
2. Input selection — Pick from bundled resolver lists (7,854 known resolvers, CIDR range scans with configurable sampling, or load your own file)
3. Configuration — Set domain, workers, timeout, toggle options (Skip Ping, NXDOMAIN, EDNS). E2E testing is optional — toggle it on to see binary availability status and configure pubkey/cert
4. Live progress — Watch each scan step with progress bars, pass/fail counts, and elapsed time
5. Results — Scrollable ranked table with all metrics

Keyboard: ↑/↓ navigate, Tab next field, Space toggle, Enter confirm, q cancel/quit, Ctrl+C force quit.

---

scan — All-in-One Pipeline (Recommended)

Automatically chains the right scan steps based on your flags. This is the recommended way to use the scanner.

findns scan --domain t.example.com

-i and -o are optional. Without -i, bundled Iranian resolvers are used. Without -o, results save to results.json.

UDP mode pipeline: ping → nxdomain → resolve/tunnel → e2e (add --edns for EDNS payload check) DoH mode pipeline: doh/resolve/tunnel → doh/e2e

When --domain is set, the basic resolve step (A record for google.com) is skipped — tunnel domains have no A record, so findns goes straight to resolve/tunnel.

Flag	Description	Default
--domain	Tunnel domain (enables tunnel/e2e steps)	—
--pubkey	DNSTT server public key (enables e2e test)	—
--cert	Slipstream cert path (enables Slipstream e2e)	—
--test-url	URL to fetch through tunnel for e2e test	http://httpbin.org/ip
--proxy-auth	SOCKS proxy auth as user:pass (for e2e tests)	—
--doh	Scan DoH resolvers instead of UDP	false
--edns	Include EDNS payload size check	false
--edns-size	EDNS0 UDP payload size in bytes (larger = better throughput)	1232
--cidr	Scan a CIDR range directly (e.g. --cidr 5.52.0.0/16)	—
--skip-ping	Skip ICMP ping step	false
--skip-nxdomain	Skip NXDOMAIN hijack check	false
--top	Number of top results to display	10
--output-ips	Write plain IP list alongside JSON	auto

---

fetch — Download Resolver Lists

Automatically downloads and deduplicates resolver lists from public sources.

# Global UDP resolvers (from trickest/resolvers)
findns fetch -o resolvers.txt

# Include 7,800+ known regional resolvers (embedded, no download needed)
findns fetch -o resolvers.txt --local

# DoH resolver URLs (19+ well-known + public lists)
findns fetch -o doh-resolvers.txt --doh

Built-in DoH endpoints include:

• Google (dns.google)
• Cloudflare (cloudflare-dns.com)
• Quad9 (dns.quad9.net)
• AdGuard, Mullvad, NextDNS, LibreDNS, BlahDNS, and more

---

local — Export Bundled Regional Data

Export regional resolver data bundled inside the binary. No internet connection needed.

Two modes:

…

Flag	Description	Default
--discover	Switch to discovery mode (CIDR expansion)	false
--sample N	[discover] Random IPs per subnet	10
--full	[discover] Export all ~10.8M IPs	false
--batch N	[discover] Export exactly N IPs (use with --offset)	0
--offset N	[discover] Skip N IPs before starting batch	0
--list-ranges	Print embedded CIDR ranges and exit	false

---

ping — ICMP Reachability

findns ping -i resolvers.txt -o result.json
findns ping -i resolvers.txt -o result.json -c 5 -t 2

Metric: ping_ms (average RTT)

---

resolve — DNS Resolution Test

findns resolve -i resolvers.txt -o result.json --domain google.com

Metric: resolve_ms (average resolve time)

---

resolve tunnel — NS Delegation Check

Tests whether a resolver can see your tunnel's NS records and resolve the glue A record.

findns resolve tunnel -i resolvers.txt -o result.json --domain t.example.com

Metric: resolve_ms (average NS + glue query time)

---

️ nxdomain — DNS Hijack Detection

Tests whether resolvers return proper NXDOMAIN for non-existent domains. Hijacking resolvers return fake NOERROR answers — these are not safe for tunneling.

findns nxdomain -i reso