SenPaiScanner: a Go Cloudflare endpoint scanner with Xray validation and client-ready exports

The problem SenPaiScanner targets: filtered networks and dead Cloudflare endpoints

Cloudflare fronts a large share of the internet, and its edge addresses are not equally reachable from every network. On a filtered or high-latency link, an address that resolves and accepts a TCP connection may still fail once TLS, SNI and the proxy transport are in play. Picking a working endpoint by hand means guessing, and guessing repeatedly.

SenPaiScanner exists to replace that guessing. The README describes it as a "cross-platform Cloudflare endpoint scanner for unstable, filtered, or high-latency networks" that performs edge probing and then validates the best candidates through your actual proxy configuration using an embedded Xray core. That second stage is the part that separates it from a plain reachability sweep: a candidate is only useful if your own proxy settings can complete a session through it.

The audience follows from that. You need this if you already hold share links (the README names vless://, trojan:// and vmess://) and you want a ranked list of endpoints plus a client configuration you can import. You do not need it if you are looking for a general-purpose network scanner or a proxy client; it is neither.

Two-stage validation and the Signal Desk data flow

The engine works in two passes. Discovery samples Cloudflare IPv4 ranges with weighted random selection, probing multiple ports with a configurable worker count, timeout, and an optional WebSocket check. Results stream into the interface live, with health, latency, loss, throughput, colo, port and status reported as they arrive.

The second pass is validation. When you stop discovery, the healthy set can be speed-tested as a shortlist, and passing candidates are run through the embedded Xray core against your real proxy configuration. The README states that SNI, host, path, transport, TLS and port are derived from the share link, so the validation reflects your setup rather than a generic handshake. Download throughput and TTFB are measured, with optional upload testing where configured.

Around that engine sit three interfaces sharing one workflow: a desktop GUI for Windows, Linux and macOS, an Android app for Android 7.0+, and a CLI/TUI for the same desktop platforms plus Termux. The README splits the desktop and Android experience into Scan, Results and Export workspaces. Export is deliberately separate from Results, so generating a configuration does not interrupt inspection. Cancellation preserves results already discovered, which matters when a scan has been running for a while.

Installing SenPaiScanner and running a first scan from the CLI

There is no package registry step. The README points to GitHub Releases, where the v1.0.0 workflow publishes every supported interface together and adds SHA256SUMS.txt. Download the asset for your platform, then make it executable on Linux or macOS:

chmod +x SenPaiScanner-1.0.0-cli-*
./SenPaiScanner-1.0.0-cli-linux-amd64

The README gives exactly these two lines for the CLI assets. If you would rather build from source, the repository ships a Makefile whose build target compiles ./cmd/senpaiscanner into a binary named senpaiscanner, with version, commit and build date injected through -ldflags. The install target runs go install on the same command path.

make build
make build-linux-amd64

Those two targets produce the local binary and the Linux amd64 artifact under dist/. The Makefile also defines test as go test -race -cover ./..., which is the check to run if you are building your own copy.

For a first real use, the desktop GUI is the intended entry point: configure source, ports, workers, timeout, WebSocket requirement, proxy URL and the optional neighbor scan in the Scan workspace, then watch Results. The CLI is described as keyboard-first and automation-friendly, but the README does not document its flags, so treat the GUI as the documented path and read the CLI help before scripting against it.

Where SenPaiScanner is the wrong tool

The scanner assumes you already have working share links. Validation runs through your proxy configuration, so if the VLESS, Trojan or VMess link is itself broken or expired, every candidate will fail validation and the tool will look like it found nothing. It cannot repair a bad link, and the README does not describe any link-testing or repair step.

Neighbor scanning is off by default, and the README's own wording, "Nearby Cloudflare addresses are explored only when you explicitly enable the option", is a signal that broad exploration has a cost. Turning it on widens the address space you probe, which multiplies scan time and the load you place on the edge. For a quick check, leaving it off is the sensible default.

The README also does not document rollback, so there is no described way to undo an export or revert a configuration file the tool generated. If you are generating Clash YAML or sing-box JSON into a directory that another tool consumes, keep your own backups. And the metadata story is explicitly a merge: ISP and ASN detection combines Cloudflare, IPWhois and IPinfo with a Team Cymru DNS fallback. That is resilience against one provider failing, not a guarantee of accuracy, and the README does not state how disagreements between those sources are resolved.

How SenPaiScanner differs from v2rayN and generic Cloudflare scanners

v2rayN is a Windows client for managing and running proxy configurations. SenPaiScanner is not a client. It scans, validates and exports; the README's output list is raw endpoints, rewritten share URLs, Base64 subscription data, sing-box JSON and Clash YAML. The intended flow is to feed those files into a client you already use. If your problem is running a proxy, v2rayN solves it and SenPaiScanner does not.

The closer comparison is a generic Cloudflare IP scanner that only checks TCP reachability. The difference is the second stage. A reachability-only scanner tells you an address answers; SenPaiScanner additionally runs the candidate through the embedded Xray core against your parsed transport settings and reports throughput and TTFB. That is a heavier operation per candidate, and it is why the workflow separates discovery from speed testing: you stop when you have enough green results, then test only that shortlist.

The export formats are the third difference. Rewritten share links, Base64 subscriptions, sing-box JSON and Clash YAML are produced directly, so the gap between a scan result and an importable file is one copy action rather than manual editing.

Licence, maintenance and the cost of staying current

SenPaiScanner is MIT licensed, per the repository's LICENSE file and the badge in the README. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the plain reading of the licence text; it is not legal advice, and if you are redistributing a modified build you should read the file yourself.

The practical licence implication is dependency-related. The scanner embeds the Xray core (github.com/xtls/xray-core), and the module graph pulls in Wails for the desktop GUI, Bubble Tea and Lip Gloss for the TUI, and QUIC support through github.com/apernet/quic-go. Those arrive under their own licences, and the go.mod lists many of them as indirect dependencies. Vendoring or repackaging the binary means carrying all of them.

The last push to the default branch was on 2026-08-03, the same day v1.0.0 was released. The release cadence visible in the repository moves quickly: v0.5.0 on 2026-05-30, v0.7.1 on 2026-06-13, v1.0.0 on 2026-08-03. That pace is the upgrade cost. v1.0.0 introduced the redesigned Signal Desk workflow, so anyone tracking the project across that boundary should expect interface changes, not just fixes. Pinning to a release asset and checking SHA256SUMS.txt is the cheap way to control when you move.

Editorial conclusion

Adopt SenPaiScanner if you already hold VLESS, Trojan or VMess links and need a ranked shortlist of Cloudflare endpoints plus a Clash or sing-box file without hand-editing anything. Skip it if you want a general port scanner or a proxy client: it does neither. Before relying on it, verify that the SHA256SUMS.txt entry matches your downloaded asset, and confirm the embedded Xray core accepts your link's transport, since gRPC and XHTTP parsing is where a mismatch would surface first.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MatinSenPai/SenPaiScanner on GitHub
4. README
5. Releases