{"id":46469648,"url":"https://github.com/samnet-dev/findns","last_synced_at":"2026-03-12T12:01:19.886Z","repository":{"id":342448449,"uuid":"1174000077","full_name":"SamNet-dev/findns","owner":"SamNet-dev","description":"Fast DNS tunnel resolver scanner — find working resolvers for dnstt, DoH, and other DNS tunnel tools","archived":false,"fork":false,"pushed_at":"2026-03-06T05:11:32.000Z","size":137,"stargazers_count":37,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T13:14:24.604Z","etag":null,"topics":["censorship","dns","dns-tunnel","dnstt","doh","iran","resolver","scanner"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamNet-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T01:00:04.000Z","updated_at":"2026-03-07T11:52:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SamNet-dev/findns","commit_stats":null,"previous_names":["samnet-dev/findns"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/SamNet-dev/findns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamNet-dev%2Ffindns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamNet-dev%2Ffindns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamNet-dev%2Ffindns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamNet-dev%2Ffindns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamNet-dev","download_url":"https://codeload.github.com/SamNet-dev/findns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamNet-dev%2Ffindns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30288776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["censorship","dns","dns-tunnel","dnstt","doh","iran","resolver","scanner"],"created_at":"2026-03-06T06:08:14.913Z","updated_at":"2026-03-09T09:01:26.192Z","avatar_url":"https://github.com/SamNet-dev.png","language":"Go","readme":"🌐 Languages: [English](#-findns) | [فارسی](#-findns-1)\n\n# 🔍 findns\n\n**A fast, multi-protocol DNS resolver scanner for finding resolvers compatible with DNS tunneling.**\n\nSupports both **UDP** and **DoH (DNS-over-HTTPS)** resolvers with end-to-end tunnel verification through [DNSTT](https://www.bamsoftware.com/software/dnstt/) and [Slipstream](https://github.com/Mygod/slipstream-rust).\n\n\u003e 🌐 Built for **restricted networks** where finding a working resolver is the difference between connectivity and isolation.\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔄 **UDP + DoH Scanning** | Test both plain DNS (port 53) and DNS-over-HTTPS (port 443) |\n| 🔗 **Full Scan Pipeline** | Ping → Resolve → NXDOMAIN → EDNS → Tunnel → E2E in one command |\n| 🛡️ **Hijack Detection** | Detect DNS resolvers that inject fake answers (NXDOMAIN check) |\n| 📏 **EDNS Payload Testing** | Find resolvers that support large DNS payloads (faster tunnels) |\n| 🚇 **E2E Tunnel Verification** | Actually launches DNSTT/Slipstream clients to verify real connectivity |\n| 📥 **Resolver List Fetcher** | Auto-download thousands of resolvers from public sources |\n| 🌍 **Regional Resolver Lists** | Built-in support for regional intranet resolver lists (7,800+ IPs) |\n| ⚡ **High Concurrency** | 50 parallel workers by default — scans thousands of resolvers in minutes |\n| 📋 **JSON Pipeline** | Output from one scan feeds into the next for multi-stage filtering |\n| 🌐 **CIDR Input** | Accept IP ranges like `185.51.200.0/24` — auto-expanded to individual hosts |\n\n---\n\n## 🏗️ How It Works\n\n```\n          Restricted Network                   |     Open Internet\n                                               |\n  📱 Client ──[UDP:53]──→ Resolver ──[UDP:53]──→ 🖥️ DNSTT Server\n  📱 Client ──[HTTPS:443]──→ DoH Resolver ────→ 🖥️ DNSTT Server\n                                               |\n           ↑ scanner tests this part ↑\n```\n\n### 🤔 Why DoH Matters\n\n| Transport | Port | Visibility | Restricted Networks |\n|-----------|------|------------|---------------------|\n| 🔴 UDP DNS | 53 | Fully visible to DPI | Monitored, often blocked |\n| 🔴 DoT | 853 | TLS on known port | Often blocked |\n| 🟢 **DoH** | **443** | **Looks like HTTPS** | **Hard to detect** |\n| 🔴 DoQ | 443/UDP | QUIC-based | Often disabled |\n\nThe 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.\n\n---\n\n## 📦 Install\n\n### From Source\n\n```bash\ngit clone https://github.com/SamNet-dev/findns.git\ncd findns\ngo build -o scanner ./cmd\n```\n\n### Go Install\n\n```bash\ngo install github.com/SamNet-dev/findns/cmd@latest\n```\n\n### Download Binary\n\nPre-built binaries for Linux, macOS, and Windows are available on the [Releases](https://github.com/SamNet-dev/findns/releases) page.\n\n```bash\n# Example: Linux x64\ncurl -LO https://github.com/SamNet-dev/findns/releases/latest/download/findns-linux-amd64\nchmod +x findns-linux-amd64\n./findns-linux-amd64 --help\n```\n\n### Requirements\n\n- **Go 1.24+** for building from source\n- **dnstt-client** — only for e2e tunnel tests (`--pubkey`). Install: `go install www.bamsoftware.com/git/dnstt.git/dnstt-client@latest`\n- **slipstream-client** — only for e2e Slipstream tests (`--cert`)\n- **curl** — for e2e connectivity verification\n\n\u003e **Important:** On Linux, you must place `dnstt-client` in PATH (e.g. `/usr/local/bin/`). Just putting it next to the scanner is not enough. Run: `sudo mv dnstt-client /usr/local/bin/ \u0026\u0026 sudo chmod +x /usr/local/bin/dnstt-client`\n\u003e\n\u003e Without `--pubkey`, the scanner still finds resolvers compatible with DNS tunneling — it tests ping, resolve, NXDOMAIN, EDNS, and tunnel delegation without needing dnstt-client.\n\n---\n\n## 🪟 Windows Guide\n\nWindows is fully supported. Two ways to get started:\n\n### Option 1: Download Binary (Easiest)\n\n1. Go to the [Releases](https://github.com/SamNet-dev/findns/releases) page\n2. Download `findns-windows-amd64.exe`\n3. Rename it to `findns.exe` (optional, for convenience)\n4. Open **cmd** or **PowerShell** in the same folder\n5. Run:\n\n```powershell\n.\\findns.exe --help\n```\n\n\u003e No Go installation needed — just download and run.\n\n### Option 2: Build from Source\n\nRequires **Go 1.24+** installed from [go.dev/dl](https://go.dev/dl/).\n\n```powershell\ngit clone https://github.com/SamNet-dev/findns.git\ncd findns\ngo build -o findns.exe ./cmd\n```\n\n### Run\n\nUse `.\\findns.exe` instead of `./scanner` in all commands:\n\n```powershell\n# Fetch resolvers\n.\\findns.exe fetch -o resolvers.txt\n\n# Full scan\n.\\findns.exe scan -i resolvers.txt -o results.json --domain t.example.com\n\n# With e2e test\n.\\findns.exe scan -i resolvers.txt -o results.json ^\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e\n```\n\n\u003e **Tip:** In PowerShell, use backtick `` ` `` for line continuation instead of `^`.\n\n### Prerequisites\n\n- **curl** — included by default in Windows 10/11\n- **dnstt-client.exe** — place next to `findns.exe` or in a folder in your `PATH` (only for e2e DNSTT tests)\n- **slipstream-client.exe** — same as above (only for e2e Slipstream tests)\n\n### Common Issues\n\n| Issue | Fix |\n|-------|-----|\n| `ping` shows 0% loss but scan fails | Run as **Administrator** — Windows ICMP requires elevated privileges |\n| `dnstt-client` not found | Place `dnstt-client.exe` next to `findns.exe` or add its folder to PATH |\n| PowerShell blocks execution | Use `cmd.exe` or run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |\n| Long commands break | Use backtick `` ` `` (PowerShell) or `^` (cmd) for line continuation |\n\n---\n\n## 🚀 Quick Start\n\n### 1️⃣ Get Resolver Lists\n\n```bash\n# 📥 Download global UDP resolvers\n./scanner fetch -o resolvers.txt\n\n# 🌍 Include regional intranet resolvers\n./scanner fetch -o resolvers.txt --local\n\n# 🔒 Download DoH resolver URLs\n./scanner fetch -o doh-resolvers.txt --doh\n```\n\n### 2️⃣ Run Full Scan\n\n```bash\n# 🔍 Scan UDP resolvers (all checks)\n./scanner scan -i resolvers.txt -o results.json --domain t.example.com\n\n# 🔍 Scan with e2e DNSTT verification\n./scanner scan -i resolvers.txt -o results.json \\\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e\n\n# 🔒 Scan DoH resolvers\n./scanner scan -i doh-resolvers.txt -o results.json \\\n  --domain t.example.com --doh\n\n# 🔒 DoH scan with e2e verification\n./scanner scan -i doh-resolvers.txt -o results.json \\\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e --doh\n```\n\n### 3️⃣ Check Results\n\nResults are saved as JSON. The `passed` array contains resolvers that survived all steps, sorted by performance:\n\n```json\n{\n  \"passed\": [\n    {\"ip\": \"1.1.1.1\", \"metrics\": {\"ping_ms\": 4.2, \"resolve_ms\": 15.3, \"edns_max\": 1232}},\n    {\"ip\": \"8.8.8.8\", \"metrics\": {\"ping_ms\": 12.7, \"resolve_ms\": 22.1, \"edns_max\": 1232}}\n  ]\n}\n```\n\n---\n\n## 📖 Commands\n\n### 🎯 `scan` — All-in-One Pipeline (Recommended)\n\nAutomatically chains the right scan steps based on your flags. This is the **recommended** way to use the scanner.\n\n```bash\n./scanner scan -i resolvers.txt -o results.json --domain t.example.com\n```\n\n**UDP mode pipeline:** `ping → resolve → nxdomain → edns → tunnel → e2e`\n**DoH mode pipeline:** `doh/resolve → doh/tunnel → doh/e2e`\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--domain` | Tunnel domain (enables tunnel/edns/e2e steps) | — |\n| `--pubkey` | DNSTT server public key (enables e2e test) | — |\n| `--cert` | Slipstream cert path (enables Slipstream e2e) | — |\n| `--test-url` | URL to fetch through tunnel for e2e test | `https://httpbin.org/ip` |\n| `--doh` | Scan DoH resolvers instead of UDP | `false` |\n| `--skip-ping` | Skip ICMP ping step | `false` |\n| `--skip-nxdomain` | Skip NXDOMAIN hijack check | `false` |\n| `--top` | Number of top results to display | `10` |\n\n---\n\n### 📥 `fetch` — Download Resolver Lists\n\nAutomatically downloads and deduplicates resolver lists from public sources.\n\n```bash\n# Global UDP resolvers (from trickest/resolvers)\n./scanner fetch -o resolvers.txt\n\n# Include regional intranet resolvers (7,800+ IPs)\n./scanner fetch -o resolvers.txt --local\n\n# DoH resolver URLs (19+ well-known + public lists)\n./scanner fetch -o doh-resolvers.txt --doh\n```\n\n**Built-in DoH endpoints** include:\n- 🔵 Google (`dns.google`)\n- 🟠 Cloudflare (`cloudflare-dns.com`)\n- 🟣 Quad9 (`dns.quad9.net`)\n- 🟢 AdGuard, Mullvad, NextDNS, LibreDNS, BlahDNS, and more\n\n---\n\n### 🏓 `ping` — ICMP Reachability\n\n```bash\n./scanner ping -i resolvers.txt -o result.json\n./scanner ping -i resolvers.txt -o result.json -c 5 -t 2\n```\n\n📊 **Metric:** `ping_ms` (average RTT)\n\n---\n\n### 🔎 `resolve` — DNS Resolution Test\n\n```bash\n./scanner resolve -i resolvers.txt -o result.json --domain google.com\n```\n\n📊 **Metric:** `resolve_ms` (average resolve time)\n\n---\n\n### 🔎 `resolve tunnel` — NS Delegation Check\n\nTests whether a resolver can see your tunnel's NS records and resolve the glue A record.\n\n```bash\n./scanner resolve tunnel -i resolvers.txt -o result.json --domain t.example.com\n```\n\n📊 **Metric:** `resolve_ms` (average NS + glue query time)\n\n---\n\n### 🛡️ `nxdomain` — DNS Hijack Detection\n\nTests whether resolvers return proper NXDOMAIN for non-existent domains. Hijacking resolvers return fake NOERROR answers — these are **not safe** for tunneling.\n\n```bash\n./scanner nxdomain -i resolvers.txt -o result.json\n```\n\n📊 **Metrics:** `nxdomain_ok` (count of correct responses), `hijack` (1.0 = hijacking detected)\n\n---\n\n### 📏 `edns` — EDNS Payload Size Test\n\nTests which EDNS buffer sizes a resolver supports. Larger payloads = faster DNS tunnel. Tests 512, 900, and 1232 bytes.\n\n```bash\n./scanner edns -i resolvers.txt -o result.json --domain t.example.com\n```\n\n📊 **Metric:** `edns_max` (largest working payload: 512, 900, or 1232)\n\n---\n\n### 🚇 `e2e dnstt` — End-to-End DNSTT Test (UDP)\n\nActually launches `dnstt-client`, creates a SOCKS tunnel, and verifies connectivity with `curl`.\n\n```bash\n./scanner e2e dnstt -i resolvers.txt -o result.json \\\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e\n```\n\n📊 **Metric:** `e2e_ms` (time from start to successful connection)\n\n---\n\n### 🚇 `e2e slipstream` — End-to-End Slipstream Test\n\n```bash\n./scanner e2e slipstream -i resolvers.txt -o result.json \\\n  --domain s.example.com --cert /path/to/cert.pem\n```\n\n📊 **Metric:** `e2e_ms`\n\n---\n\n### 🔒 `doh resolve` — DoH Resolver Test\n\nTest DNS resolution through DoH endpoints (HTTPS POST with `application/dns-message`).\n\n```bash\n./scanner doh resolve -i doh-resolvers.txt -o result.json --domain google.com\n```\n\n---\n\n### 🔒 `doh resolve tunnel` — DoH NS Delegation\n\n```bash\n./scanner doh resolve tunnel -i doh-resolvers.txt -o result.json --domain t.example.com\n```\n\n---\n\n### 🔒 `doh e2e` — End-to-End DNSTT via DoH\n\nLaunches `dnstt-client -doh \u003curl\u003e` and verifies tunnel connectivity.\n\n```bash\n./scanner doh e2e -i doh-resolvers.txt -o result.json \\\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e\n```\n\n---\n\n### ⛓️ `chain` — Custom Step Pipeline\n\nRun any combination of steps in sequence. Only resolvers that pass each step advance.\n\n```bash\n./scanner chain -i resolvers.txt -o result.json \\\n  --step \"ping\" \\\n  --step \"resolve:domain=google.com\" \\\n  --step \"nxdomain\" \\\n  --step \"edns:domain=t.example.com\" \\\n  --step \"resolve/tunnel:domain=t.example.com\" \\\n  --step \"e2e/dnstt:domain=t.example.com,pubkey=\u003ckey\u003e\"\n```\n\nDoH chain example:\n\n```bash\n./scanner chain -i doh-resolvers.txt -o result.json \\\n  --step \"doh/resolve:domain=google.com\" \\\n  --step \"doh/resolve/tunnel:domain=t.example.com\" \\\n  --step \"doh/e2e:domain=t.example.com,pubkey=\u003ckey\u003e\"\n```\n\n**All available steps:**\n\n| Step | Required Params | Metrics | Description |\n|------|----------------|---------|-------------|\n| `ping` | — | `ping_ms` | ICMP reachability |\n| `resolve` | `domain` | `resolve_ms` | DNS A record resolution |\n| `resolve/tunnel` | `domain` | `resolve_ms` | NS delegation + glue record |\n| `nxdomain` | — | `hijack`, `nxdomain_ok` | NXDOMAIN integrity check |\n| `edns` | `domain` | `edns_max` | EDNS payload size support |\n| `e2e/dnstt` | `domain`, `pubkey` | `e2e_ms` | Real DNSTT tunnel test |\n| `e2e/slipstream` | `domain` | `e2e_ms` | Real Slipstream tunnel test |\n| `doh/resolve` | `domain` | `resolve_ms` | DoH DNS resolution |\n| `doh/resolve/tunnel` | `domain` | `resolve_ms` | DoH NS delegation |\n| `doh/e2e` | `domain`, `pubkey` | `e2e_ms` | Real DNSTT tunnel via DoH |\n\nStep format: `type:key=val,key=val`. Optional params: `count`, `timeout`.\n\n---\n\n## ⚙️ Global Flags\n\n| Flag | Short | Description | Default |\n|------|-------|-------------|---------|\n| `--input` | `-i` | Input file (text or JSON) | required |\n| `--output` | `-o` | Output JSON file | required |\n| `--timeout` | `-t` | Timeout per attempt (seconds) | 3 |\n| `--count` | `-c` | Attempts per IP/URL | 3 |\n| `--workers` | | Concurrent workers | 50 |\n| `--include-failed` | | Also scan failed entries from JSON input | false |\n\n---\n\n## 📄 Input / Output Format\n\n### Input\n\nPlain text file with one entry per line. Supports IPs, CIDR ranges, and DoH URLs:\n\n```text\n# UDP resolvers (one IP per line)\n8.8.8.8\n1.1.1.1\n9.9.9.9\n\n# CIDR ranges (expanded automatically)\n185.51.200.0/24\n10.202.10.0/28\n\n# DoH resolvers (full URLs)\nhttps://dns.google/dns-query\nhttps://cloudflare-dns.com/dns-query\nhttps://dns.quad9.net/dns-query\n```\n\n**CIDR support:** Ranges like `1.2.3.0/24` are automatically expanded to individual host IPs (network and broadcast addresses are excluded). This is useful for scanning regional IP blocks (e.g. `iran-ipv4.cidrs` files). A warning is shown when expansion exceeds 100,000 IPs.\n\nCan also accept JSON output from a previous scan (only `passed` entries are used by default).\n\n### Output\n\nJSON with structured results:\n\n```json\n{\n  \"steps\": [\n    {\n      \"name\": \"ping\",\n      \"tested\": 10000,\n      \"passed\": 9200,\n      \"failed\": 800,\n      \"duration_secs\": 15.1\n    }\n  ],\n  \"passed\": [\n    {\n      \"ip\": \"1.1.1.1\",\n      \"metrics\": {\n        \"ping_ms\": 4.2,\n        \"resolve_ms\": 15.3,\n        \"edns_max\": 1232,\n        \"e2e_ms\": 3200.5\n      }\n    }\n  ],\n  \"failed\": [\n    {\"ip\": \"9.9.9.9\"}\n  ]\n}\n```\n\n---\n\n## 🔧 Example Workflows\n\n### Find working UDP resolvers for DNSTT\n\n```bash\n# 1. Get resolvers\n./scanner fetch -o resolvers.txt --local\n\n# 2. Full scan with e2e\n./scanner scan -i resolvers.txt -o results.json \\\n  --domain t.mysite.com --pubkey abc123...\n\n# 3. Use the best resolver in your DNSTT client\ndnstt-client -udp \u003cbest-ip\u003e:53 -pubkey-file server.pub t.mysite.com 127.0.0.1:1080\n```\n\n### Find working DoH resolvers for DNSTT\n\n```bash\n# 1. Get DoH endpoints\n./scanner fetch -o doh.txt --doh\n\n# 2. Scan with DoH e2e\n./scanner scan -i doh.txt -o results.json \\\n  --domain t.mysite.com --pubkey abc123... --doh\n\n# 3. Use the best DoH resolver\ndnstt-client -doh \u003cbest-url\u003e -pubkey-file server.pub t.mysite.com 127.0.0.1:1080\n```\n\n### Multi-stage filtering with chain\n\n```bash\n# Quick filter → deep test\n./scanner chain -i resolvers.txt -o results.json \\\n  --step \"ping:count=1\" \\\n  --step \"resolve:domain=google.com,count=1\" \\\n  --step \"nxdomain:count=2\" \\\n  --step \"edns:domain=t.mysite.com\" \\\n  --step \"e2e/dnstt:domain=t.mysite.com,pubkey=abc123,timeout=10\"\n```\n\n---\n\n## 🙏 Credits\n\nThis project was originally inspired by [net2share/dnst-scanner](https://github.com/net2share/dnst-scanner). We rebuilt and expanded it with DoH support, NXDOMAIN/EDNS checks, a full scan pipeline, TUI, cross-platform fixes, and CI releases.\n\n---\n\n## 🔗 Related Projects\n\n| Project | Description |\n|---------|-------------|\n| [dnstm](https://github.com/net2share/dnstm) | DNS Tunnel Manager (server) |\n| [dnstm-setup](https://github.com/SamNet-dev/dnstm-setup) | Interactive setup wizard for dnstm |\n| [ir-resolvers](https://github.com/net2share/ir-resolvers) | Regional intranet resolver list (7,800+ IPs) |\n| [dnstt](https://www.bamsoftware.com/software/dnstt/) | DNS tunnel with DoH/DoT support |\n| [slipstream-rust](https://github.com/Mygod/slipstream-rust) | QUIC-based DNS tunnel |\n\n---\n\n## 📖 Farsi Guide\n\nFor a complete guide in Farsi covering every command, flag, and scenario, see [GUIDE.md](GUIDE.md).\n\n---\n\n## 💖 Donate\n\nIf this project helps you, consider supporting development: [samnet.dev/donate](https://www.samnet.dev/donate/)\n\n---\n\n## 📜 License\n\nMIT\n\n---\n---\n\n\u003cdiv dir=\"rtl\"\u003e\n\n# 🔍 findns\n\n**اسکنر سریع و چندپروتکلی برای پیدا کردن DNS resolverهای سازگار با تانل DNS**\n\nاز هر دو پروتکل **UDP** و **DoH (DNS-over-HTTPS)** پشتیبانی می‌کند و تانل‌ها را به صورت واقعی (end-to-end) با [DNSTT](https://www.bamsoftware.com/software/dnstt/) و [Slipstream](https://github.com/Mygod/slipstream-rust) تست می‌کند.\n\n\u003e 🌐 ساخته شده برای **شبکه‌های محدود** — جایی که پیدا کردن یک resolver کارآمد یعنی تفاوت بین اتصال و انزوا.\n\n---\n\n## ✨ امکانات\n\n| امکان | توضیح |\n|-------|-------|\n| 🔄 **اسکن UDP + DoH** | تست هم DNS ساده (پورت 53) و هم DNS-over-HTTPS (پورت 443) |\n| 🔗 **پایپلاین کامل** | Ping → Resolve → NXDOMAIN → EDNS → Tunnel → E2E با یک دستور |\n| 🛡️ **تشخیص هایجک** | شناسایی resolverهایی که جواب جعلی برمی‌گردانند |\n| 📏 **تست EDNS** | پیدا کردن resolverهایی که payload بزرگ پشتیبانی می‌کنند (تانل سریع‌تر) |\n| 🚇 **تست واقعی تانل** | واقعاً کلاینت DNSTT/Slipstream را اجرا می‌کند و اتصال را تأیید می‌کند |\n| 📥 **دانلود لیست resolver** | دانلود خودکار از منابع عمومی |\n| 🌍 **resolverهای محلی** | لیست داخلی 7,800+ آی‌پی resolver منطقه‌ای |\n| ⚡ **همزمانی بالا** | 50 worker موازی — هزاران resolver در چند دقیقه اسکن می‌شود |\n| 📋 **خروجی JSON** | خروجی هر اسکن ورودی اسکن بعدی می‌شود |\n| 🌐 **ورودی CIDR** | رنج آی‌پی مثل `185.51.200.0/24` را می‌خواند و به صورت خودکار باز می‌کند |\n\n---\n\n## 🏗️ نحوه کار\n\n\u003c/div\u003e\n\n```\n          شبکه محدود                            |      اینترنت آزاد\n                                               |\n  📱 کلاینت ──[UDP:53]──→ Resolver ──[UDP:53]──→ 🖥️ سرور DNSTT\n  📱 کلاینت ──[HTTPS:443]──→ DoH Resolver ────→ 🖥️ سرور DNSTT\n                                               |\n              ↑ اسکنر این قسمت را تست می‌کند ↑\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### 🤔 چرا DoH مهم است؟\n\n| پروتکل | پورت | قابل شناسایی | وضعیت در شبکه‌های محدود |\n|---------|------|-------------|----------------|\n| 🔴 UDP DNS | 53 | کاملاً قابل مشاهده | تحت نظارت، اغلب مسدود |\n| 🔴 DoT | 853 | TLS روی پورت شناخته شده | از سال ۲۰۲۰ مسدود |\n| 🟢 **DoH** | **443** | **شبیه HTTPS معمولی** | **سخت برای شناسایی** |\n| 🔴 DoQ | 443/UDP | مبتنی بر QUIC | QUIC در تمام ISPها غیرفعال |\n\nسرور DNSTT **همیشه** روی پورت 53 گوش می‌دهد. اما **کلاینت** می‌تواند با resolver واسط از طریق پروتکل‌های مختلف ارتباط برقرار کند. DoH کوئری‌های DNS را داخل HTTPS معمولی قرار می‌دهد و برای فایروال‌ها تقریباً نامرئی است.\n\n---\n\n## 📦 نصب\n\n### از سورس\n\n\u003c/div\u003e\n\n```bash\ngit clone https://github.com/SamNet-dev/findns.git\ncd findns\ngo build -o scanner ./cmd\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### Go Install\n\n\u003c/div\u003e\n\n```bash\ngo install github.com/SamNet-dev/findns/cmd@latest\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### دانلود باینری\n\nباینری‌های آماده برای Linux، macOS و Windows در صفحه [Releases](https://github.com/SamNet-dev/findns/releases) موجود است.\n\n### پیش‌نیازها\n\n- **Go 1.24+** برای بیلد از سورس\n- **dnstt-client** — فقط برای تست e2e تانل (`--pubkey`). نصب: `go install www.bamsoftware.com/git/dnstt.git/dnstt-client@latest`\n- **slipstream-client** — فقط برای تست e2e Slipstream (`--cert`)\n- **curl** — برای تأیید اتصال e2e\n\n\u003e **مهم:** در لینوکس باید `dnstt-client` را در PATH قرار دهید (مثلاً `/usr/local/bin/`). فقط گذاشتن کنار اسکنر کافی نیست. اجرا کنید: `sudo mv dnstt-client /usr/local/bin/ \u0026\u0026 sudo chmod +x /usr/local/bin/dnstt-client`\n\u003e\n\u003e بدون `--pubkey` هم اسکنر resolverهای سازگار با تانل DNS را پیدا می‌کند (ping, resolve, nxdomain, edns, tunnel delegation بدون نیاز به dnstt-client).\n\n---\n\n## 🪟 راهنمای ویندوز\n\nویندوز به طور کامل پشتیبانی می‌شود. دو روش برای شروع:\n\n### روش ۱: دانلود باینری (ساده‌ترین)\n\n1. به صفحه [Releases](https://github.com/SamNet-dev/findns/releases) بروید\n2. فایل `findns-windows-amd64.exe` را دانلود کنید\n3. نام آن را به `findns.exe` تغییر دهید (اختیاری)\n4. **cmd** یا **PowerShell** را در همان پوشه باز کنید\n5. اجرا کنید:\n\n\u003c/div\u003e\n\n```powershell\n.\\findns.exe --help\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n\u003e نیازی به نصب Go نیست — فقط دانلود و اجرا کنید.\n\n### روش ۲: بیلد از سورس\n\nنیاز به **Go 1.24+** از [go.dev/dl](https://go.dev/dl/) دارد.\n\n\u003c/div\u003e\n\n```powershell\ngit clone https://github.com/SamNet-dev/findns.git\ncd findns\ngo build -o findns.exe ./cmd\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### اجرا\n\nدر تمام دستورات به جای `./scanner` از `.\\findns.exe` استفاده کنید:\n\n\u003c/div\u003e\n\n```powershell\n# دریافت لیست resolverها\n.\\findns.exe fetch -o resolvers.txt\n\n# اسکن کامل\n.\\findns.exe scan -i resolvers.txt -o results.json --domain t.example.com\n\n# با تست e2e\n.\\findns.exe scan -i resolvers.txt -o results.json ^\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n\u003e **نکته:** در PowerShell از بک‌تیک `` ` `` برای ادامه خط استفاده کنید (به جای `^`).\n\n### پیش‌نیازها\n\n- **curl** — در ویندوز 10/11 به صورت پیش‌فرض نصب است\n- **dnstt-client.exe** — کنار `findns.exe` قرار دهید یا در PATH اضافه کنید (فقط برای تست e2e DNSTT)\n- **slipstream-client.exe** — مثل بالا (فقط برای تست e2e Slipstream)\n\n### مشکلات رایج\n\n| مشکل | راه حل |\n|------|--------|\n| `ping` نشان می‌دهد 0% loss ولی اسکن فیل می‌شود | به عنوان **Administrator** اجرا کنید — ICMP در ویندوز نیاز به دسترسی بالا دارد |\n| `dnstt-client` پیدا نمی‌شود | فایل `dnstt-client.exe` را کنار `findns.exe` قرار دهید یا پوشه‌اش را به PATH اضافه کنید |\n| PowerShell اجرا را بلاک می‌کند | از `cmd.exe` استفاده کنید یا `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` را اجرا کنید |\n| دستورات طولانی خطا می‌دهند | از بک‌تیک `` ` `` (PowerShell) یا `^` (cmd) برای ادامه خط استفاده کنید |\n\n---\n\n## 🚀 شروع سریع\n\n### 1️⃣ دریافت لیست Resolverها\n\n\u003c/div\u003e\n\n```bash\n# 📥 دانلود resolverهای UDP جهانی\n./scanner fetch -o resolvers.txt\n\n# 🌍 شامل resolverهای محلی\n./scanner fetch -o resolvers.txt --local\n\n# 🔒 دانلود آدرس‌های DoH\n./scanner fetch -o doh-resolvers.txt --doh\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### 2️⃣ اجرای اسکن کامل\n\n\u003c/div\u003e\n\n```bash\n# 🔍 اسکن resolverهای UDP (تمام بررسی‌ها)\n./scanner scan -i resolvers.txt -o results.json --domain t.example.com\n\n# 🔍 اسکن با تست واقعی تانل DNSTT\n./scanner scan -i resolvers.txt -o results.json \\\n  --domain t.example.com --pubkey \u003chex-pubkey\u003e\n\n# 🔒 اسکن resolverهای DoH\n./scanner scan -i doh-resolvers.txt -o results.json \\\n  --domain t.example.com --doh\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### 3️⃣ بررسی نتایج\n\nنتایج به صورت JSON ذخیره می‌شوند. آرایه `passed` شامل resolverهایی است که تمام مراحل را با موفقیت گذرانده‌اند:\n\n\u003c/div\u003e\n\n```json\n{\n  \"passed\": [\n    {\"ip\": \"1.1.1.1\", \"metrics\": {\"ping_ms\": 4.2, \"resolve_ms\": 15.3, \"edns_max\": 1232}}\n  ]\n}\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n---\n\n## 📖 دستورات\n\n### 🎯 `scan` — پایپلاین یکپارچه (پیشنهادی)\n\nبه صورت خودکار مراحل مناسب را بر اساس فلگ‌ها ترتیب می‌دهد.\n\n**حالت UDP:** `ping → resolve → nxdomain → edns → tunnel → e2e`\n**حالت DoH:** `doh/resolve → doh/tunnel → doh/e2e`\n\n| فلگ | توضیح |\n|-----|-------|\n| `--domain` | دامنه تانل (فعال‌سازی تست تانل/edns/e2e) |\n| `--pubkey` | کلید عمومی سرور DNSTT (فعال‌سازی تست e2e) |\n| `--cert` | مسیر گواهی Slipstream (فعال‌سازی تست Slipstream) |\n| `--doh` | اسکن DoH به جای UDP |\n| `--skip-ping` | رد کردن مرحله ping |\n| `--skip-nxdomain` | رد کردن بررسی هایجک |\n| `--top` | تعداد نتایج برتر برای نمایش (پیش‌فرض: 10) |\n\n---\n\n### 📥 `fetch` — دانلود لیست Resolverها\n\n\u003c/div\u003e\n\n```bash\n./scanner fetch -o resolvers.txt           # resolverهای UDP جهانی\n./scanner fetch -o resolvers.txt --local    # + resolverهای محلی\n./scanner fetch -o doh-resolvers.txt --doh # آدرس‌های DoH\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n---\n\n### دستورات جداگانه\n\n| دستور | توضیح | متریک |\n|-------|-------|-------|\n| 🏓 `ping` | بررسی دسترسی‌پذیری ICMP | `ping_ms` |\n| 🔎 `resolve` | تست resolve رکورد A | `resolve_ms` |\n| 🔎 `resolve tunnel` | بررسی NS delegation + رکورد glue | `resolve_ms` |\n| 🛡️ `nxdomain` | تشخیص هایجک DNS | `hijack`, `nxdomain_ok` |\n| 📏 `edns` | تست سایز payload EDNS (512/900/1232) | `edns_max` |\n| 🚇 `e2e dnstt` | تست واقعی تانل DNSTT (UDP) | `e2e_ms` |\n| 🚇 `e2e slipstream` | تست واقعی تانل Slipstream | `e2e_ms` |\n| 🔒 `doh resolve` | تست resolve از طریق DoH | `resolve_ms` |\n| 🔒 `doh resolve tunnel` | بررسی NS از طریق DoH | `resolve_ms` |\n| 🔒 `doh e2e` | تست واقعی تانل DNSTT از طریق DoH | `e2e_ms` |\n\n---\n\n### ⛓️ `chain` — پایپلاین سفارشی\n\nهر ترکیبی از مراحل را اجرا کنید. فقط resolverهایی که هر مرحله را پاس کنند به مرحله بعد می‌روند.\n\n\u003c/div\u003e\n\n```bash\n./scanner chain -i resolvers.txt -o result.json \\\n  --step \"ping\" \\\n  --step \"resolve:domain=google.com\" \\\n  --step \"nxdomain\" \\\n  --step \"edns:domain=t.example.com\" \\\n  --step \"resolve/tunnel:domain=t.example.com\" \\\n  --step \"e2e/dnstt:domain=t.example.com,pubkey=\u003ckey\u003e\"\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n---\n\n## ⚙️ فلگ‌های عمومی\n\n| فلگ | مخفف | توضیح | پیش‌فرض |\n|-----|------|-------|---------|\n| `--input` | `-i` | فایل ورودی (متن یا JSON) | الزامی |\n| `--output` | `-o` | فایل خروجی JSON | الزامی |\n| `--timeout` | `-t` | تایم‌اوت هر تلاش (ثانیه) | 3 |\n| `--count` | `-c` | تعداد تلاش برای هر IP/URL | 3 |\n| `--workers` | | تعداد workerهای موازی | 50 |\n| `--include-failed` | | اسکن IPهای فیل‌شده از ورودی JSON | false |\n\n---\n\n## 🔧 مثال‌های کاربردی\n\n### پیدا کردن resolver UDP کارآمد برای DNSTT\n\n\u003c/div\u003e\n\n```bash\n# ۱. دریافت لیست\n./scanner fetch -o resolvers.txt --local\n\n# ۲. اسکن کامل با تست e2e\n./scanner scan -i resolvers.txt -o results.json \\\n  --domain t.mysite.com --pubkey abc123...\n\n# ۳. استفاده از بهترین resolver\ndnstt-client -udp \u003cbest-ip\u003e:53 -pubkey-file server.pub t.mysite.com 127.0.0.1:1080\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n### پیدا کردن resolver DoH کارآمد برای DNSTT\n\n\u003c/div\u003e\n\n```bash\n# ۱. دریافت لیست DoH\n./scanner fetch -o doh.txt --doh\n\n# ۲. اسکن DoH با تست e2e\n./scanner scan -i doh.txt -o results.json \\\n  --domain t.mysite.com --pubkey abc123... --doh\n\n# ۳. استفاده از بهترین resolver\ndnstt-client -doh \u003cbest-url\u003e -pubkey-file server.pub t.mysite.com 127.0.0.1:1080\n```\n\n\u003cdiv dir=\"rtl\"\u003e\n\n---\n\n## 🙏 تقدیر\n\nاین پروژه با الهام از [net2share/dnst-scanner](https://github.com/net2share/dnst-scanner) ساخته شده و با پشتیبانی DoH، بررسی NXDOMAIN/EDNS، پایپلاین اسکن، رابط کاربری ترمینال، رفع مشکلات چندسکویی و CI بازسازی و گسترش یافته است.\n\n---\n\n## 🔗 پروژه‌های مرتبط\n\n| پروژه | توضیح |\n|-------|-------|\n| [dnstm](https://github.com/net2share/dnstm) | مدیریت تانل DNS (سرور) |\n| [dnstm-setup](https://github.com/SamNet-dev/dnstm-setup) | ویزارد نصب تعاملی dnstm |\n| [ir-resolvers](https://github.com/net2share/ir-resolvers) | لیست resolverهای محلی (7,800+ IP) |\n| [dnstt](https://www.bamsoftware.com/software/dnstt/) | تانل DNS با پشتیبانی DoH/DoT |\n| [slipstream-rust](https://github.com/Mygod/slipstream-rust) | تانل DNS مبتنی بر QUIC |\n\n---\n\n## 📖 راهنمای کامل فارسی\n\nبرای راهنمای جامع فارسی شامل تمام دستورات، فلگ‌ها و سناریوها، فایل [GUIDE.md](GUIDE.md) را ببینید.\n\n---\n\n## 💖 حمایت مالی\n\nاگر این پروژه به شما کمک کرد، از توسعه آن حمایت کنید: [samnet.dev/donate](https://www.samnet.dev/donate/)\n\n---\n\n## 📜 لایسنس\n\nMIT\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamnet-dev%2Ffindns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamnet-dev%2Ffindns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamnet-dev%2Ffindns/lists"}