usque

🥚➡️🍏🍎

Usque is an open-source reimplementation of the Cloudflare WARP client's MASQUE mode. It leverages the Connnect-IP (RFC 9484) protocol and comes with many operation modes including a native tunnel (currently Linux only), a SOCKS5 proxy, and a HTTP proxy.

usque - 🥚➡️🍏🍎

Installation

You can download the latest release from the releases page. For now, Android (arm64), Linux (armv5, armv6, armv7, arm64, amd64), Windows (arm64, amd64) and Darwin (arm64, amd64) binaries are provided. However only the Linux amd64 binary was tested. If you have a different platform, you can build from source.

Extract the archive and you will find a binary named usque in the root directory. You can move this binary to a directory in your PATH to make it accessible from anywhere.

Building from source

Since the tool is written in Go, it should be rather trivial.

Ensure that you have Go installed on your system. You can download it from here. At least Go 1.24.1 is required.
Clone this repository and switch to the project's root directory
Build the project using the following command:

CGO_ENABLED=0 go build -ldflags="-s -w" .

And that will produce an usque binary in the current directory.

If you would rather cross compile, set the GOOS and GOARCH environment variables accordingly. For example, to build for Windows on a Linux system:

GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" .

Docker

You can deploy the tool using Docker. Dockerfile is provided in the repository. To build the image, run:

docker build -t usque:latest .

Example usage (spawns a SOCKS proxy and exposes it on port 1080):

docker run -it --rm -p 1080:1080 usque:latest socks

Usage

$ ./usque --help
An unofficial Cloudflare Warp CLI that uses the MASQUE protocol and exposes the tunnel as various different services.

Usage:
  usque [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  enroll      Enrolls a MASQUE private key and switches mode
  help        Help about any command
  http-proxy  Expose Warp as an HTTP proxy with CONNECT support
  nativetun   Expose Warp as a native TUN device
  portfw      Forward ports through a MASQUE tunnel
  register    Register a new client and enroll a device key
  socks       Expose Warp as a SOCKS5 proxy

Flags:
  -c, --config string   config file (default is config.json) (default "config.json")
  -h, --help            help for usque

Use "usque [command] --help" for more information about a command.

Before doing anything, you need to register.

Registration

There is a handy (though not too feature-rich) register subcommand that creates a fresh Warp account ready to use. It also takes care of device registration and MASQUE device enrollment. Call this once and it will create a working configuration for future use in modules.

A simple example would be:

$ ./usque register

[!TIP] If you want to specify a name for the device, you may do so by specifying -n <device-name>.

[!TIP] If you want to register with ZeroTrust, you need to obtain the team token and do so by specifying --jwt <team-token>.

Visit https://<team-domain>/warp and complete the authentication process.

Obtain the team token from the success page's source code, or execute the following command in the browser console: console.log(document.querySelector("meta[http-equiv='refresh']").content.split("=")[2]).

If you didn't get rate-limited or any other error, you should see a Successful registration message and a working config. In case of certain issues such as rate limiting, you may need to wait a bit and try again.

Enrolling

While the registration command also handles device enrollment, in some cases, you may want to re-enroll the old key found in the config. This is useful when migrating from one device to another while the server still has the old client key enrolled. Or if your account had WireGuard enabled and you want to switch to MASQUE.

[!NOTE] This command refreshes your config with data downloaded from Cloudflare servers, so make sure you have backups.

[!TIP] When using ZeroTrust this command can update the config with the newly assigned IPv4 and IPv6 addresses. This is useful, because IPv6 doesn't seem to work there if the IPv6 in config isn't up to date. Personal WARP doesn't seem to be affected by this.

$ ./usque enroll

Native Tunnel Mode (for Advanced Users, Linux and Windows only!)

The native tunnel is probably the most efficient mode of operation (as of now).

On Linux

It requires the TUN device to be available on the system. This means your kernel must support loading the tun.ko module. iproute2 is also a requirement. While it is still userspace, traffic is directly injected into the kernel's network stack, therefore you will see a real network interface and you will be able to tunnel any IP (Layer 3) traffic that WARP supports. Since it creates a real network interface and also attempts to set IP addresses, it will most likely require root privileges.

On Windows

It requires the wintun.dll file to be present in the same directory as the usque.exe binary. Then it will take care of bringing up the interface and setting the IP addresses. Normally this also requires administrative privileges.

To bring up a native tunnel, execute:

$ sudo ./usque nativetun

Unless otherwise specified, you should see a tun0 (or tun1, tun2, etc.) interface appear on Linux. On Windows, the interface is typically named usque. If you didn't disable IPv4 and IPv6 inside the tunnel using cli flags (on Linux), you should also see the IPv4 and IPv6 address pre-assigned to this interface. This should be enough for applications that can route traffic through a specific network interface to function. For example ping:

$ ping -I tun0 1.1

Or curl:

$ curl --interface tun0 https://cloudflare.com/cdn-cgi/trace

Should just work. However the tool doesn't set any routes. If you need that, you have to do that manually. For example, to route all traffic to the tunnel, you need to make sure that the address used for tunnel communication is routed to your regular network interface. For that, open the config.json and check the endpoint address. If you plan to connect to the Cloudflare endpoint using IPv4, you will most likely see this:

"endpoint_v4": "162.159.198.1"

Remember that for the next steps.

Routes on Linux

Assuming your regular network interface is eth0 and your gateway address is 192.168.1.1, you can add a route like this:

$ sudo ip route add 162.159.198.1/32 via 192.168.1.1 dev eth0

After that, you can add a default route to the tun0 interface for both IPv4 and IPv6:

$ sudo ip route add default dev tun0 && sudo ip -6 route add default dev tun0

Routes on Windows

First, determine the interface index for your regular network adapter by running:

route print

Look under the Interface List for the correct index number.

Before adding default routes, determine the gateway for your tunnel interface by running:

ipconfig

Look for the adapter named usque (or whatever name you have for your tunnel interface) and note its gateway address.

Assuming:

Tunnel endpoint: 162.159.198.1
Gateway: 192.168.1.1
Interface index: 12
Tunnel interface: usque (replace with the actual name or index of your tunnel interface)

Run the following commands in an elevated Command Prompt (Run as Administrator):

route add 162.159.198.1 mask 255.255.255.255 192.168.1.1 metric 1 if 12

Then add default routes to route all traffic through the tunnel:

route add 0.0.0.0 mask 0.0.0.0 [TUNNEL_GATEWAY] metric 1 if [TUN_INTERFACE_INDEX]
route add ::/0 [TUNNEL_GATEWAY] metric 1 if [TUN_INTERFACE_INDEX]

[!NOTE] Replace [TUNNEL_GATEWAY] and `[TUN_INTER

Usque

Install / Use

README