# SenPai Scanner

> **English:** [README.md](README.md)

[![CI](https://github.com/matinsenpai/senpaiscanner/actions/workflows/ci.yml/badge.svg)](https://github.com/matinsenpai/senpaiscanner/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/matinsenpai/senpaiscanner?style=flat-square)](https://github.com/matinsenpai/senpaiscanner/releases/latest)
[![Go Version](https://img.shields.io/github/go-mod/go-version/matinsenpai/senpaiscanner?style=flat-square)](go.mod)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
[![Platforms](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows%20%7C%20android%20%7C%20termux-informational?style=flat-square)](#نصب)

---

<img width="825" height="589" alt="image" src="https://github.com/user-attachments/assets/6558f7b1-bd9d-460a-adf2-d314fe70c48a" />

اگر روی شبکه‌ای هستید که تأخیر بالاست، اتصال بی‌خبر قطع می‌شود و پیدا کردن یک IP کارآمد Cloudflare تبدیل به کار روزانه شده — SenPai Scanner برای همین ساخته شده.

این ابزار IPهای لبه Cloudflare را پروب می‌کند، بهترین‌ها را با xray داخلی و کانفیگ VLESS یا Trojan خودتان تست می‌کند، و نتیجه را آماده‌ی paste کردن تحویل می‌دهد. بدون حفظ کردن فلگ‌های عجیب، بدون تنظیمات پیچیده — فقط ابزار را اجرا کنید و بگذارید کارش را بکند.

---

## چطور کار می‌کند

`senpaiscanner` را اجرا کنید تا وارد یک منوی ساده شوید. با کلیدهای جهت‌نما و Enter جابه‌جا می‌شوید — هیچ فلگ CLI برای اسکن وجود ندارد.

```
┌────────────────────────────────────────────────────────────┐
│  ▶  Find Working IPs   scan Cloudflare IPs — config optional │
│     Retry Last Scan    retry last scan with previous config  │
│     About                                                    │
│     Quit                                                     │
└────────────────────────────────────────────────────────────┘
```

**Find Working IPs** در یک یا دو فاز کار می‌کند:

**فاز ۱ — اسکن اتصال:** کاندیداهای Cloudflare را پروب می‌کند. اگر کانفیگ URL ندهید، از HTTP استاندارد استفاده می‌شود؛ اگر بدهید، SNI، host، مسیر WebSocket و پورت از لینک شما گرفته می‌شود. در حالت **Random**، هر IP سالم به‌طور خودکار **اسکن همسایه** را فعال می‌کند — آدرس‌های نزدیک در همان بلوک Cloudflare هم بررسی می‌شوند.

**فاز ۲ — اعتبارسنجی xray** *(اختیاری):* یک نمونه xray داخلی راه‌اندازی می‌کند و بهترین نتایج فاز ۱ را با کانفیگ واقعی VLESS یا Trojan شما end-to-end تست می‌کند. خروجی شامل endpoint، نوع transport، سرعت دانلود، تأخیر (TTFB) و وضعیت pass/fail است.

بعد از اتمام، **`c`** را بزنید تا endpointهای سالم در کلیپ‌بورد کپی و در فایل `ips.txt` ذخیره شوند.

تنظیمات آخرین اسکن به‌صورت خودکار ذخیره می‌شود. **Retry Last Scan** همان اسکن را بدون وارد کردن مجدد تنظیمات تکرار می‌کند.

---

## نصب

### دسکتاپ — باینری آماده

از [صفحه Releases](https://github.com/matinsenpai/senpaiscanner/releases/latest) دانلود کنید:

| پلتفرم | معماری | فایل |
|---|---|---|
| Linux | x86_64 | `senpaiscanner-linux-amd64` |
| Linux | ARM64 | `senpaiscanner-linux-arm64` |
| Linux | 32-bit x86 | `senpaiscanner-linux-386` |
| macOS | Intel | `senpaiscanner-darwin-amd64` |
| macOS | Apple Silicon | `senpaiscanner-darwin-arm64` |
| Windows | x86_64 | `senpaiscanner-windows-amd64.exe` |
| Windows | 32-bit x86 | `senpaiscanner-windows-386.exe` |

**Linux / macOS — نصب با یک دستور:**

```bash
# نسخه پایدار
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash

# پیش‌انتشار
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash -s -- --prerelease
```

**Windows (PowerShell):**

```powershell
$r = Invoke-RestMethod https://api.github.com/repos/matinsenpai/senpaiscanner/releases/latest
$url = ($r.assets | Where-Object name -eq "senpaiscanner-windows-amd64.exe").browser_download_url
Invoke-WebRequest $url -OutFile senpaiscanner.exe
```

### اندروید — APK آماده

APKهای امضاشده به هر Release ضمیمه می‌شوند:

| فایل | توضیح |
|---|---|
| `SenPaiScanner-{version}-universal-release.apk` | همه ABIها — پیشنهادی |
| `SenPaiScanner-{version}-arm64-v8a-release.apk` | فقط ARM 64-bit |
| `SenPaiScanner-{version}-armeabi-v7a-release.apk` | فقط ARM 32-bit |

APK را نصب کنید، «نصب از منابع ناشناس» را در صورت نیاز فعال کنید، دسترسی شبکه بدهید و روی **START SCAN** بزنید.

### Termux

اگر می‌خواهید همان TUI کامل دسکتاپ را روی اندروید داشته باشید — از جمله اعتبارسنجی xray، فایل نتایج زنده و اسکن همسایه — Termux گزینه مناسبی است.

**۱. نصب Termux** از [F-Droid](https://f-droid.org/en/packages/com.termux/) (نسخه Play Store توصیه نمی‌شود):

```bash
pkg update && pkg upgrade -y
pkg install curl tar -y
```

**۲. نصب SenPai Scanner:**

```bash
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash
```

اسکریپت Termux را تشخیص می‌دهد و در `$PREFIX/bin` نصب می‌کند. روی گوشی ۶۴-bit، فایل `senpaiscanner-linux-arm64` دانلود می‌شود.

**۳. اجرا:**

```bash
senpaiscanner
```

**چند نکته برای Termux:**

| موضوع | توضیح |
|---|---|
| **ناوبری** | کلیدهای جهت‌دار یا کیبورد بلوتوث؛ در منوها `k` / `j` / `h` / `l` هم کار می‌کند |
| **Paste کردن URL** | لانگ‌پرس در Termux ← Paste |
| **کلید `c` (کلیپ‌بورد)** | ممکن است در همه setupها کار نکند؛ نتایج همیشه در `ips.txt` هستند |
| **فایل‌های نتایج** | قبل از اجرا `cd ~` کنید تا همه فایل‌ها در یک‌جا بمانند |
| **اسکن طولانی** | `termux-wake-lock` نصب کنید تا صفحه وسط اسکن خاموش نشود |
| **به‌روزرسانی** | همان one-liner را دوباره اجرا کنید؛ در صورت وجود نسخه جدید آپدیت می‌شود |

**نصب دستی (بدون اسکریپت):**

```bash
curl -fsSL -o "$PREFIX/bin/senpaiscanner" \
  https://github.com/matinsenpai/senpaiscanner/releases/latest/download/senpaiscanner-linux-arm64
chmod +x "$PREFIX/bin/senpaiscanner"
senpaiscanner
```

### از سورس

```bash
go install github.com/matinsenpai/senpaiscanner/cmd/senpaiscanner@latest
```

---

## راهنمای استفاده

```bash
senpaiscanner              # باز کردن TUI
senpaiscanner --version    # نمایش نسخه
senpaiscanner -v           # همان
senpaiscanner version      # همان
```

بقیه کارها داخل TUI یا اپ اندروید است.

### کلیدهای ناوبری (TUI)

| کلید | عملکرد |
|---|---|
| `↑` / `↓` یا `k` / `j` | جابه‌جایی بین ردیف‌ها |
| `←` / `→` یا `h` / `l` | جابه‌جایی بین گزینه‌های یک ردیف |
| `Enter` | انتخاب / تأیید / شروع اسکن |
| `Esc` | برگشت |
| `q` | خروج از منو؛ حین اسکن: لغو یا بازگشت بعد از اتمام |

در ردیف **Config URL** کلیدهای `←` / `→` مکان‌نما را جابه‌جا می‌کنند؛ `Ctrl+A` / `Ctrl+E` به ابتدا و انتها می‌روند.

---

## تنظیمات اسکن (Find Working IPs)

### مرحله ۱ — پارامترهای اصلی

| ردیف | گزینه‌ها | توضیح |
|---|---|---|
| **Source** | Random / From File | محدوده تصادفی IPv4 Cloudflare، یا لیست از `ips.txt` |
| **Count** | 1,000 / 5,000 / 20,000 / Custom | تعداد IP در فاز ۱ |
| **Workers** | 50 / 100 / 200 / Custom | پروبرهای موازی — پیش‌فرض ۵۰ مناسب شبکه‌های ضعیف‌تر است |
| **Timeout** | 2s / 3s / 5s / Custom | مهلت هر پروب |
| **Ports** | Config, 443, 8443, 2053, 2083, 2087, 2096 | چندانتخابی؛ هر IP روی تمام پورت‌های انتخاب‌شده تست می‌شود |

روی **Ports** Enter بزنید تا به مرحله بعد بروید. برای toggle هر پورت، روی آن فوکوس کنید و `Space` یا `Enter` بزنید.

### مرحله ۲ — کانفیگ اختیاری

| ردیف | گزینه‌ها | توضیح |
|---|---|---|
| **Config** | paste URL یا خالی | خالی = فقط فاز ۱؛ با URL = فاز ۱ + فاز ۲ |
| **Top N** | 10 / 25 / 50 / 100 / All / Custom | تعداد نتایج فاز ۱ که در فاز ۲ اعتبارسنجی می‌شوند |

لینک‌های پشتیبانی‌شده: **`vless://`** و **`trojan://`**. پارسر لینک‌های واقعی را هم می‌پذیرد.

### تنظیمات پایدار

هر بار که اسکن را شروع می‌کنید، تنظیمات در این مسیرها ذخیره می‌شوند:

| پلتفرم | مسیر |
|---|---|
| Windows | `%AppData%\senpaiscanner\config.json` |
| macOS | `~/Library/Application Support/senpaiscanner/config.json` |
| Linux / Termux | `~/.config/senpaiscanner/config.json` |

**Retry Last Scan** در صفحه اصلی همین مقادیر را بارگذاری و فوراً اسکن را شروع می‌کند.

---

## فایل نتایج زنده

حین اسکن، یک فایل با نام `SenPaiScannerResult-YYYYMMDD-HHMMSS.txt` کنار باینری ساخته می‌شود. این فایل:

- تا رسیدن اولین نتیجه سالم ساخته نمی‌شود (فایل خالی placeholder نمی‌سازد)
- با هر به‌روزرسانی بازنویسی می‌شود — می‌توانید آن را در ادیتور tail کنید
- شامل طرح اسکن، جدول فاز ۱، و جدول فاز ۲ (در صورت وجود) است

---

## جزئیات فاز ۱ و ۲

### فاز ۱ — پیدا کردن IPهای در دسترس

| حالت | رفتار |
|---|---|
| بدون URL کانفیگ | پروب HTTP استاندارد (`speed.cloudflare.com`، نمونه ۶۴ KiB) |
| با URL کانفیگ | SNI / host / path از لینک؛ برای `type=ws` ارتقای WebSocket انجام می‌شود |

در حالت Random، با پیدا شدن هر IP سالم، آدرس‌های نزدیک در همان بلوک هم به‌صورت خودکار پروب می‌شوند (تا شعاع ۳۲، حداکثر ۱۲ همسایه به ازای هر hit).

جدول زنده ۲۰ نتیجه برتر را نشان می‌دهد: **ENDPOINT**، **LOSS**، **AVG(ms)**، **COLO**، **STATUS**.

### فاز ۲ — اعتبارسنجی xray

بهترین کاندیداهای فاز ۱ با xray داخلی تست می‌شوند:

| ستون | معنی |
|---|---|
| ENDPOINT | `IP:port` اعتبارسنجی‌شده |
| TYPE | نوع transport (ws, grpc, xhttp, …) |
| SPEED | throughput دانلود بر حسب Mbps، یا `n/a` |
| LATENCY | زمان تا اولین بایت (TTFB) |
| STATUS | ✓ موفق / ✗ ناموفق |

اتصال با `/cdn-cgi/trace` بررسی می‌شود. endpoint می‌تواند با SPEED مقدار `n/a` هم ✓ باشد. هر کاندید یک retry خودکار روی شکست دارد.

بعد از فاز ۲، **`c`** را بزنید تا endpointهای سالم (مثل `104.16.72.162:443`) در کلیپ‌بورد کپی و در `ips.txt` ذخیره شوند.

---

## فرمت `ips.txt` (From File)

فایل را کنار executable یا در پوشه کاری فعلی قرار دهید:

| نوع خط | مثال | رفتار |
|---|---|---|
| IPv4 ساده | `104.16.72.162` | بارگذاری |
| CSV | `104.16.72.162,note` | ستون اول خوانده می‌شود |
| کامنت / خالی | `# my list` | نادیده گرفته می‌شود |
| CIDR کوچک (≤۲۵۶ host) | `104.16.72.160/29` | expand کامل |
| CIDR بزرگ | `104.16.0.0/16` | نمونه تصادفی تا ۲۵۶ IP |
| CIDR نامعتبر | `not-a-cidr/99` | خطا و توقف اسکن |

خطوط IPv6 نادیده گرفته می‌شوند.

**یک workflow مفید:** اسکن Random بزنید ← با `c` نتایج را در `ips.txt` ذخیره کنید ← همان لیست را با **From File** روی پورت‌های بیشتر تست کنید.

---

## اپ اندروید

موتور پروب و منطق xray از طریق پل Go mobile (`gomobile bind`) روی اندروید اجرا می‌شود.

### بخش‌های اصلی UI

| بخش | امکانات |
|---|---|
| **Home** | کارت آمار (Tested، In-Flight، Healthy، Failed)؛ لیست IP؛ کپی تکی و گروهی |
| **Settings** | Source، Count، Workers، Timeout، Ports، Config URL، Top N |
| **FAB** | START SCAN / STOP SCAN |
| **Info** | معرفی، نسخه، لینک GitHub و تلگرام |

### تفاوت‌های اندروید با دسکتاپ

| قابلیت | TUI دسکتاپ | اندروید |
|---|---|---|
| تنظیمات پایدار + Retry Last Scan | ✓ | — (فقط در همان session) |
| فایل نتایج زنده | ✓ | — |
| فقط فاز ۱ (بدون URL) | ✓ | ✓ |
| اسکن همسایه (Random) | ✓ | ✓ |
| CIDR در `ips.txt` | ✓ | فقط IP ساده |
| ذخیره در `ips.txt` | ✓ | فقط کلیپ‌بورد |

---

## نکاتی برای شبکه‌های محدود

**با پیش‌فرض‌ها شروع کنید.** ۵,۰۰۰ IP، ۵۰ worker، timeout ۵ ثانیه و پورت ۴۴۳ baseline خوبی روی خطوط lossy است.

**بعد از اسکن اول از From File استفاده کنید.** با `c` نتایج را بگیرید، `ips.txt` را ویرایش کنید، و shortlist را با پورت‌های بیشتر تست کنید.

**چند پورت امتحان کنید.** پورت‌های CDN Cloudflare زیر DPI رفتار متفاوتی دارند.

**به اسکن همسایه اعتماد کنید.** در حالت Random نیازی به بالا بردن Count نیست — هر hit سالم به‌صورت خودکار همسایه‌هایش را در صف قرار می‌دهد.

**کانفیگ WebSocket به IP سازگار با WS نیاز دارد.** برای `type=ws`، hold TLS + upgrade WS اجرا می‌شود. IPای که trace را رد کند ولی WS را نه، کاندید فاز ۲ نمی‌شود.

**۰٪ loss به تنهایی کافی نیست.** throughput غیرصفر یا WS موفق هم لازم است.

---

## سوالات متداول

**چرا ping نمی‌زند؟**
Cloudflare ICMP را روی edge IPها drop می‌کند. SenPai Scanner رفتار HTTP/TLS واقعی را تست می‌کند که به استفاده عملی VLESS/Trojan نزدیک‌تر است.

**تفاوتش با warp-plus چیست؟**
SenPai Scanner پروکسی دائمی راه نمی‌اندازد. IPهای Cloudflare را برای **کانفیگ xray شما** پیدا و اعتبارسنجی می‌کند و لیست `IP:port` export می‌دهد.

**محدوده IPها از کجاست؟**
از لیست‌های رسمی Cloudflare — `cloudflare.com/ips-v4` و `cloudflare.com/ips-v6` — که داخل باینری embed شده‌اند.

**«ips.txt not found» در From File چیست؟**
فایل را کنار executable یا در پوشه کاری فعلی بگذارید.

**اسکن با پورت‌های زیاد کند است.**
هر پورت برای هر IP پروب می‌شود. ۵ پورت × ۵,۰۰۰ IP برابر است با ۲۵,۰۰۰ پروب در فاز ۱. Count یا تعداد پورت‌ها را کاهش دهید.

**چرا tested از Count بیشتر است؟**
در حالت Random، اسکن همسایه تا ۴۰۰ پروب اضافه می‌کند. این رفتار عمدی است.

---

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

### دسکتاپ

```bash
git clone https://github.com/matinsenpai/senpaiscanner.git
cd senpaiscanner
make build          # پلتفرم فعلی
make build-all      # همه پلتفرم‌ها ← dist/
make test
make install        # در $GOPATH/bin
```

**Windows (cross-compile):**

```powershell
powershell -ExecutionPolicy Bypass -File build.ps1
# اختیاری: -Version "0.6.0"
```

تگ `v*` با GitHub Actions و GoReleaser آرشیو چندپلتفرمی و checksum منتشر می‌کند.

### اندروید

```bash
# ساخت کتابخانه Go mobile
cd android
./build_go_mobile.sh        # Linux / macOS
build_go_mobile.bat         # Windows

# ساخت APK
./gradlew :app:assembleDebug
./gradlew :app:assembleRelease   # نیاز به keystore
```

CI با push تگ، APK امضاشده را به Release ضمیمه می‌کند.

---

## مشارکت

[CONTRIBUTING.md](CONTRIBUTING.md) را ببینید.

Issue و PR خوش‌آمد است. برای تغییرات بزرگ اول یک issue باز کنید تا درباره جهت پروژه صحبت کنیم.

برای گزارش باگ لطفاً موارد زیر را ذکر کنید: OS/arch، نسخه (`senpaiscanner --version`)، صفحه‌ای که در آن بودید، رفتار موردانتظار در مقابل آنچه دیدید.

---

## نقشه راه

- آستانه قابل تنظیم download/upload برای فیلتر نهایی
- تنظیمات پایدار روی اندروید
- حالت `Watch` برای مانیتورینگ مداوم
- export مستقیم به فرمت JSON برای xray / Sing-Box از صفحه نتایج

---

## مجوز

MIT — [LICENSE](LICENSE)