{"id":30695953,"url":"https://github.com/ircfspace/masque-plus","last_synced_at":"2025-10-13T21:03:20.748Z","repository":{"id":312158167,"uuid":"1046552773","full_name":"ircfspace/masque-plus","owner":"ircfspace","description":"A simple Go launcher for usque that handles registration, configuration, and running a SOCKS proxy. Designed for Cloudflare MASQUE protocol usage.","archived":false,"fork":false,"pushed_at":"2025-09-06T07:23:02.000Z","size":143,"stargazers_count":68,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-06T07:24:57.072Z","etag":null,"topics":["android","anticensorship","cloudflare","go","linux","mac","masque","warp","windows"],"latest_commit_sha":null,"homepage":"https://github.com/ircfspace/masque-plus/releases","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ircfspace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-28T21:21:57.000Z","updated_at":"2025-09-06T07:23:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"3a26ebed-6158-42b9-b134-c967b7ec907c","html_url":"https://github.com/ircfspace/masque-plus","commit_stats":null,"previous_names":["ircfspace/masque-plus"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/ircfspace/masque-plus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ircfspace%2Fmasque-plus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ircfspace%2Fmasque-plus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ircfspace%2Fmasque-plus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ircfspace%2Fmasque-plus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ircfspace","download_url":"https://codeload.github.com/ircfspace/masque-plus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ircfspace%2Fmasque-plus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016885,"owners_count":26085912,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","anticensorship","cloudflare","go","linux","mac","masque","warp","windows"],"created_at":"2025-09-02T07:11:41.001Z","updated_at":"2025-10-13T21:03:20.743Z","avatar_url":"https://github.com/ircfspace.png","language":"Go","readme":"# Masque-Plus\n\nA simple Go launcher for `usque` that handles registration, configuration, and running a SOCKS proxy.  \nDesigned for **Cloudflare MASQUE protocol** usage.\n\nCross-platform: works on **Linux, macOS, Windows, and Android**. The binaries are automatically built via **GitHub Actions**.\n\n![masque-plus](masque-plus.jpg)\n\n## Features\n\n- Automatically registers `usque` if config is missing or renewal is requested.\n- Supports both **IPv4** and **IPv6** endpoints, including domain resolution.\n- Starts a local SOCKS proxy on a specified IP and port.\n- Handles private key errors by re-registering automatically.\n- Endpoint scanner to auto-select a working IP from CIDR ranges.\n- Customizable MASQUE parameters like SNI, port, DNS servers, MTU, keepalive, and proxy authentication.\n- Warp status check during scanning to ensure \"warp=on\".\n- Cross-platform support for Linux, macOS, Windows, and Android.\n\n## Installation\n\nDownload the latest release for your system architecture from the [Releases page](https://github.com/ircfspace/masque-plus/releases/latest).\n\nPlace the `usque` binary in the same folder as this launcher (`Masque-Plus.exe` for Windows, or `Masque-Plus` for Linux/macOS).\n\n## Usage\n\n```bash\n./Masque-Plus --endpoint \u003chost:port\u003e [--bind \u003cIP:Port\u003e] [--renew] [--scan] [-4|-6] [other flags]\n```\n\n### Core Flags\n\n| Flag                       | Description                                                                                                                                                             | Default                                                    |\n| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| `--bind`                   | IP and port to bind the local SOCKS proxy. Format: `IP:Port`.                                                                                                           | 127.0.0.1:1080                                             |\n| `--endpoint`               | Required unless `--scan` is used. The MASQUE server endpoint to connect. Supports IPv4/IPv6/domains (e.g., 162.159.198.2:443, [2606:4700:103::2]:443, example.com:443). | -                                                          |\n| `--scan`                   | Auto-select an endpoint by scanning and randomly choosing a suitable IP (respecting `-4`/`-6`).                                                                         | false                                                      |\n| `-4`                       | Force IPv4 endpoint selection (works with `--scan` or provided `--endpoint`).                                                                                           | -                                                          |\n| `-6`                       | Force IPv6 endpoint selection (works with `--scan` or provided `--endpoint`).                                                                                           | -                                                          |\n| `--connect-timeout`        | Overall timeout for the final connect/process to be up. Accepts Go durations (e.g., 10s, 1m).                                                                           | 15m                                                        |\n| `--renew`                  | Force renewal of the configuration even if `config.json` already exists.                                                                                                | false                                                      |\n| `--range4`                 | Comma-separated IPv4 CIDRs to scan (with `--scan`).                                                                                                                     | 162.159.192.0/24,\u003cbr\u003e162.159.197.0/24,\u003cbr\u003e162.159.198.0/24 |\n| `--range6`                 | Comma-separated IPv6 CIDRs to scan (with `--scan`).                                                                                                                     | 2606:4700:103::/64                                         |\n| `--ping`                   | Ping each candidate before connect (QUIC probe).                                                                                                                        | true                                                       |\n| `--scan-timeout`           | Per-endpoint scan timeout (dial+handshake).                                                                                                                             | 5s                                                         |\n| `--scan-max`               | Maximum number of endpoints to try during scan.                                                                                                                         | 30                                                         |\n| `--scan-verbose-child`     | Print MASQUE child process logs during scan.                                                                                                                            | false                                                      |\n| `--scan-tunnel-fail-limit` | Number of 'Failed to connect tunnel' occurrences before skipping an endpoint.                                                                                           | 2                                                          |\n| `--scan-ordered`           | Scan candidates in CIDR order (disable shuffling).                                                                                                                      | false                                                      |\n| `--version`                | Show the current version of the program.                                                                                                                                |                                                            |\n\n### Usque-Specific Flags (Passed Directly to `usque socks`)\n\n| Flag                    | Description                                                                                      | Default                                |\n| ----------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------- |\n| `--connect-port`        | Used port for MASQUE connection (overrides endpoint port if specified).                          | `443`                                  |\n| `--dns`                 | Comma-separated DNS servers to use (e.g., `8.8.8.8,1.1.1.1`). Validates IPs and ignores invalid. | -                                      |\n| `--dns-timeout`         | Timeout for DNS queries.                                                                         | `2s`                                   |\n| `--initial-packet-size` | Initial packet size for MASQUE connection.                                                       | `1242`                                 |\n| `--keepalive-period`    | Keepalive period for MASQUE connection.                                                          | `30s`                                  |\n| `--local-dns`           | Don't use the tunnel for DNS queries.                                                            | `false`                                |\n| `--mtu`                 | MTU for MASQUE connection.                                                                       | `1280`                                 |\n| `--no-tunnel-ipv4`      | Disable IPv4 inside the MASQUE tunnel.                                                           | `false`                                |\n| `--no-tunnel-ipv6`      | Disable IPv6 inside the MASQUE tunnel.                                                           | `false`                                |\n| `--password`            | Password for proxy authentication (requires `--username`).                                       | -                                      |\n| `--username`            | Username for proxy authentication (requires `--password`).                                       | -                                      |\n| `--reconnect-delay`     | Delay between reconnect attempts.                                                                | `1s`                                   |\n| `--sni`                 | SNI address to use for MASQUE connection (defaults to domain if endpoint is a domain).           | `consumer-masque.cloudflareclient.com` |\n| `--ipv6`                | Use IPv6 for MASQUE connection (overrides to match endpoint if mismatch).                        | `false`                                |\n\n### Examples\n\n```bash\n# Connect to a specific IP endpoint and start SOCKS proxy\n./Masque-Plus --endpoint 162.159.198.2:443\n\n# Use a domain endpoint with custom SNI and port\n./Masque-Plus --endpoint example.com:8443 --sni example.com --connect-port 8443 --bind 127.0.0.1:8086\n\n# Force renewal and use custom DNS servers\n./Masque-Plus --endpoint 162.159.198.2:443 --renew --dns 8.8.8.8,1.1.1.1\n\n# Scan for a working IPv4 endpoint with verbose logs\n./Masque-Plus --scan -4 --scan-verbose-child --sni consumer-masque.cloudflareclient.com\n\n# Enable proxy authentication and disable IPv4 in tunnel\n./Masque-Plus --endpoint [2606:4700:103::2]:443 --username test --password secret --no-tunnel-ipv4\n\n# Custom scan ranges and max attempts\n./Masque-Plus --scan --range4 162.159.192.0/24,162.159.197.0/24 --scan-max 50\n```\n\n## TODO\n\n✅ Add an internal endpoint scanner to automatically search and suggest optimal MASQUE endpoints.\u003cbr /\u003e\n⬜ Planning to add the `MasqueInMasque` method to get an IP from a different location.\n\n## Notes\n\n- Make sure the `usque` binary has execution permissions (`chmod +x usque` on Linux/macOS).\n- Configurations are saved in `config.json` in the same folder.\n- If a private key error occurs, the launcher will attempt to re-register `usque` automatically.\n- During scanning, endpoints are shuffled for randomness (unless `--scan-ordered`), and a Warp check is performed to ensure \"warp=on\".\n- Invalid DNS servers are logged and ignored.\n- If only one of `--username` or `--password` is provided, authentication is skipped with a warning.\n\n## For Developers\n\nTo build the binary locally (Windows example):\n\n```bash\ngo build -o masque-plus.exe\n```\n\n## Credits\n\n- This project uses [`usque`](https://github.com/Diniboy1123/usque) as the core MASQUE implementation.\n- MASQUE protocol and Cloudflare 1.1.1.1 inspired the functionality.\n- Development and code assistance were supported by ChatGPT.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fircfspace%2Fmasque-plus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fircfspace%2Fmasque-plus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fircfspace%2Fmasque-plus/lists"}