cfray is a single-file Python proxy toolkit for VLESS/VMess configs behind Cloudflare. What started as an IP scanner is now a full suite:
- **Config Scanner** — test hundreds of IPs for latency + download speed, rank by score, export the best configs
- **Clean IP Finder** — scan all ~1.5M Cloudflare IPv4 addresses to find reachable edge IPs (Mega mode: ~3M probes on 2 ports)
- **Xray Pipeline Test** — 3-stage pipeline that scans IPs, swaps them into your config, and expands with fragment presets + SNI variations to bypass DPI/firewall blocks
- **Deploy Xray Server** — deploy a full xray-core server on any Linux VPS with systemd, TLS certs, REALITY keys, and multi-config support
- **Worker Proxy** — generate a Cloudflare Worker script for a fresh `workers.dev` SNI on any VLESS WebSocket config
- **Connection Manager** — manage inbounds, users, URIs, and uninstall on deployed servers
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](https://www.cloudflare.com/ips-v4/) 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`).
```bash
# Interactive
python3 scanner.py
# Press F, choose scan mode
# CLI
python3 scanner.py --find-clean --no-tui --clean-mode mega
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 |
v1.1 adds **server deployment**, **pipeline testing**, **worker proxy**, and a **connection manager** — turning cfray from a scanner into a full proxy toolkit.
---
### ⚡ Xray Pipeline Test `[X]`
A smart 3-stage pipeline that takes a single VLESS/VMess config and finds the best way to connect through it — including DPI bypass via TLS fragmentation.
**How it works:**
```
Stage 1: 🔍 IP Scan
Scans Cloudflare IP ranges to find clean, reachable IPs.
Tests thousands of IPs in parallel via TLS handshake.
Stage 2: 🧪 Base Test
Swaps each clean IP into your config and tests if it actually
passes traffic. Uses a direct VLESS tunnel to verify real
connectivity — not just a handshake. Filters down to IPs
that work with your specific config.
Stage 3: 🔧 Fragment Expansion
Takes the working IPs and expands them with DPI bypass fragment
presets + SNI variations:
- light: 100-200 byte fragments, 10-20ms interval
- medium: 50-200 byte fragments, 10-40ms interval
- heavy: 10-300 byte fragments, 5-50ms interval
Finds the best combination of IP + fragment + SNI.
```
**Use case:** You have a config that doesn't connect (blocked by DPI/firewall). Instead of manually trying different IPs and fragment settings, the pipeline automatically finds working combinations.
**xray-core** is required — cfray downloads it automatically on first use or you can install manually:
python3 scanner.py --xray 'vless://...' --xray-frag heavy --xray-keep 5
```
---
### 🚀 Deploy Xray Server `[D]`
Deploy a fully configured Xray proxy server on any Linux VPS in under 2 minutes. The wizard walks you through every step — protocol, transport, security, port — and generates ready-to-use client URIs.
**What it sets up:**
- Downloads and installs **xray-core** binary
- Generates server config with your chosen protocol/transport/security
- Creates **systemd service** for auto-start on boot
- Obtains **TLS certificates** via certbot (for TLS security)
| Transport | TCP, WebSocket, gRPC, HTTP/2, XHTTP |
| Security | REALITY, TLS, None |
| Ports | Any port (default 443) |
> **Note:** REALITY mode only supports TCP, gRPC, and HTTP/2 transports. WebSocket and XHTTP are available with TLS or None security.
**REALITY** is the recommended security mode — it doesn't need a domain or TLS certificates. It uses x25519 key exchange with a "camouflage" SNI (like `yahoo.com` or `google.com`) to make traffic look like normal HTTPS.
**XHTTP** (also called SplitHTTP) is a CDN-compatible transport that works well behind Cloudflare and other CDN providers. It splits HTTP requests in a way that bypasses many DPI systems.
**Multi-config deploy:** You can deploy multiple protocol configurations in a single session. For example, deploy TCP+REALITY on port 443 *and* WS+TLS on port 444 on the same server. Each config gets its own UUID and port. REALITY keys and TLS certificates are generated once and reused across configs.
- **[V] View URIs** — display all generated client configs again (they don't disappear)
- **[M] Connection Manager** — jump straight to managing the server
- **[Q] Back** — return to main menu
---
### ☁️ Worker Proxy `[O]`
Get a fresh **Cloudflare Workers** SNI for any VLESS config. cfray generates a Worker script that proxies WebSocket traffic to your backend server — you deploy it to your Cloudflare account and get a clean, unblocked `workers.dev` SNI.
**How it works:**
1. You provide a working VLESS config (WebSocket transport required)
2. cfray generates a JavaScript Worker script that relays WebSocket connections to your backend
3. cfray shows the script + step-by-step instructions to deploy it on `dash.cloudflare.com`
4. You paste the resulting Worker URL back into cfray
5. cfray outputs a new config with the fresh `*.workers.dev` domain as SNI
**Use case:** Your config works but the SNI/domain is blocked in your region. Instead of finding a new domain, you create a Workers proxy that gives you a clean `workers.dev` SNI. Since Cloudflare Workers domains are widely used for legitimate purposes, they're rarely blocked.
**Requirements:**
- A Cloudflare account (free tier works)
- Your original config must use **WebSocket** transport (Workers only proxy WS traffic)
# 3. Your Worker URL (after you deploy it on dash.cloudflare.com)
```
---
### 🔧 Connection Manager `[C]`
Manage an existing Xray server's configuration directly — add/remove inbounds, manage users, view client URIs, and uninstall. Works with any xray-core server deployed by cfray.
**What you can do:**
| Key | Action |
|-----|--------|
| `A` | **Add inbound** — create a new protocol/transport/port |
| `V` | **View** — view inbound JSON details |
| `U` | **Add user** — add a new UUID to an existing inbound |
**Show URIs** generates VLESS/VMess client URIs from the server's config file for every inbound and every user. This is useful when you've deployed multiple configs and need to share the URIs with users, or when you've lost the original URIs from deploy time.
**Uninstall** completely removes everything cfray installed: stops the xray service, removes the binary, deletes config files, removes the systemd service, and cleans up the `~/.cfray/` directory. Requires typing "uninstall" to confirm (safety check).
کانفیگ یا آیپی ندارید؟ cfray میتونه **تمام رنج آیپیهای کلادفلر** رو اسکن کنه و آیپیهای تمیز و قابل دسترس رو پیدا کنه — بعد مستقیم با حالت Template تست سرعت کنید.
**چطوری کار میکنه:**
1. آیپیها رو از ۱۴ زیرشبکه IPv4 کلادفلر تولید میکنه (~۱.۵ میلیون آیپی)
2. هر آیپی رو با TLS handshake + بررسی هدر کلادفلر تست میکنه
3. آیپیهای جوابدهنده رو بر اساس پینگ مرتب برمیگردونه
4. نتایج رو ذخیره کنید یا با حالت Template برای تست سرعت استفاده کنید
کلادفلر [۱۴ زیرشبکه IPv4](https://www.cloudflare.com/ips-v4/) منتشر کرده که مجموعاً **~۱,۵۱۱,۸۰۸ آیپی یکتا** هستن. حالتهای Full و Mega همه رو اسکن میکنن. **حالت Mega** هر آیپی رو روی پورت 443 و 8443 (پورت جایگزین HTTPS کلادفلر) تست میکنه و تعداد پروبها رو به **~۳ میلیون** میرسونه (۱.۵ میلیون آیپی × ۲ پورت). وقتی بعضی آیپیها روی یه پورت مسدود هستن ولی روی پورت دیگه کار میکنن، این حالت خیلی مفیده.
```bash
# تعاملی
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) → برترینها
(اگه کمتر از ۵۰ آیپی باشه، همه توی هر مرحله تست میشن)
v1.1 قابلیتهای **دیپلوی سرور**، **تست پایپلاین**، **پروکسی ورکر** و **مدیریت اتصالات** رو اضافه کرده — cfray رو از یه اسکنر به یه ابزار کامل پروکسی تبدیل کرده.
---
### ⚡ تست پایپلاین Xray `[X]`
یه پایپلاین هوشمند ۳ مرحلهای که یه کانفیگ VLESS/VMess میگیره و بهترین راه اتصال رو پیدا میکنه — شامل دور زدن DPI با فرگمنت TLS.
**چطوری کار میکنه:**
```
مرحله ۱: 🔍 اسکن آیپی
رنجهای آیپی کلادفلر رو اسکن میکنه تا آیپیهای تمیز و قابل
دسترس پیدا کنه. هزاران آیپی رو همزمان با TLS handshake تست میکنه.
مرحله ۲: 🧪 تست پایه
هر آیپی تمیز رو توی کانفیگتون جایگزین میکنه و تست میکنه که آیا
واقعاً ترافیک رد میکنه یا نه. از تانل مستقیم VLESS برای تایید
اتصال واقعی استفاده میکنه — نه فقط handshake. آیپیهایی که با
کانفیگ خاص شما کار میکنن فیلتر میشن.
مرحله ۳: 🔧 گسترش فرگمنت
آیپیهای کارکننده رو با پریستهای فرگمنت DPI bypass و تغییرات
**کاربرد:** کانفیگی دارید که وصل نمیشه (مسدود شده توسط DPI/فایروال). به جای اینکه دستی آیپی و تنظیمات فرگمنت مختلف رو امتحان کنید، پایپلاین خودکار ترکیبهای کارکننده رو پیدا میکنه.
**xray-core** لازمه — cfray اولین بار خودش دانلود میکنه یا میتونید دستی نصب کنید:
python3 scanner.py --xray 'vless://...' --xray-frag heavy --xray-keep 5
```
---
### 🚀 دیپلوی سرور Xray `[D]`
یه سرور پروکسی Xray کاملاً پیکربندیشده رو روی هر VPS لینوکسی در کمتر از ۲ دقیقه نصب کنید. ویزارد شما رو قدم به قدم راهنمایی میکنه — پروتکل، ترنسپورت، امنیت، پورت — و URI کلاینت آماده استفاده تحویل میده.
**چه چیزهایی نصب میکنه:**
- دانلود و نصب **xray-core**
- تولید کانفیگ سرور با پروتکل/ترنسپورت/امنیت دلخواه شما
- ساخت **سرویس systemd** برای اجرای خودکار
- دریافت **گواهی TLS** با certbot (برای امنیت TLS)
- تولید **کلید x25519** (برای امنیت REALITY)
- خروجی URI کلاینت VLESS/VMess که مستقیم وارد اپ میکنید
> **توجه:** حالت REALITY فقط از TCP، gRPC و HTTP/2 پشتیبانی میکنه. WebSocket و XHTTP با امنیت TLS یا None در دسترس هستن.
**REALITY** حالت امنیتی پیشنهادی هست — نیازی به دامنه یا گواهی TLS نداره. از تبادل کلید x25519 با SNI استتاری (مثل `yahoo.com` یا `google.com`) استفاده میکنه تا ترافیک شبیه HTTPS عادی به نظر بیاد.
**XHTTP** (SplitHTTP) یه ترنسپورت سازگار با CDN هست که پشت کلادفلر و CDNهای دیگه خوب کار میکنه. درخواستهای HTTP رو طوری تقسیم میکنه که از بسیاری از سیستمهای DPI رد بشه.
**دیپلوی چند کانفیگ:** میتونید چندین کانفیگ با پروتکلهای مختلف رو توی یه نشست نصب کنید. مثلاً TCP+REALITY روی پورت 443 *و* WS+TLS روی پورت 444 روی همون سرور. هر کانفیگ UUID و پورت خودش رو داره. کلیدهای REALITY و گواهی TLS یکبار تولید و بعد مجدداً استفاده میشن.
- **[V] مشاهده URI** — نمایش دوباره همه کانفیگهای تولید شده (دیگه ناپدید نمیشن)
- **[M] مدیریت اتصالات** — مستقیم به Connection Manager برید
- **[Q] برگشت** — برگشت به منوی اصلی
---
### ☁️ پروکسی ورکر `[O]`
یه **SNI تازه از Cloudflare Workers** برای هر کانفیگ VLESS بسازید. cfray یه اسکریپت Worker تولید میکنه که ترافیک WebSocket رو به سرور شما پروکسی میکنه — شما خودتون روی حساب کلادفلرتون دیپلوی میکنید و یه SNI تمیز `workers.dev` میگیرید.
**چطوری کار میکنه:**
1. یه کانفیگ VLESS کارکننده میدید (ترنسپورت WebSocket لازمه)
2. cfray یه اسکریپت JavaScript Worker تولید میکنه که اتصالات WebSocket رو به سرور شما رله میکنه
3. cfray اسکریپت + راهنمای قدم به قدم دیپلوی روی `dash.cloudflare.com` رو نشون میده
4. آدرس Worker خودتون رو توی cfray وارد میکنید
5. cfray یه کانفیگ جدید با دامنه تازه `*.workers.dev` به عنوان SNI خروجی میده
**کاربرد:** کانفیگتون کار میکنه ولی SNI/دامنه توی منطقهتون مسدود شده. به جای پیدا کردن دامنه جدید، یه پروکسی Workers میسازید که SNI تمیز `workers.dev` بهتون میده. چون دامنههای Workers کلادفلر برای کارهای قانونی زیادی استفاده میشن، به ندرت مسدود میشن.
**نیازمندیها:**
- حساب کلادفلر (تیر رایگان کافیه)
- کانفیگ اصلی باید ترنسپورت **WebSocket** داشته باشه
```bash
# تعاملی
python3 scanner.py # O رو بزنید
```
---
### 🔧 مدیریت اتصالات (Connection Manager) `[C]`
کانفیگ سرور Xray موجود رو مستقیم مدیریت کنید — اضافه/حذف inbound، مدیریت کاربران، مشاهده URI کلاینتها و حذف نصب.
**کلیدهای مدیریت:**
| کلید | عملکرد |
|------|--------|
| `A` | **اضافه کردن inbound** — پروتکل/ترنسپورت/پورت جدید بسازید |
| `D` | **حذف نصب** — xray، کانفیگ، systemd رو کامل پاک کنید |
| `B` | **برگشت** — برگشت به منوی اصلی |
**نمایش URI** از فایل کانفیگ سرور، URIهای VLESS/VMess کلاینت رو برای هر inbound و هر کاربر تولید میکنه. وقتی چندین کانفیگ دیپلوی کردید و باید URIها رو با کاربران به اشتراک بذارید، یا وقتی URIهای اصلی از زمان دیپلوی گم شدن، خیلی مفیده.
**حذف نصب** هر چیزی که cfray نصب کرده رو کامل حذف میکنه: سرویس xray رو متوقف میکنه، باینری رو حذف میکنه، فایلهای کانفیگ رو پاک میکنه، سرویس systemd رو حذف میکنه و پوشه `~/.cfray/` رو تمیز میکنه. برای ایمنی باید عبارت "uninstall" رو تایپ کنید.
```bash
# تعاملی
python3 scanner.py # C رو بزنید
```
---
### 🔧 فلگهای جدید CLI در v1.1
| فلگ | توضیحات | پیشفرض |
|-----|---------|--------|
| `--xray URI` | تست URI از طریق پایپلاین xray | — |
