FreedomScanner

A high-performance IP scanner written in Go for testing VLESS/WebSocket connectivity across IP ranges

---

English

Features

• High-Speed Scanning: Scan millions of IPs with configurable concurrency (up to 2000+ simultaneous connections)
• CIDR Support: Automatically expands IP ranges in CIDR notation (e.g., 104.16.0.0/24)
• VLESS/WebSocket Testing: Tests actual VLESS connectivity, not just open ports
• Configurable Timeouts: Adjust timeouts for slow/unstable networks
• Retry Mechanism: Configurable retry count for reliability
• Latency Sorting: Results sorted by response latency
• Progress Reporting: Real-time progress updates during scan
• File-Based Configuration: Load IPs and configs from files

Installation

Prerequisites

• Go 1.21 or higher

Build from Source

git clone https://github.com/EJ-Research/freedomScanner.git
cd freedomScanner
go build -o freedomScanner .

Download Binary

Download pre-built binaries from the Releases page.

Usage

Basic Usage

# Full scan (port check + VLESS test)
./freedomScanner -ips ips.txt -config config.txt

# Port scan only (skip VLESS testing)
./freedomScanner -ips ips.txt -skip-vless

# VLESS test only (skip port scanning)
./freedomScanner -ips ips.txt -config config.txt -skip-port

Command Line Options

Flag	Default	Description
-ips	ips.txt	File containing IP ranges (one per line)
-config	config.txt	File containing VLESS config URL
-c	500	Number of concurrent connections
-pt	3s	Timeout for port scanning
-vt	5s	Timeout for VLESS testing
-r	2	Number of retries for failed connections
-o	results.txt	Output file for results
-skip-port	false	Skip port scanning, assume all ports open
-skip-vless	false	Skip VLESS testing, only scan ports
-v	false	Verbose output (show working IPs in real-time)

Performance Tuning

# Fast mode (good internet connection)
./freedomScanner -c 2000 -pt 2s -vt 3s -r 1

# Normal mode (default)
./freedomScanner -c 500 -pt 3s -vt 5s -r 2

# Slow mode (poor/unstable internet)
./freedomScanner -c 100 -pt 5s -vt 10s -r 3

# Ultra-slow mode (very poor internet)
./freedomScanner -c 50 -pt 10s -vt 15s -r 5

Input Files

IP Ranges File (ips.txt)

# Cloudflare IP Ranges
# Lines starting with # are comments

173.245.48.0/20
103.21.244.0/22
104.16.0.0/13
172.64.0.0/13

# Single IPs also supported
8.8.8.8
1.1.1.1

VLESS Config File (config.txt)

vless://uuid@ip:port?type=ws&host=example.com&path=/&security=tls&sni=example.com#name

Output

Results are saved to the output file (default: results.txt) sorted by latency:

# FreedomScanner Results
# Scanned at: 2024-01-15T10:30:00Z
# Total IPs: 1000000

# Working VLESS IPs:
104.16.0.202 # latency: 222ms
104.16.0.217 # latency: 225ms
104.16.0.248 # latency: 226ms

# IPs with open port 443 (VLESS not tested or not working):
192.168.1.1
192.168.1.2

How It Works

1. IP Expansion: CIDR ranges are expanded to individual IP addresses
2. Port Scanning: TCP connection to port 443 is attempted
3. TLS Handshake: If port is open, TLS handshake with configured SNI
4. WebSocket Upgrade: HTTP upgrade request is sent to test VLESS endpoint
5. Response Validation: Valid HTTP response indicates working connection
6. Latency Measurement: Round-trip time is recorded for each working IP

Performance Benchmarks

Concurrency	IPs/Second	Memory Usage
100	~50-100	~50MB
500	~200-400	~100MB
1000	~400-800	~200MB
2000	~800-1500	~400MB

Actual performance depends on network conditions and target server response times.

---

فارسی

ویژگی‌ها

• اسکن پرسرعت: اسکن میلیون‌ها آی‌پی با همزمانی قابل تنظیم (تا 2000+ اتصال همزمان)
• پشتیبانی CIDR: باز کردن خودکار رنج‌های آی‌پی در فرمت CIDR (مثل 104.16.0.0/24)
• تست VLESS/WebSocket: تست اتصال واقعی VLESS، نه فقط پورت باز
• تایم‌اوت قابل تنظیم: تنظیم تایم‌اوت برای شبکه‌های کند/ناپایدار
• مکانیزم تلاش مجدد: تعداد تلاش مجدد قابل تنظیم برای اطمینان بیشتر
• مرتب‌سازی بر اساس تاخیر: نتایج بر اساس زمان پاسخ مرتب می‌شوند
• گزارش پیشرفت: نمایش زنده پیشرفت اسکن
• پیکربندی فایل‌محور: بارگذاری آی‌پی‌ها و کانفیگ از فایل

نصب

پیش‌نیازها

• Go نسخه 1.21 یا بالاتر

ساخت از سورس

git clone https://github.com/EJ-Research/freedomScanner.git
cd freedomScanner
go build -o freedomScanner.exe .

دانلود باینری

باینری‌های آماده را از صفحه Releases دانلود کنید.

نحوه استفاده

استفاده پایه

# اسکن کامل (چک پورت + تست VLESS)
.\freedomScanner.exe -ips ips.txt -config config.txt

# فقط اسکن پورت (بدون تست VLESS)
.\freedomScanner.exe -ips ips.txt -skip-vless

# فقط تست VLESS (بدون اسکن پورت)
.\freedomScanner.exe -ips ips.txt -config config.txt -skip-port

پارامترهای خط فرمان

پارامتر	پیش‌فرض	توضیح
-ips	ips.txt	فایل حاوی رنج آی‌پی‌ها (هر خط یک رنج)
-config	config.txt	فایل حاوی کانفیگ VLESS
-c	500	تعداد اتصالات همزمان
-pt	3s	تایم‌اوت برای اسکن پورت
-vt	5s	تایم‌اوت برای تست VLESS
-r	2	تعداد تلاش مجدد برای اتصالات ناموفق
-o	results.txt	فایل خروجی نتایج
-skip-port	false	رد شدن از اسکن پورت
-skip-vless	false	رد شدن از تست VLESS
-v	false	خروجی مفصل (نمایش آی‌پی‌های کارا در لحظه)

تنظیم عملکرد

# حالت سریع (اینترنت خوب)
.\freedomScanner.exe -c 2000 -pt 2s -vt 3s -r 1

# حالت معمولی (پیش‌فرض)
.\freedomScanner.exe -c 500 -pt 3s -vt 5s -r 2

# حالت کند (اینترنت ضعیف/ناپایدار)
.\freedomScanner.exe -c 100 -pt 5s -vt 10s -r 3

# حالت خیلی کند (اینترنت خیلی ضعیف)
.\freedomScanner.exe -c 50 -pt 10s -vt 15s -r 5

فایل‌های ورودی

فایل رنج آی‌پی (ips.txt)

# رنج‌های آی‌پی کلودفلر
# خطوط شروع شده با # نادیده گرفته می‌شوند

173.245.48.0/20
103.21.244.0/22
104.16.0.0/13
172.64.0.0/13

# آی‌پی تکی هم پشتیبانی می‌شود
8.8.8.8
1.1.1.1

فایل کانفیگ VLESS (config.txt)

vless://uuid@ip:port?type=ws&host=example.com&path=/&security=tls&sni=example.com#name

خروجی

نتایج در فایل خروجی (پیش‌فرض: results.txt) ذخیره می‌شوند، مرتب شده بر اساس تاخیر:

# FreedomScanner Results
# Scanned at: 2024-01-15T10:30:00Z
# Total IPs: 1000000

# Working VLESS IPs:
104.16.0.202 # latency: 222ms
104.16.0.217 # latency: 225ms
104.16.0.248 # latency: 226ms

# IPs with open port 443 (VLESS not tested or not working):
192.168.1.1
192.168.1.2

نحوه عملکرد

1. گسترش آی‌پی: رنج‌های CIDR به آی‌پی‌های جداگانه تبدیل می‌شوند
2. اسکن پورت: اتصال TCP به پورت 443 تست می‌شود
3. هندشیک TLS: اگر پورت باز باشد، هندشیک TLS با SNI تنظیم شده
4. آپگرید WebSocket: درخواست HTTP برای تست اندپوینت VLESS
5. اعتبارسنجی پاسخ: پاسخ HTTP معتبر نشان‌دهنده اتصال کارا است
6. اندازه‌گیری تاخیر: زمان رفت و برگشت برای هر آی‌پی کارا ثبت می‌شود

بنچمارک عملکرد

همزمانی	آی‌پی/ثانیه	مصرف حافظه
100	~50-100	~50MB
500	~200-400	~100MB
1000	~400-800	~200MB
2000	~800-1500	~400MB

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

---

License

MIT License - See LICENSE file for details

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change

Disclaimer

This tool is for educational and legitimate testing purposes only. Users are responsible for ensuring they have proper authorization before scanning any networks or IP ranges

---

Star ⭐ this repo if you find it useful!