A Cloudflare IP finder with a terminal UI, built for networks where latency is unpredictable and connections drop without warning. Paste your VLESS or Trojan config, pick your settings, and let it find IPs that actually work through your proxy — no commands to memorize.
Run senpaiscanner and you land in a short menu. Navigate with arrow keys and Enter — no flags, no subcommands.
┌────────────────────────────────────────────────────────────┐
│ ▶ Find Working IPs paste a config and test CF IPs │
│ About │
│ Quit │
└────────────────────────────────────────────────────────────┘
Find Working IPs runs in two phases:
- Phase 1 — Connectivity scan probes candidate Cloudflare IPs using settings derived from your config URL (SNI, host, WebSocket path, port). It checks trace reachability and, for WebSocket configs, whether a WS-style TLS connection survives DPI.
- Phase 2 — xray validation launches an embedded xray instance and tests the best Phase 1 hits end-to-end through your actual VLESS/Trojan config. Results show endpoint, transport type, download speed, latency (TTFB), and pass/fail status.
When Phase 2 finishes, press c to copy working IP:port endpoints to the clipboard and save them to ips.txt next to the binary (or current working directory).
Download from the releases page.
| Platform | Architecture | File |
|---|---|---|
| Linux | x86_64 | senpaiscanner_linux_x86_64.tar.gz |
| Linux | ARM64 | senpaiscanner_linux_arm64.tar.gz |
| macOS | Intel | senpaiscanner_darwin_x86_64.tar.gz |
| macOS | Apple Silicon | senpaiscanner_darwin_arm64.tar.gz |
| Windows | x86_64 | senpaiscanner_windows_x86_64.zip |
Linux / macOS:
stable release:
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bashpre-release:
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash -s -- --prereleaseWindows (PowerShell):
$r = Invoke-RestMethod https://api.github.com/repos/matinsenpai/senpaiscanner/releases/latest
$url = ($r.assets | Where-Object name -like "*windows*x86_64*").browser_download_url
Invoke-WebRequest $url -OutFile senpaiscanner.zip
Expand-Archive senpaiscanner.zip .go install github.com/matinsenpai/senpaiscanner/cmd/senpaiscanner@latestsenpaiscanner # open the TUI
senpaiscanner --version # print version and exit
senpaiscanner -v # same
senpaiscanner version # sameEverything else is inside the TUI — there are no scan-related CLI flags.
| Key | Action |
|---|---|
↑ / ↓ or k / j |
move between rows |
← / → or h / l |
move between options within a row |
Enter |
select / confirm / start |
Esc |
go back |
q |
quit from menu; during a scan, cancel or return to menu when finished |
On the Config URL row, ← / → move the text cursor; Ctrl+A / Ctrl+E jump to start / end. Vim keys h / j / k / l type normally into the URL field on that row.
Paste a vless:// or trojan:// share URL, adjust the setup rows, then start the scan.
| Row | Options | Notes |
|---|---|---|
| Source | Random / From File | random Cloudflare IPv4 ranges, or read candidates from ips.txt |
| Count | 1,000 / 5,000 / 20,000 / Custom | IPs to probe in Phase 1; ignored when Source is From File |
| Workers | 50 / 100 / 200 / Custom | parallel probers (default 50 — safe on restricted networks) |
| Timeout | 2s / 3s / 5s / Custom | per-probe deadline (default 5s) |
| Ports | Config, 443, 8443, 2053, 2083, 2087, 2096 | multi-select; each IP is tested on every selected port |
Press Enter on the last row to continue to the optional config step.
| Row | Options | Notes |
|---|---|---|
| Config | paste URL or leave empty | empty → Phase 1 only (standard HTTP probe); with URL → Phase 1 + Phase 2 |
| Top N | 10 / 25 / 50 / 100 / All / Custom | how many Phase 1 hits to validate in Phase 2 (only when a config URL is set) |
Enter with an empty config field starts a connectivity-only scan. Paste a URL, set Top N, then Enter again to run full validation.
Live results file: every scan writes (and keeps updating) SenPaiScannerResult-YYYYMMDD-HHMMSS.txt next to the binary or in the working directory. Open it in any editor while the scan runs to watch results arrive.
Source → From File: place ips.txt (one IP per line) next to the binary or in the directory you run from. All listed IPs are probed on the selected ports; the Count row is ignored.
Ports row: use ← / → to focus a port pill, then Space or Enter to toggle it. Select Config alone to use the port from your URL. Selecting multiple ports multiplies Phase 1 work (IPs × ports).
Starting the scan: Enter on Ports opens the optional config screen. From there, Enter starts the scan (empty config = Phase 1 only).
Without a config URL, Phase 1 uses a standard Cloudflare HTTP probe (speed.cloudflare.com, 64 KiB sample). With a config URL, probes use SNI/host/path from your link and require WebSocket success when type=ws.
Press q / Esc to cancel and return to the menu.
The top Phase 1 candidates are tested through an embedded xray instance with your config. The live table shows:
| Column | Meaning |
|---|---|
| ENDPOINT | IP:port that was validated |
| TYPE | transport (ws, grpc, xhttp, …) |
| SPEED | measured download throughput in Mbps, or n/a if speed could not be measured |
| LATENCY | time to first byte through the proxy (TTFB) |
| STATUS | ✓ working / ✗ failed |
| Key | Action |
|---|---|
c |
copy working endpoints to clipboard and save to ips.txt |
q / Esc |
return to the main menu |
Exported lines look like 104.16.72.162:443 — ready to paste into client configs or DNS/IP lists.
Version string and short project blurb; Enter / q / Esc back to the menu.
Start with defaults. 5,000 random IPs, 50 workers, 5s timeout, and the config port are a good baseline on lossy or filtered lines.
Use From File after a partial run. Copy working endpoints with c, edit ips.txt, then re-run with Source → From File to validate only your shortlist on more ports.
Try multiple ports. Cloudflare CDN ports (443, 8443, 2053, …) behave differently under DPI. Multi-port selection lets Phase 1 find the best IP:port pair before xray validation.
WebSocket configs need WS-friendly IPs. Phase 1 runs an idle TLS hold plus a WebSocket upgrade check when your URL uses type=ws. An IP that passes trace but fails WS will not become a Phase 2 candidate.
0% loss alone is not enough. For HTTP-style probing, non-zero download throughput or a successful WS check is required for an IP to count as healthy.
Speed in Phase 2 is best-effort. Connectivity is confirmed via cp.cloudflare.com/cdn-cgi/trace. Download speed is measured when possible (Cloudflare speed endpoint, config host, or parallel trace sampling). If speed cannot be measured reliably, the endpoint can still show ✓ with SPEED n/a.
Why doesn't it just run a ping? Cloudflare drops ICMP on their edge IPs. SenPai Scanner validates HTTP/TLS behaviour and, for proxy configs, runs traffic through xray — closer to real VLESS/Trojan usage than ping or bare TCP.
How is this different from warp-plus?
SenPai Scanner does not run a permanent proxy. It finds and validates Cloudflare IPs for your xray config and exports IP:port lists you can plug into Sing-Box, v2rayN, etc.
Where do the IP ranges come from?
Embedded from Cloudflare's official published lists (cloudflare.com/ips-v4, cloudflare.com/ips-v6). The binary ships with a snapshot; ranges rarely change.
"ips.txt not found" when using From File
Place ips.txt next to the executable or in your current working directory before starting. One IP per line; # comments and CSV lines (IP in the first column) are supported.
The scan feels slow with many ports selected Each selected port is probed for every IP. Testing 5 ports on 5,000 IPs means 25,000 probes in Phase 1 — lower Count or narrow the port list if needed.
What happened to Quick Scan, Custom Scan, Test IPs, and Discover Colos? Those separate menu flows were removed to focus on one workflow: paste your config, find working endpoints, export results. The core probe engine is still used internally by Find Working IPs.
git clone https://github.com/matinsenpai/senpaiscanner.git
cd senpaiscanner
make build # current platform
make build-all # all platforms → dist/
make test
make install # to $GOPATH/binWindows (cross-compile all platforms):
powershell -ExecutionPolicy Bypass -File build.ps1
# optional: -Version "0.4.0"Binaries land in dist/.
See CONTRIBUTING.md for project principles, development setup, and pull request guidelines.
Issues and PRs are welcome. For larger changes, open an issue first to discuss scope.
For bugs, include your OS/arch, version (senpaiscanner --version), the screen you were on, and what you expected vs what happened.
- Configurable download/upload thresholds for final filtering
- Persistent settings saved between sessions
Watchmode for continuous monitoring- Export directly to xray/Sing-Box JSON from the results screen
MIT — see LICENSE.