wiretap

In this diagram, the Client has generated and installed WireGuard configuration files that will route traffic destined for 10.0.0.0/24 through a WireGuard interface. Wiretap is then deployed to the Server with a configuration that connects to the Client as a WireGuard peer. The Client can then interact with local network resources as if on the same network as the Server, and optionally chain additional Servers to reach new networks. Access to the Wiretap network can also be shared with other Clients.

Table of Contents

• Terminology and Requirements
  • Client System Requirements
  • Server System Requirements
  • Environment Requirements
• Quick Start
• Installation
• How it Works
• Usage
  • Configure
    • Outbound Connections
    • Simple Mode
  • Serve
  • Status
  • Add Server (Optional)
  • Add Client (Optional)
  • Expose (Port Forwarding)
    • List
    • Remove
• Features
• Demo
• Experimental
  • Localhost Server Access
  • TCP Tunneling
  • Add Clients To Any Server

Terminology and Requirements

A Wiretap Server is any machine where a Wiretap binary is running the serve command. Servers receive and relay network traffic on behalf of Wiretap Clients, acting like a VPN "exit node."

A Wiretap Client is any machine running the Wireguard configurations necessary to send and receive network traffic through a Wiretap Server. It functions much like a client in a VPN connection. Clients are also able to reconfigure parts of the Wiretap network dynamically using the Wiretap binary.

[!IMPORTANT] Unlike the typical use of "client" and "server" terms in networking, Wiretap's Client and Server terms have nothing to do with which machine listens for or initiates the initial connection.

Client System Requirements

• WireGuard installed - https://www.wireguard.com/install/
• Privileged access necessary to configure WireGuard interfaces (usually root/admin access)

Server System Requirements

• Ability to get the Wiretap binary onto the Server system, and run it

Environment Requirements

• Bidirectional UDP communication between Server and Client on one port. Any firewalls between them must allow at least one machine to initiate a UDP connection to the other.
  • The machine receiving the initial connection (the Client by default) must be able to listen for UDP connections on a port that the initiating machine can connect to.

[!NOTE] By default the Server initiates the handshake to the Client because the Server is more likely to have outbound UDP allowed through a firewall than inbound UDP, but the reverse is easily configurable with Outbound Connections

While not ideal, Wiretap can work with TCP instead of UDP. See the experimental TCP Tunneling section for more info.

Quick Start

1. Download binaries from the releases page, one for your Client machine and one for your Server machine (if different os/arch). Copy the Wiretap binary onto the server
2. On the Client, run ./wiretap configure --endpoint : --routes with the appropriate arguments
3. Copy the server command output that best suits the Server OS and run it on the Server machine
4. On the Client, run sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf create the associated Wireguard interfaces
5. Confirm the handshake completed for both configs by running sudo wg show on the Client
6. (Optional) Add more Servers and Clients as needed with the wiretap add command

See the Usage section for more details.

Installation

No installation of Wiretap is required. Just grab a binary from the releases page. You may need two different binaries if the OS/ARCH are different on the Client and Server machines.

If you want to compile it yourself or can't find the OS/ARCH you're looking for, install the latest Go from https://go.dev/dl/ and use the provided Makefile.

How it Works

[!TIP] For a more detailed explanation of Wiretap's networking model, see the How it Works page in the Wiki. That information can be very helpful when trying to troubleshoot connection issues.

Traditional VPN server software can't be installed by unprivileged users because VPNs rely on dangerous operations like changing network routes and working with raw packets.

Wiretap bypasses this requirement by rerouting traffic to a user-space TCP/IP network stack, where a listener accepts connections on behalf of the true destination. Then it creates a new connection to the true destination (via the native network stack) and copies data between the connections, effectively connecting the Client to the destination. This is similar to how https://github.com/sshuttle/sshuttle and https://github.com/nicocha30/ligolo-ng work, but relies on WireGuard as the tunneling mechanism rather than SSH or TLS.

To build secure and scalable tunnels across multiple hops, each node in the Wiretap network has two interfaces: Relay and E2EE (End-to-End Encrypted). The Relay interfaces simply relay packets between nodes, but cannot see the plaintext. When a Relay node sees a packet that does not match routing rules, it forwards it to its own E2EE interface where the contents can be decrypted by only that interface. This means there are two layers of WireGuard encapsulation (encryption) between any two nodes.

Usage

./wiretap --help --show-hidden

Usage:
  wiretap [flags]
  wiretap [command]

Available Commands:
  add         Add peer to wiretap
  configure   Build wireguard config
  expose      Expose local services to servers
  help        Help about any command
  ping        Ping wiretap server API
  serve       Listen and proxy traffic into target network
  status      Show peer layout

Flags:
  -h, --help          help for wiretap
  -H, --show-hidden   show hidden flag options
  -v, --version       version for wiretap

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

The following commands are documented in this section:

• configure
• serve
• status
• add server
• add client
• expose

Get help for any command by adding the -h flag to it.

[!TIP] Some deprecated and less-common flags are hidden from the standard help output. Add the -H flag as well to see them.

Configure

On the Client machine, run Wiretap's configure command to generate starting config files:

./wiretap configure --endpoint : --routes 

• --endpoint tells the Server machine how to connect to the Client machine's Relay interface (the E2EE interfaces already know how to talk to each other if the Relay interfaces are working)
• --routes is the equivalent of WireGuard's AllowedIPs setting. This tells the Client to route traffic that matches these IP ranges through Wiretap.

[!IMPORTANT] By default the Client listening port will be the same port specified in the --endpoint IP:port. This can be overwritten using the --port argument. If creating an outbound connection, the default Server listening port will be the same port specified in the --outbound-endpoint IP:port unless overwritten with the --sport argument. Both ports otherwise have a default of 51820.

Following the example in the diagram:

./wiretap configure --endpoint 7.3.3.1:1337 --routes 10.0.0.0/24

---

Click to view output

…

---

[!NOTE] The 51821 ListenPort in wiretap.conf needs to be available for use on the Client, but does NOT need to be accessible to the Server over real-world networks. See the How It Works section for details. Use --simple in the configure command if your setup requires a single interface on the Client. The Server will auto-detect that configuration.

Install the resulting wiretap_relay.conf and wiretap.conf configs files into WireGuard on the Client:

• If you have wg-quick installed, run sudo wg-quick up ./wiretap_relay.conf && sudo wg-quick up ./wiretap.conf
• If using a GUI, select the menu option similar to Import Tunnel(s) From File

[!TIP] You can modify the AllowedIPs in the wiretap.conf file any time after generating the config files, just reload the config file with wg-quick down ./wiretap.conf && wg-quick up ./wiretap.conf (or re-import them into the GUI) after making the change. No changes are needed on the Server to update them.

Don't forget to disable or remove the tunnels when you're done (e.g., sudo wg-quick down ./wiretap.conf && sudo wg-quick down ./wiretap_relay.conf)

Outbound Connections

You can use the --outbound-endpoint flag to configure the Client to Initiate the UDP connection to the Server. If you do, the --outbound-endpoint value will instead be used to tell the Client where to connect to the Server, and the --sport value (explicit or implicit) will configure the Server's listening port.

In this case the Client will listen on 51820 in case other Servers need to be added using the default Inbound mode, but this can be changed by passing a value to the --port flag when running the configure command.

Simple Mode

While not recommended, you can add the --simple flag to configure Wiretap as a more traditional one-Client-and-one-Server VPN. Most of Wiretap's dynamic configuration features (any Wiretap commands you would run after establishing the initial connection) will be unavailable in this mode.

Serve

On the remote machine, upload the Wiretap binary and then run one of the commands from the output of configure to start Wiretap in Server mode:

$env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $env:WIRETAP_RELAY_INTERFACE_PORT="51820"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc="; $env:WIRETAP_RELAY_PEER_ENDPOINT="1.3.3.7:1337"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg="; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve

There are two other ways to pass arguments to the Server:

1. With the generated Server config file: -f wiretap_server.conf
2. The legacy method of passing command line arguments (--endpoint 7.3.3.1:1337 ...). Be aware that this method exposes the arguments to other users on the system. A compromised private key can be used to connect to the Client as a peer and/or decrypt traffic

[!NOTE] The wiretap_server.conf file uses a notation unique to Wiretap. It cannot be used to start a Wireguard server with wg-quick or other generic Wireguard tools.

Confirm that the Relay interfaces on the Client and Server have successfully completed a handshake. The Client should see successful handshakes in whatever WireGuard interface is running. If using the command-line tools, check with sudo wg show. By default the E2EE handshake will not occur until the Client sends data, so you may need to attempt to use the connection (e.g. ping an IP in the associated --routes) to trigger the handshake process.

Now the Client should be able to interact with the routes specified in the configure command!

Status

Once the client configs have been imported and Wireguard is started,