DOCSEARCHbyAlgolia
Submit Docs

SenPai Scanner

repository·main·Indexed 24 days ago

https://github.com/matinsenpai/senpaiscanner

A Cloudflare IP finder designed for unstable networks featuring a Terminal UI and Android app. It probes Cloudflare edge IPs and validates them using an embedded Xray instance with VLESS or Trojan configurations. The tool operates in two phases: a connectivity scan (with optional neighbor scanning in Random mode) and an Xray validation phase that measures download speed, latency (TTFB), and connection status.

Tokens
3.5K
Snippets
5
Records
19
Agent score
82%

What's inside senpaiscanner

  1. How SenPai Scanner works (Phase 1 and Phase 2)

    main

    SenPai Scanner operates in two distinct phases to find and validate usable Cloudflare IP addresses for proxy configurations (like VLESS/Trojan).

    Phase 1: Finding Available IPs

    In this phase, the scanner probes for reachable IPs. The behavior depends on whether a configuration URL is provided:

    • Without Config URL: Performs a standard HTTP probe (e.g., speed.cloudflare.com, 64 KiB sample).
    • With Config URL: Extracts SNI, host, and path from the link. For type=ws, it performs a WebSocket upgrade.
    • Random Mode: When a healthy IP is found, the scanner automatically probes nearby addresses in the same block (up to a radius of 32, maximum 12 neighbors per hit).

    Phase 2: Xray Validation

    The best candidates from Phase 1 are tested using an internal Xray engine. The results are displayed with the following columns:

    • ENDPOINT: The validated IP:port.
    • TYPE: The transport type (e.g., ws, grpc, xhttp, etc.).
    • SPEED: Download throughput in Mbps, or n/a.
    • LATENCY: Time to first byte (TTFB).
    • STATUS: ✓ for success or ✗ for failure.

    Note: Connection is verified via /cdn-cgi/trace. An endpoint can be successful (✓) even if SPEED is n/a. After Phase 2, pressing c copies healthy endpoints (e.g., 104.16.72.162:443) to the clipboard and saves them to ips.txt.

  2. How SenPai Scanner works: Scanning and Validation

    main

    SenPai Scanner operates in two main phases to find and verify working Cloudflare IPs:

    Phase 1: Connectivity Scan

    Probes candidate Cloudflare IPs.

    • Without a config URL: Uses a standard HTTP probe.
    • With a config URL: Automatically parses your VLESS or Trojan configuration to derive the SNI, host, WebSocket path, and port.
    • Random Mode: When a healthy hit is found, it triggers a neighbor scan to explore nearby addresses in the same Cloudflare block.

    Phase 2: Xray Validation (Optional)

    Launches an embedded xray instance to test the best hits from Phase 1 end-to-end using your actual VLESS/Trojan configuration. It provides details on:

    • Endpoint
    • Transport type
    • Download speed
    • Latency (TTFB)
    • Pass/fail status

    Managing Results

    • Copy to Clipboard: Press c when a scan finishes to copy IP:port endpoints.
    • Save to File: Results are automatically saved to ips.txt in the current working directory (or next to the binary).

  3. How SenPai Scanner works

    main

    SenPai Scanner probes Cloudflare edge IPs to find working endpoints for VLESS or Trojan configurations. The scanning process occurs in two distinct phases:

    1. Phase 1 — Connection Scan: Probes Cloudflare IP candidates. If no configuration URL is provided, it uses standard HTTP. If a URL is provided, it extracts the SNI, host, WebSocket path, and port from the link. In Random mode, any healthy IP automatically triggers a Neighbor Scan, checking nearby addresses within the same Cloudflare block.
    2. Phase 2 — xray Validation (Optional): Launches an internal xray instance to perform end-to-end testing of the best results from Phase 1 using your actual VLESS or Trojan configuration. The output includes the endpoint, transport type, download speed, latency (TTFB), and pass/fail status.

    After completion, pressing c copies healthy endpoints to the clipboard and saves them to ips.txt.

  4. Compare Desktop TUI and Android App features

    main

    SenPai Scanner is available as a Desktop TUI (Terminal User Interface) and an Android App. They have different capabilities:

    FeatureDesktop TUIAndroid App
    Persistent Settings + Retry Last Scan✓— (Session only)
    Live results file✓—
    Phase 1 only (without URL)✓✓
    Neighbor scanning (Random)✓✓
    CIDR support in ips.txt✓Only simple IPs
    Save to ips.txt✓Clipboard only

    Android UI Sections:

    • Home: Statistics cards (Tested, In-Flight, Healthy, Failed), IP list, single/group copy.
    • Settings: Source, Count, Workers, Timeout, Ports, Config URL, Top N.
    • FAB: START SCAN / STOP SCAN buttons.
    • Info: App info, version, GitHub/Telegram links.

  5. Install SenPai Scanner on Linux or macOS

    main

    You can install the stable release or a pre-release version using the provided installation script via curl. This will download and set up the appropriate binary for your system.

    Stable Release:

    curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash

    Pre-release:

    curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash -s -- --prerelease
    # stable release
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash

# pre-release
curl -fsSL https://github.com/MatinSenPai/SenPaiScanner/raw/refs/heads/main/install.sh | bash -s -- --prerelease

  6. Use the `ips.txt` file for scanning (From File)

    main

    You can provide a list of IPs to scan by placing a file named ips.txt next to the executable or in your current working directory. The scanner supports several line formats:

    Line TypeExampleBehavior
    Simple IPv4104.16.72.162Loaded directly
    CSV104.16.72.162,noteThe first column is read
    Comment / Empty# my listIgnored
    Small CIDR (≤256 hosts)104.16.72.160/29Fully expanded
    Large CIDR104.16.0.0/16Random sample up to 256 IPs
    Invalid CIDRnot-a-cidr/99Error and scan stops

    Note: IPv6 lines are ignored.

    Recommended Workflow: Run a Random scan $\rightarrow$ press c to save results to ips.txt $\rightarrow$ use the From File mode to test that specific list against more ports.

  7. Install SenPai Scanner on Windows via PowerShell

    main

    Use the following PowerShell command to download the latest senpaiscanner-windows-amd64.exe from GitHub releases and save it as senpaiscanner.exe.

    $r = Invoke-RestMethod https://api.github.com/repos/matinsenpai/senpaiscanner/releases/latest
$url = ($r.assets | Where-Object name -eq "senpaiscanner-windows-amd64.exe").browser_download_url
Invoke-WebRequest $url -OutFile senpaiscanner.exe

  8. Install SenPai Scanner on Windows

    main

    Use PowerShell to download and save the latest senpaiscanner-windows-amd64.exe executable.

    $r = Invoke-RestMethod https://api.github.com/repos/matinsenpai/senpaiscanner/releases/latest
$url = ($r.assets | Where-Object name -eq "senpaiscanner-windows-amd64.exe").browser_download_url
Invoke-WebRequest $url -OutFile senpaiscanner.exe

  9. Configure Scan Parameters (Find Working IPs)

    main

    The scanning process is configured in two steps within the TUI.

    Step 1: Main Parameters

    • Source: Choose Random (random IPv4 Cloudflare range) or From File (uses a list from ips.txt).
    • Count: Number of IPs to probe in Phase 1 (e.g., 1,000, 5,000, 20,000, or Custom).
    • Workers: Number of parallel probers (e.g., 50, 100, 200, or Custom). 50 is recommended for weaker networks.
    • Timeout: Timeout per probe (e.g., 2s, 3s, 5s, or Custom).
    • Ports: Select ports to test (e.g., 443, 8443, 2053, 2083, 2087, 2096, or Config). Use Space or Enter to toggle ports.

    Step 2: Optional Configuration

    • Config: Paste a vless:// or trojan:// URL. If left empty, only Phase 1 runs. If a URL is provided, Phase 2 (xray validation) is enabled.
    • Top N: Number of Phase 1 results to pass to Phase 2 for validation (e.g., 10, 25, 50, 100, All, or Custom).

  10. Build SenPai Scanner from source

    main

    Desktop (Linux/macOS/Windows)

    Linux/macOS:

    git clone https://github.com/matinsenpai/senpaiscanner.git
cd senpaiscanner
make build          # Build for current platform
make build-all      # Build for all platforms (outputs to dist/)
make test           # Run tests
make install        # Install to $GOPATH/bin

    Windows (Cross-compile via PowerShell):

    powershell -ExecutionPolicy Bypass -File build.ps1
# Optional: -Version "0.6.0"

    Android

    1. Build Go mobile library:
    cd android
./build_go_mobile.sh        # Linux / macOS
build_go_mobile.bat         # Windows
    1. Build APK:
    ./gradlew :app:assembleDebug
./gradlew :app:assembleRelease   # Requires a keystore
    git clone https://github.com/matinsenpai/senpaiscanner.git
cd senpaiscanner
make build

  11. Navigate the SenPai Scanner TUI

    main

    The Terminal User Interface (TUI) is controlled via keyboard shortcuts:

    KeyAction
    ↑ / ↓ or k / jMove between rows
    ← / → or h / lMove between options in a row
    EnterSelect / Confirm / Start scan
    EscGo back
    qQuit menu; during scan: Cancel or return after completion
    Space or EnterToggle port selection (when in Ports menu)
    Ctrl+A / Ctrl+EMove cursor to start/end of line (in Config URL row)

  12. Use SenPai Scanner TUI Navigation and Shortcuts

    main

    The SenPai Scanner uses an interactive Terminal User Interface (TUI).

    Navigation:

    • Use Arrow Keys and Enter to navigate the menu.
    • In Termux, you can also use k / j / h / l for menu navigation.

    Key Actions:

    • c: Copy working IP:port endpoints to the clipboard and save them to ips.txt.
    • Retry Last Scan: Use this option on the home screen to repeat your previous scan with the same configuration.

    Termux Specifics:

    • Pasting Config: Long-press in Termux to paste a URL. For better clipboard support, run pkg install termux-api.
    • Prevent Sleep: Run termux-wake-lock (requires termux-api) to prevent the device from sleeping during long scans.
    • Config Location: Settings are stored at ~/.config/senpaiscanner/config.json and enable the 'Retry Last Scan' feature.