cfray/README.md

⚡ cfray

Cloudflare Config Scanner & Clean IP Finder

Test VLESS/VMess proxy configs for latency & speed + Scan all ~1.5M Cloudflare IPs to find clean, reachable edges

English • فارسی

---

🇬🇧 English

📖 What is cfray?

cfray is a single-file Python tool that finds the fastest Cloudflare edge IPs for your VLESS/VMess proxy configs. It tests latency (ping) and download speed across hundreds of IPs, ranks them by score, and exports the best configs — ready to use. It also includes a Clean IP Finder that scans all ~1.5M Cloudflare IPv4 addresses (from 14 published subnets) to discover reachable edge IPs. Mega mode tests each IP on 2 ports for ~3M total probes.

Zero dependencies. Just Python 3.8+ and one file.

---

🚀 Quick Start

# Download
git clone https://git.samnet.dev/SamNet-dev/cfray.git
cd cfray

# Run interactive TUI
python3 scanner.py

# That's it! Pick your input, choose a mode, and watch the results.

---

📥 Input Methods

cfray supports 5 ways to load your configs:

1️⃣ Config File [1-9]

A .txt file with one VLESS or VMess URI per line:

vless://uuid@domain1.ir:443?type=ws&host=sni.com&path=/dl&security=tls#config-1
vless://uuid@domain2.ir:443?type=ws&host=sni.com&path=/dl&security=tls#config-2
vmess://eyJ2IjoiMiIsImFkZCI6...

Drop your file in the same folder as scanner.py and it shows up automatically.

2️⃣ Subscription URL [S]

Paste a remote URL that serves VLESS/VMess configs:

# Interactive
python3 scanner.py
# Press S, paste URL

# CLI
python3 scanner.py --sub https://example.com/sub.txt

Supports both plain text (one URI per line) and base64-encoded subscriptions.

3️⃣ Template + Address List [T]

Have ONE working config but want to test it against many Cloudflare IPs? This is for you.

How it works:

1. You give a VLESS/VMess config as a template
2. You give a .txt file with Cloudflare IPs or domains (one per line)
3. cfray creates a config for each address by replacing the IP in your template
4. Tests them all and finds the fastest

# Interactive
python3 scanner.py
# Press T, paste your config, enter path to address list

# CLI
python3 scanner.py --template 'vless://uuid@placeholder:443?type=ws&...' -i addresses.txt

Example address list (addresses.txt):

104.21.12.206
188.114.96.7
172.67.132.102
172.67.166.192

4️⃣ Domain JSON File

A JSON file with domain + IP data:

{"data": [
  {"domain": "example.ir", "ipv4": "104.21.x.x"},
  {"domain": "other.ir", "ipv4": "172.67.x.x"}
]}

5️⃣ Clean IP Finder [F]

Don't have any configs or IPs? cfray can scan all Cloudflare IP ranges to find clean, reachable edge IPs — then use them directly with a template for speed testing.

How it works:

1. Generates IPs from all 14 Cloudflare IPv4 subnets (~1.5M IPs)
2. Probes each IP with TLS handshake + Cloudflare header validation
3. Returns all responding IPs sorted by latency
4. Save the results or feed them into Template mode for a full speed test

Scan modes:

Mode	IPs Tested	Ports	Est. Time	Description
Quick	~4,000	443	~30 sec	1 random IP per /24 block
Normal	~12,000	443	~2 min	3 IPs per /24 + CF verify (recommended)
Full	~1,500,000	443	20+ min	All IPs + CF verify
Mega	~3,000,000	443 + 8443	30-60 min	All IPs on 2 ports for maximum coverage

Cloudflare publishes 14 IPv4 subnets totaling ~1,511,808 unique IPs. Full and Mega modes scan all of them. Mega mode tests every IP on both port 443 and 8443 (Cloudflare's alternate HTTPS port), doubling the probes to ~3M (1.5M IPs × 2 ports). This is useful when some IPs are blocked on one port but reachable on another. Results include the port (e.g., 104.16.5.20:8443).

# Interactive
python3 scanner.py
# Press F, choose scan mode

# CLI
python3 scanner.py --find-clean --no-tui --clean-mode mega

# With custom subnets
python3 scanner.py --find-clean --no-tui --subnets "104.16.0.0/13,172.64.0.0/13"

Found IPs are saved to results/clean_ips.txt (full absolute path shown). You can then use them with Template mode to speed test a config against all discovered IPs.

---

🔬 How the Scan Works

Step 1: 🔍 DNS Resolution
  Resolve all domains to their Cloudflare edge IPs
  Group configs by IP (many domains share the same CF edge)

Step 2: 📡 Latency Test
  TCP connect + TLS handshake to each unique IP
  Mark alive/dead, measure ping & connection time

Step 3: 📊 Speed Test (progressive rounds)
  R1: Small file (1-5MB) → test all alive IPs
  R2: Medium file (5-25MB) → test top candidates
  R3: Large file (20-50MB) → test the best ones
  (For <50 IPs, ALL are tested in every round)

Step 4: 🏆 Scoring & Export
  Score = Latency (35%) + Speed (50%) + TTFB (15%)
  Export top configs ranked by score

---

⚙️ Scan Modes

Mode	Rounds	Est. Data	Est. Time	Best For
⚡ Quick	1MB → 5MB	~200 MB	~2-3 min	Fast check
🔄 Normal	1MB → 5MB → 20MB	~850 MB	~5-10 min	Balanced (recommended)
🔬 Thorough	5MB → 25MB → 50MB	~5-10 GB	~20-45 min	Maximum accuracy

---

🖥️ Dashboard Controls

After the scan, you get an interactive dashboard:

Key	Action
S	🔄 Cycle sort: score → latency → speed
C	📋 View all VLESS/VMess URIs for an IP
D	🌐 View domains for an IP
E	💾 Export results (CSV + top N configs)
A	📦 Export ALL configs sorted best → worst
J/K	⬆️⬇️ Scroll up/down
N/P	📄 Page up/down
B	◀️ Back to main menu (new scan)
H	❓ Help
Q	🚪 Quit

---

🔧 CLI Options

python3 scanner.py [options]

Option	Description	Default
-i, --input	Input file (VLESS URIs or .json)	—
--sub	Subscription URL	—
--template	VLESS/VMess template URI (use with -i)	—
-m, --mode	quick / normal / thorough	normal
--rounds	Custom rounds, e.g. "1MB:200,5MB:50"	auto
-w, --workers	Latency test workers	300
--speed-workers	Download test workers	10
--timeout	Latency timeout (seconds)	5
--speed-timeout	Download timeout (seconds)	30
--skip-download	Latency only, no speed test	off
--top	Export top N configs (0 = all)	50
--no-tui	Headless mode (plain text output)	off
-o, --output	CSV output path	auto
--output-configs	Config file output path	auto
--find-clean	Find clean Cloudflare IPs	off
--clean-mode	quick / normal / full / mega	normal
--subnets	Custom subnets (file or comma-separated)	all CF

---

💡 Examples

# Interactive TUI — easiest way
python3 scanner.py

# Quick scan with subscription
python3 scanner.py --sub https://example.com/sub.txt --mode quick

# Template: test one config against 500 IPs
python3 scanner.py --template 'vless://uuid@x:443?type=ws&host=sni.com&security=tls#test' -i ips.txt

# Headless mode for scripts/cron
python3 scanner.py -i configs.txt --no-tui --mode normal -o results.csv

# Latency only (no download test)
python3 scanner.py -i configs.txt --skip-download

# Custom rounds
python3 scanner.py -i configs.txt --rounds "2MB:100,10MB:30,50MB:10"

# Find clean Cloudflare IPs (interactive)
python3 scanner.py   # Press F

# Find clean IPs (headless, mega mode — ~3M probes)
python3 scanner.py --find-clean --no-tui --clean-mode mega

---

📁 Output Files

Results are saved to the results/ folder:

File	Contents
*_results.csv	Full CSV with all metrics
*_top50.txt	Top 50 VLESS/VMess URIs (ready to use)
*_full_sorted.txt	ALL configs sorted best → worst
clean_ips.txt	Clean Cloudflare IPs from IP finder

---

🛡️ Rate Limiting & CDN Fallback

cfray is smart about Cloudflare's speed test limits:

• Tracks request budget (550 requests per 10-minute window)
• When rate-limited (429), automatically switches to CDN mirror (cloudflaremirrors.com)
• When CF blocks large downloads (403), retries through CDN
• Shows countdown timer when waiting for rate limit reset

---

🇮🇷 فارسی

📖 cfray چیه؟

cfray یه ابزار پایتونه که سریع‌ترین آی‌پی‌های کلادفلر رو برای کانفیگ‌های VLESS/VMess پیدا می‌کنه. پینگ و سرعت دانلود رو تست می‌کنه، بهترین‌ها رو امتیاز میده و خروجی آماده استفاده میده. همچنین شامل جستجوگر آی‌پی تمیز هست که تمام ~۱.۵ میلیون آی‌پی IPv4 کلادفلر (از ۱۴ زیرشبکه) رو اسکن می‌کنه. حالت Mega هر آی‌پی رو روی ۲ پورت تست می‌کنه (~۳ میلیون پروب).

بدون نیاز به نصب چیز اضافه. فقط Python 3.8+ و یه فایل.

---

🚀 شروع سریع

# دانلود
git clone https://git.samnet.dev/SamNet-dev/cfray.git
cd cfray

# اجرا
python3 scanner.py

---

📥 روش‌های ورودی

cfray ۵ روش برای بارگذاری کانفیگ‌ها داره:

1️⃣ فایل کانفیگ [1-9]

یه فایل .txt که هر خط یه آدرس VLESS یا VMess داره:

vless://uuid@domain1.ir:443?type=ws&host=sni.com&path=/dl&security=tls#config-1
vmess://eyJ2IjoiMiIsImFkZCI6...

فایلتون رو کنار scanner.py بذارید، خودش پیداش می‌کنه.

2️⃣ لینک اشتراک (Subscription) [S]

یه لینک بدید که توش کانفیگ‌های VLESS/VMess هست:

python3 scanner.py --sub https://example.com/sub.txt

هم متن ساده (هر خط یه URI) و هم base64 رو ساپورت می‌کنه.

3️⃣ قالب + لیست آدرس (Template) [T]

یه کانفیگ دارید ولی می‌خواید با کلی آی‌پی کلادفلر تستش کنید؟ این روش مال شماست!

چطوری کار می‌کنه:

1. یه کانفیگ VLESS/VMess به عنوان قالب میدید
2. یه فایل .txt با آی‌پی‌ها یا دامنه‌های کلادفلر میدید (هر خط یکی)
3. cfray به تعداد آدرس‌ها کانفیگ می‌سازه — آدرس توی قالب رو با هر آی‌پی عوض می‌کنه
4. همه رو تست می‌کنه و سریع‌ترین رو پیدا می‌کنه

# تعاملی
python3 scanner.py
# T رو بزن، کانفیگتو پیست کن، مسیر فایل آدرس‌ها رو بده

# خط فرمان
python3 scanner.py --template 'vless://uuid@x:443?type=ws&...' -i addresses.txt

مثال فایل آدرس (addresses.txt):

104.21.12.206
188.114.96.7
172.67.132.102

4️⃣ فایل JSON دامنه‌ها

{"data": [
  {"domain": "example.ir", "ipv4": "104.21.x.x"},
  {"domain": "other.ir", "ipv4": "172.67.x.x"}
]}

5️⃣ پیدا کردن آی‌پی تمیز کلادفلر [F]

کانفیگ یا آی‌پی ندارید؟ cfray می‌تونه تمام رنج آی‌پی‌های کلادفلر رو اسکن کنه و آی‌پی‌های تمیز و قابل دسترس رو پیدا کنه — بعد مستقیم با حالت Template تست سرعت کنید.

چطوری کار می‌کنه:

1. آی‌پی‌ها رو از ۱۴ زیرشبکه IPv4 کلادفلر تولید می‌کنه (~۱.۵ میلیون آی‌پی)
2. هر آی‌پی رو با TLS handshake + بررسی هدر کلادفلر تست می‌کنه
3. آی‌پی‌های جواب‌دهنده رو بر اساس پینگ مرتب برمی‌گردونه
4. نتایج رو ذخیره کنید یا با حالت Template برای تست سرعت استفاده کنید

حالت‌های اسکن:

حالت	تعداد آی‌پی	پورت‌ها	زمان تقریبی	توضیحات
Quick	~۴,۰۰۰	443	~۳۰ ثانیه	۱ آی‌پی تصادفی از هر بلاک /24
Normal	~۱۲,۰۰۰	443	~۲ دقیقه	۳ آی‌پی از هر بلاک + تایید CF (پیشنهادی)
Full	~۱,۵۰۰,۰۰۰	443	۲۰+ دقیقه	همه آی‌پی‌ها + تایید CF
Mega	~۳,۰۰۰,۰۰۰	443 + 8443	۳۰-۶۰ دقیقه	همه آی‌پی‌ها روی ۲ پورت برای حداکثر پوشش

کلادفلر ۱۴ زیرشبکه IPv4 منتشر کرده که مجموعاً ~۱,۵۱۱,۸۰۸ آی‌پی یکتا هستن. حالت‌های Full و Mega همه رو اسکن می‌کنن. حالت Mega هر آی‌پی رو روی پورت 443 و 8443 (پورت جایگزین HTTPS کلادفلر) تست می‌کنه و تعداد پروب‌ها رو به ~۳ میلیون می‌رسونه (۱.۵ میلیون آی‌پی × ۲ پورت). وقتی بعضی آی‌پی‌ها روی یه پورت مسدود هستن ولی روی پورت دیگه کار می‌کنن، این حالت خیلی مفیده.

# تعاملی
python3 scanner.py
# F رو بزن، حالت اسکن رو انتخاب کن

# خط فرمان
python3 scanner.py --find-clean --no-tui --clean-mode mega

آی‌پی‌های پیدا شده توی results/clean_ips.txt ذخیره میشن. بعد می‌تونید با حالت Template تست سرعت کنید.

---

🔬 اسکن چطوری کار می‌کنه؟

مرحله ۱: 🔍 تبدیل دامنه به آی‌پی (DNS)
  هر دامنه رو به آی‌پی کلادفلرش تبدیل می‌کنه
  کانفیگ‌هایی که آی‌پی مشترک دارن رو گروه می‌کنه

مرحله ۲: 📡 تست پینگ (Latency)
  اتصال TCP + TLS به هر آی‌پی
  زنده/مرده مشخص میشه، پینگ اندازه‌گیری میشه

مرحله ۳: 📊 تست سرعت (دانلود مرحله‌ای)
  R1: فایل کوچک (1-5MB) → همه آی‌پی‌ها
  R2: فایل متوسط (5-25MB) → بهترین‌ها
  R3: فایل بزرگ (20-50MB) → برترین‌ها
  (اگه کمتر از ۵۰ آی‌پی باشه، همه توی هر مرحله تست میشن)

مرحله ۴: 🏆 امتیازدهی و خروجی
  امتیاز = پینگ (۳۵%) + سرعت (۵۰%) + TTFB (۱۵%)
  بهترین کانفیگ‌ها رتبه‌بندی و ذخیره میشن

---

⚙️ حالت‌های اسکن

حالت	مراحل	حجم تقریبی	زمان تقریبی	مناسب برای
⚡ سریع (Quick)	1MB → 5MB	~200 MB	~2-3 دقیقه	بررسی سریع
🔄 معمولی (Normal)	1MB → 5MB → 20MB	~850 MB	~5-10 دقیقه	متعادل (پیشنهادی)
🔬 دقیق (Thorough)	5MB → 25MB → 50MB	~5-10 GB	~20-45 دقیقه	حداکثر دقت

---

🖥️ کلیدهای داشبورد

بعد از اتمام اسکن، یه داشبورد تعاملی دارید:

کلید	عملکرد
S	🔄 تغییر مرتب‌سازی: امتیاز → پینگ → سرعت
C	📋 نمایش کانفیگ‌های VLESS/VMess یه آی‌پی
D	🌐 نمایش دامنه‌های یه آی‌پی
E	💾 خروجی گرفتن (CSV + بهترین N تا)
A	📦 خروجی همه کانفیگ‌ها (مرتب شده)
J/K	⬆️⬇️ بالا/پایین
N/P	📄 صفحه بعد/قبل
B	◀️ برگشت به منو (اسکن جدید)
H	❓ راهنما
Q	🚪 خروج

---

📁 فایل‌های خروجی

نتایج توی پوشه results/ ذخیره میشن:

فایل	محتوا
*_results.csv	فایل CSV با تمام اطلاعات
*_top50.txt	۵۰ تا بهترین کانفیگ (آماده استفاده)
*_full_sorted.txt	همه کانفیگ‌ها مرتب شده
clean_ips.txt	آی‌پی‌های تمیز کلادفلر از IP Finder

---

🛡️ مدیریت محدودیت کلادفلر

cfray هوشمندانه با محدودیت‌های سرعت‌سنجی کلادفلر کار می‌کنه:

• بودجه درخواست‌ها رو پیگیری می‌کنه (۵۵۰ درخواست در هر ۱۰ دقیقه)
• وقتی محدود بشه (429)، خودکار به سرور CDN سوئیچ می‌کنه
• وقتی فایل بزرگ رد بشه (403)، از طریق CDN دوباره امتحان می‌کنه
• تایمر شمارش معکوس نشون میده

---

⭐ Made by Sam — SamNet Technologies