Skip to content

docs: add features section and fix Persian RTL #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nightowlnerd merged 1 commit into from
Jan 30, 2026
Merged

docs: add features section and fix Persian RTL #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 19 additions & 90 deletions README.fa.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
<div dir="rtl">

# dnscan

[![CI](https://github.com/nightowlnerd/dnscan/actions/workflows/ci.yml/badge.svg)](https://github.com/nightowlnerd/dnscan/actions/workflows/ci.yml)
Expand All @@ -10,6 +8,13 @@

پیدا کردن سرورهای DNS فعال برای تونل‌های DNS در زمان قطعی اینترنت. این ابزار رنج‌های IP کشورهای مختلف را اسکن می‌کند تا resolverهای بازگشتی که می‌توانند به سرور تونل شما برسند را پیدا کند.

## ویژگی‌ها

- 🧪 **تست Burst** - سرورهایی که فقط به یک کوئری جواب می‌دهند اما زیر بار واقعی fail می‌شوند را فیلتر می‌کند (مثل 1.1.1.1 که 0% موفقیت دارد)
- 🛡️ **تشخیص DNS Hijacking** - سرورهایی که IP خصوصی برمی‌گردانند را شناسایی و هشدار می‌دهد
- ⚡ **مرتب‌سازی بر اساس QPS** - نتایج بر اساس سرعت (queries per second) مرتب می‌شوند
- 🎨 **رنگ‌بندی** - سبز برای ≥85% موفقیت، زرد برای 70-84%

## کاربرد

در زمان محدودیت‌های اینترنتی، تونل‌های DNS (مثل [slipstream](https://github.com/Mygod/slipstream-rust)) می‌توانند با کدگذاری ترافیک در کوئری‌های DNS، محدودیت‌ها را دور بزنند. این ابزار سرورهای DNS را پیدا می‌کند که:
Expand All @@ -19,10 +24,6 @@

## شروع سریع

</div>

<div dir="ltr">

```bash
# دانلود و استخراج (Linux amd64)
curl -LO https://github.com/nightowlnerd/dnscan/releases/latest/download/dnscan-linux-amd64.tar.gz
Expand All @@ -32,20 +33,12 @@ tar xzf dnscan-linux-amd64.tar.gz
./dnscan --country ir --domain t.example.com --mode list
```

</div>

![dnscan screenshot](screenshot.jpg)

<div dir="rtl">

**نکته:** فایل tarball شامل باینری `dnscan` و پوشه `data/` است. رنج‌های IP برای کشورهای جدید به صورت خودکار دانلود می‌شوند.

## ساخت از سورس

</div>

<div dir="ltr">

```bash
# Linux
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o dnscan-linux-amd64 .
Expand All @@ -54,10 +47,6 @@ CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o dnscan-linux-
go build -o dnscan .
```

</div>

<div dir="rtl">

## پرچم‌ها

| پرچم | پیش‌فرض | توضیحات |
Expand All @@ -84,10 +73,6 @@ go build -o dnscan .

## مثال‌ها

</div>

<div dir="ltr">

```bash
# تست سریع - فقط DNSهای شناخته‌شده
./dnscan --country ir --domain t.example.com --mode list
Expand All @@ -108,26 +93,28 @@ go build -o dnscan .
./dnscan --country cn --domain t.example.com --mode fast
```

</div>
## تست Burst

<div dir="rtl">
وقتی `--domain` مشخص شود، dnscan هر سرور کاندید را با 20 کوئری همزمان تست می‌کند. این کار سرورهایی مثل 1.1.1.1 را که به یک کوئری جواب می‌دهند اما زیر بار واقعی slipstream fail می‌شوند، فیلتر می‌کند.

## پرچم --verify
نتایج بر اساس QPS (queries per second) مرتب می‌شوند - سریع‌ترین سرورها اول نشان داده می‌شوند.

به صورت پیش‌فرض، اسکنر فقط چک می‌کند که آیا سرور DNS پاسخ می‌دهد. با `--verify`، هر کاندیدا را با slipstream-client واقعی تست می‌کند تا کارکرد تونل را تأیید کند:
## تشخیص DNS Hijacking

</div>
اگر ISP شما DNS را hijack کرده باشد (کوئری‌ها به IP خصوصی مثل 10.x.x.x برمی‌گردند)، dnscan این سرورها را رد کرده و هشدار می‌دهد:

<div dir="ltr">
```
Warning: 5 servers returned private IPs (possible DNS hijacking)
```

## پرچم --verify

به صورت پیش‌فرض، اسکنر فقط چک می‌کند که آیا سرور DNS پاسخ می‌دهد. با `--verify`، هر کاندیدا را با slipstream-client واقعی تست می‌کند تا کارکرد تونل را تأیید کند:

```bash
./dnscan --domain t.example.com --mode list --verify ./slipstream-client
```

</div>

<div dir="rtl">

دریافت slipstream-client از: https://github.com/AliRezaBeigy/slipstream-rust-deploy/releases

خروجی زمان اتصال هر سرور را نشان می‌دهد:
Expand All @@ -139,10 +126,6 @@ go build -o dnscan .

## فایل‌های داده

</div>

<div dir="ltr">

```
data/
ranges/
Expand All @@ -151,55 +134,31 @@ data/
ir.txt # سرورهای DNS شناخته‌شده
```

</div>

<div dir="rtl">

### دانلود خودکار رنج‌های IP

رنج‌های IP به صورت خودکار از [ipdeny.com](https://www.ipdeny.com/ipblocks/) دانلود می‌شوند وقتی کشور جدیدی استفاده کنید:

</div>

<div dir="ltr">

```bash
# اولین اجرا de.zone را دانلود می‌کند
./dnscan --country de --domain t.example.com --mode fast
```

</div>

<div dir="rtl">

### اضافه کردن DNS

فایل `data/dns/<country>.txt` را ویرایش کنید (برای `--mode list` استفاده می‌شود):

</div>

<div dir="ltr">

```
# data/dns/ir.txt
185.8.174.140
130.185.77.69
```

</div>

<div dir="rtl">

## راه‌اندازی سرور

قبل از اسکن، سرور تونل شما باید در حال اجرا باشد. اسکنر کوئری‌های DNS به دامنه شما می‌فرستد - اگر سرور در حال اجرا نباشد، همه سرورهای DNS ناموفق به نظر می‌رسند.

برای slipstream:

</div>

<div dir="ltr">

```bash
# روی سرور شما
docker run -d --network host bashsiz/slipstream-rust slipstream-server \
Expand All @@ -208,49 +167,25 @@ docker run -d --network host bashsiz/slipstream-rust slipstream-server \
--target-address 127.0.0.1:22
```

</div>

<div dir="rtl">

برای تست بدون تونل (فقط چک کردن دسترسی DNS):

</div>

<div dir="ltr">

```bash
# DNS responder ساده
dnsmasq --no-daemon --log-queries --address=/t.example.com/1.2.3.4
```

</div>

<div dir="rtl">

## خروجی

سرورهای DNS فعال در stdout چاپ می‌شوند (هر خط یکی):

</div>

<div dir="ltr">

```
185.8.174.140
130.185.77.69
217.218.127.127
```

</div>

<div dir="rtl">

استفاده با slipstream:

</div>

<div dir="ltr">

```bash
./slipstream-client \
--resolver 185.8.174.140:53 \
Expand All @@ -259,10 +194,6 @@ dnsmasq --no-daemon --log-queries --address=/t.example.com/1.2.3.4
--tcp-listen-port 7000
```

</div>

<div dir="rtl">

## عیب‌یابی

**هیچ سرور DNS پیدا نشد:**
Expand All @@ -278,5 +209,3 @@ dnsmasq --no-daemon --log-queries --address=/t.example.com/1.2.3.4
**"Failed to download ranges":**
- اتصال اینترنت را چک کنید
- کد کشور ممکن است در ipdeny.com وجود نداشته باشد

</div>
21 changes: 21 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,13 @@

Find working DNS servers for DNS tunnels during internet blackouts. Scans country-specific IP ranges to find recursive resolvers that can reach your tunnel server.

## Features

- 🧪 **Burst Testing** - Filters servers that respond to single queries but fail under real load (e.g., 1.1.1.1 shows 0% success)
- 🛡️ **DNS Hijacking Detection** - Detects and warns when servers return private IPs
- ⚡ **QPS Sorting** - Results sorted by throughput (queries per second)
- 🎨 **Color Coding** - Green for ≥85% success, yellow for 70-84%

## Use Case

During internet restrictions, DNS tunnels (like [slipstream](https://github.com/Mygod/slipstream-rust)) can bypass blocks by encoding traffic in DNS queries. This tool finds DNS servers that:
Expand Down Expand Up @@ -87,6 +94,20 @@ go build -o dnscan .
./dnscan --country cn --domain t.example.com --mode fast
```

## Burst Testing

When `--domain` is specified, dnscan tests each candidate with 20 concurrent queries. This filters out servers like 1.1.1.1 that respond to single queries but fail under real slipstream load.

Results are sorted by QPS (queries per second) - fastest servers listed first.

## DNS Hijacking Detection

If your ISP hijacks DNS (queries return private IPs like 10.x.x.x), dnscan rejects those servers and warns you:

```
Warning: 5 servers returned private IPs (possible DNS hijacking)
```

## The --verify Flag

By default, the scanner only checks if a DNS server responds. With `--verify`, it tests each candidate with the actual slipstream-client to confirm the tunnel works:
Expand Down