<div align="center">

<img align="center" src="media/wiretap_logo.png" width="20%"> Wiretap

Wiretap is a transparent, VPN-like proxy server that tunnels traffic via WireGuard and requires no special privileges to run.

</div>

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.

<div align="center">

(Static Version)

</div>

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 <IP>:<port> --routes <CIDRs> 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.

<div align="center">

(Click image to view enlarged version)

</div>

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

<div align="center">

</div>

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

./wiretap configure --endpoint <IP>:<port> --routes <CIDRs>

• --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

---

<details> <summary>Click to view output</summary>

Configurations successfully generated.
Import the two configs into WireGuard locally and pass the arguments below to Wiretap on the remote machine.

config: wiretap_relay.conf
────────────────────────────────
[Interface]
PrivateKey = cGsJkcVIajZW7kfN5SMwijmMx59ke7FZ+qdZOcsNDE0=
Address = 172.16.0.1/32
Address = fd:16::1/128
ListenPort = 1337

[Peer]
PublicKey = kMj7HwfYYFO/XEHNFK2kz9cBd7vTHk63fhygyuYLMzI=
AllowedIPs = 172.17.0.0/24,fd:17::/48
────────────────────────────────

config: wiretap.conf
────────────────────────────────
[Interface]
PrivateKey = YCTRVwB4xOEcBtifVmhjMhRYL7+DOlDP5VdHZGclZGg=
Address = 172.19.0.1/32
Address = fd:19::1/128
ListenPort = 51821
MTU = 1340

[Peer]
PublicKey = 3ipWthpJzqVo5wcb1TSDS1M8YOiBQYBPmbj3mVD/5Fg=
AllowedIPs = 10.0.0.0/24,::2/128
Endpoint = 172.17.0.2:51821
────────────────────────────────

server config: wiretap_server.conf

server command:
POSIX Shell:  WIRETAP_RELAY_INTERFACE_PRIVATEKEY=WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y= WIRETAP_RELAY_INTERFACE_PORT=51820 WIRETAP_RELAY_PEER_PUBLICKEY=Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc= WIRETAP_RELAY_PEER_ENDPOINT=7.3.3.1:1337 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg= WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5