• Stars
    star
    847
  • Rank 53,812 (Top 2 %)
  • Language
    Go
  • License
    Other
  • Created almost 2 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

Wiretap

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

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 resources local to the server as if on the same network and chain additional servers to reach new networks. Access to the Wiretap network can also be shared with other clients.

Wiretap Diagram

Quick Start

  1. Download binaries from the releases page, one for your client machine and one for your server (if different os/arch)
  2. Run ./wiretap configure --port <port> --endpoint <socket> --routes <routes> with the appropriate arguments
  3. Import the resulting wiretap.conf and wiretap_relay.conf files into WireGuard on the client machine
  4. Copy and paste the server command output that best suits your target system into Wiretap on the server machine
  5. Add more servers and clients as needed with the add subcommand

Requirements

Client Systems

Server Systems

  • Bidirectional UDP access to client on one port. By default the server initiates the handshake to the client because it is more likely to have outbound UDP than inbound, but the reverse is easily configurable

While not ideal, Wiretap can still work with TCP instead of UDP. See the experimental TCP Tunneling section for a step-by-step guide.

Installation

Grab a binary from the releases page. You may want two 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 Go (>=1.20) from https://go.dev/dl/ and use the provided Makefile.

Usage

Configure

Wiretap Configure Arguments

On the client machine, run Wiretap in configure mode to build a config

./wiretap configure --port <port> --endpoint <socket> --routes <routes>
  • --port sets the listening port of the Client's Relay interface. It's set to 51820 by default. Note that the E2EE listening port does not need to be accessible to the Server
  • --endpoint tells the Server how to connect to the Client'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

Following the example in the diagram:

./wiretap configure --port 1337 --endpoint 1.3.3.7:1337 --routes 10.0.0.0/24
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_PEER_PUBLICKEY=Ta75SvIb2v2V8EDo6oE2Fvsys/CNlkzW+aPjxdY+Dlc= WIRETAP_RELAY_PEER_ENDPOINT=1.3.3.7:1337 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=GKzGBe3qS7JuLp0vMAErBW6lAewvmFowCIbcgwzComg= WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve
 PowerShell:  $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $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
Config File:  ./wiretap serve -f wiretap_server.conf

Note
Wiretap uses 2 WireGuard interfaces per node in order to safely and scalably chain together servers. This means your client will bind to more than one port, but only the Relay Interface port needs to be accessible by the Server. See the How It Works section for details. Use --simple if your setup requires a single interface on the client

Install the resulting config either by copying and pasting the output or by importing the new wiretap.conf and wiretap_relay.conf files into WireGuard:

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

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

Deploy

On the remote machine, upload the binary and then copy the command with the private and public keys to start Wiretap in server mode:

$env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="WDH8F6rSUZDyQFfEsRjWLCnapU254qrSAfpGyGs+N1Y="; $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 a config file: -f wiretap_server.conf
  2. The legacy method of passing command line arguments (--endpoint 1.3.3.7:1337 ...). Be aware that this method exposes 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

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 wg show. By default the E2EE handshake will not occur until the client sends data.

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

Add Server (Optional)

Wiretap Add Server Arguments

The add server subcommand is meant to extend the Wiretap network to reach new areas of a target network. One client and at least one server must be configured and deployed before adding another server. Servers can attach to any other server or the client itself.

Note
All servers must be deployed before adding additional clients

You can view the state of the network and see API addresses with ./wiretap status

./wiretap status
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Wiretap Network Status โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚client               โ”‚
  โ”‚                     โ”‚
  โ”‚  relay: Ta75SvIb... โ”‚
  โ”‚   e2ee: cXddDGWC... โ”‚
  โ”‚                     โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚server               โ”‚
  โ”‚  relay: kMj7HwfY... โ”‚
  โ”‚   e2ee: 3ipWthpJ... โ”‚
  โ”‚                     โ”‚
  โ”‚    api: ::2         โ”‚
  โ”‚ routes: 10.0.0.0/24 โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

If you plan to attach a server directly to the client, the status command just confirms that everything is working as expected and the network layout is correct. If you want to attach a server to another server you must specify the API address in your add server command. In the example, we will want to attach to the server with API address ::2. This command will generate a configuration you can deploy to the new server (through environment variables or a config), just like with the configure command:

./wiretap add server --server-address ::2 --endpoint 10.0.0.2:51820 --routes 10.0.1.0/24
Configurations successfully generated.
Import the updated config(s) into WireGuard locally and pass the arguments below to Wiretap on the new remote server.

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

[Peer]
PublicKey = YOVI9nOvjOWTre0OVzrjx8qsYRgyuSLWndv28S2udiQ=
AllowedIPs = 10.0.1.0/24,::3/128
Endpoint = 172.17.0.3:51821
โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€

server config: wiretap_server_1.conf

POSIX Shell:  WIRETAP_RELAY_INTERFACE_PRIVATEKEY=sLERnxT2+VdwwcJOTUHK5fa5sIN7oJ1Jww9n42txrEQ= WIRETAP_RELAY_INTERFACE_IPV4=172.17.0.3 WIRETAP_RELAY_INTERFACE_IPV6=fd:17::3 WIRETAP_RELAY_PEER_PUBLICKEY=kMj7HwfYYFO/XEHNFK2kz9cBd7vTHk63fhygyuYLMzI= WIRETAP_RELAY_PEER_ALLOWED=172.16.0.0/16,fd:16::/40 WIRETAP_RELAY_PEER_ENDPOINT=10.0.0.2:51820 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=uF79x5X8q3Vd/ajWMR5XyDt/haahtpy5PkJj9b+OaUE= WIRETAP_E2EE_INTERFACE_API=::3 WIRETAP_E2EE_PEER_PUBLICKEY=cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM= WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve
 PowerShell:  $env:WIRETAP_RELAY_INTERFACE_PRIVATEKEY="sLERnxT2+VdwwcJOTUHK5fa5sIN7oJ1Jww9n42txrEQ="; $env:WIRETAP_RELAY_INTERFACE_IPV4="172.17.0.3"; $env:WIRETAP_RELAY_INTERFACE_IPV6="fd:17::3"; $env:WIRETAP_RELAY_PEER_PUBLICKEY="kMj7HwfYYFO/XEHNFK2kz9cBd7vTHk63fhygyuYLMzI="; $env:WIRETAP_RELAY_PEER_ALLOWED="172.16.0.0/16,fd:16::/40"; $env:WIRETAP_RELAY_PEER_ENDPOINT="10.0.0.2:51820"; $env:WIRETAP_E2EE_INTERFACE_PRIVATEKEY="uF79x5X8q3Vd/ajWMR5XyDt/haahtpy5PkJj9b+OaUE="; $env:WIRETAP_E2EE_INTERFACE_API="::3"; $env:WIRETAP_E2EE_PEER_PUBLICKEY="cXddDGWCzd5igux4FDv97XBsyLH0SRPehhTz3E2IXBM="; $env:WIRETAP_E2EE_PEER_ENDPOINT="172.16.0.1:51821"; .\wiretap.exe serve
Config File:  ./wiretap serve -f wiretap_server_1.conf

The client's E2EE configuration will be modified, so you need to reimport it. For example, wg-quick down ./wiretap.conf and wg-quick up ./wiretap.conf. If you are attaching a server directly to the client, the Relay interface will also need to be refreshed.

Now you can use any of the server command options to deploy Wiretap to the new server. It will then connect to the already existing server.

At this point the new routes should be usable! You can confirm that everything looks correct with wiretap status:

./wiretap status
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Wiretap Network Status โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚client               โ”‚
  โ”‚                     โ”‚
  โ”‚  relay: Ta75SvIb... โ”‚
  โ”‚   e2ee: cXddDGWC... โ”‚
  โ”‚                     โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚server               โ”‚
  โ”‚  relay: kMj7HwfY... โ”‚
  โ”‚   e2ee: 3ipWthpJ... โ”‚
  โ”‚                     โ”‚
  โ”‚    api: ::2         โ”‚
  โ”‚ routes: 10.0.0.0/24 โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚server               โ”‚
  โ”‚  relay: GMkUzfDy... โ”‚
  โ”‚   e2ee: YOVI9nOv... โ”‚
  โ”‚                     โ”‚
  โ”‚    api: ::3         โ”‚
  โ”‚ routes: 10.0.1.0/24 โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

Now the client can reach 10.0.0.0/24 and 10.0.1.0/24. From here you can attach more servers to any of the three nodes.

Add Client (Optional)

Wiretap Add Client Arguments

The add client subcommand can be used to share access to the Wiretap network with others.

Note
All servers must be deployed before adding additional clients

Adding a client is very similar to the other commands. It will generate a wiretap.conf and wiretap_relay.conf for sharing. Make sure that all of the first-hop servers (any server directly attached to the original client) can reach or be reached by the new client. Once you get the endpoint information from whoever will be running the new client run:

./wiretap add client --port 1337 --endpoint 1.3.3.8:1337
Configurations successfully generated.
Have a friend import these files into WireGuard

config: wiretap_relay_1.conf
โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
[Interface]
PrivateKey = UEgzp6zv8lNnpih31RfzKsz+BLyN5qNfh6PbCdF1Cmg=
Address = 172.16.0.2/32
Address = fd:16::2/128
ListenPort = 1337

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

config: wiretap_1.conf
โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
[Interface]
PrivateKey = 8AhL1kDjwBn/IoY4KLd5mMP4GQsyMYNsqYm3aM/bHnE=
Address = 172.19.0.2/32
Address = fd:19::2/128
ListenPort = 51821
MTU = 1340

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

[Peer]
PublicKey = YOVI9nOvjOWTre0OVzrjx8qsYRgyuSLWndv28S2udiQ=
AllowedIPs = 10.0.1.0/24,::3/128
Endpoint = 172.17.0.3:51821
โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€

Send these files and have the recipient import them into WireGuard to have access to everything in the Wiretap network! By default the routes (AllowedIPs) are copied over, but can be modified by the recipient as needed.

Port Forwarding

Warning
Port forwarding exposes services on your local machine to the remote network, use with caution

You can expose a service on the client by using the expose subcommand. For example, to allow remote systems to access port 80/tcp on your local machine, you could run:

./wiretap expose --local 80 --remote 8080

Now all Wiretap servers will be bound to port 8080/tcp and proxy connections to your services on port 80/tcp. By default this uses IPv6, so make sure any listening services support IPv6 as well. To configure Wiretap to only use IPv4, use the configure subcommand's --disable-ipv6 option.

To dynamically forward all ports using SOCKS5:

./wiretap expose --dynamic --remote 8080

All servers will spin up a SOCKS5 server on port 8080 and proxy traffic to your local machine and can be used like this:

curl -x socks5://<server-ip>:8080 http://<any-ip>:1337

The destination IP will be rewritten by the server so you can put any address.

List

Use ./wiretap expose list to see all forwarding rules currently configured.

Remove

Use ./wiretap remove with the same arguments used in expose to delete a rule. For example, to remove the SOCKS5 example above:

./wiretap expose remove --dynamic --remote 8080

How It Works

A traditional VPN 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 and copies data between the endpoint and the peer. 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 nodes 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 contents can be decrypted by only that interface. There are two layers of WireGuard encapsulation between any two nodes.

Wiretap E2EE Architecture

Help

./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
      --show-hidden   show hidden flag options
  -v, --version       version for wiretap

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

Features

  • Network
    • IPv4
    • IPv6
    • ICMPv4: Echo requests and replies
    • ICMPv6: Echo requests and replies
  • Transport
    • TCP
      • Transparent connections
      • RST response when port is unreachable
      • Reverse Port Forward
      • Reverse Socks5 Support
    • UDP
      • Transparent "connections"
      • ICMP Destination Unreachable when port is unreachable
      • Reverse Port Forward
  • Application
    • API internal to Wiretap for dynamic configuration
    • Chain servers together to tunnel traffic through an arbitrary number of machines
    • Add clients after deployment for multi-user support

Demo

The demo has four hosts and three networks for testing multi-hop/nested tunnels, but only the first target host is reached in the examples below.

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ client   โ”‚
โ”‚          โ”‚
โ”‚ 10.1.0.2 โ”‚
โ”‚ fd:1::2  โ”œโ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”‚ exposed network       โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”‚ 10.1.0.0/16,fd:1::/64 โ”‚
โ”‚ 10.1.0.3 โ”œโ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
โ”‚ fd:1::3  โ”‚
โ”‚          โ”‚
โ”‚ server   โ”‚
โ”‚          โ”‚
โ”‚ 10.2.0.3 โ”‚
โ”‚ fd:2::3  โ”œโ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”‚ target network        โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”‚ 10.2.0.0/16,fd:2::/64 โ”‚
โ”‚ 10.2.0.4 โ”œโ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
โ”‚ fd:2::4  โ”‚
โ”‚          โ”‚
โ”‚ target   โ”‚
โ”‚          โ”‚
โ”‚ 10.3.0.4 โ”‚
โ”‚ fd:3::4  โ”œโ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”‚ target2 network       โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”‚ 10.3.0.0/16,fd:3::/64 โ”‚
โ”‚ 10.3.0.5 โ”œโ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
โ”‚ fd:3::5  โ”‚
โ”‚          โ”‚
โ”‚ target2  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Video

wiretap_demo.mp4

Step-By-Step

You have unprivileged access to the server host and want to reach the target host from the client host using Wiretap.

Setup

Clone this repo.

Start the demo containers with:

docker compose up --build

Open new tabs for interactive sessions with the client and server machines:

docker exec -it wiretap-client-1 bash
docker exec -it wiretap-server-1 bash

Observe Network Limitations

The target network, and therefore the target host, is unreachable from the client machine. Both the server and target hosts are running a web service on port 80, so try interacting with each of the services from each of the hosts:

Accessing the server's web service from the client should work:

client$ curl http://10.1.0.3

Accessing the target web service from the client should not work, but doing the same thing from the server machine will:

# fails
client$ curl http://10.2.0.4
server$ curl http://10.2.0.4

Configure

Configure Wiretap from the client machine. Remember, --endpoint is how the server machine should reach the client and --routes determines which traffic is routed through Wiretap.

  • --endpoint needs to be the client address and the default WireGuard port: 10.1.0.2:51820
  • --routes needs to be the subnet of the target network: 10.2.0.0/16. But there is also an IPv6 subnet, so we should also put fd:2::/64. If you just wanted to route traffic to the target host, you could put 10.2.0.4/32 here instead
./wiretap configure --endpoint 10.1.0.2:51820 --routes 10.2.0.0/16,fd:2::/64

Install the newly created WireGuard configs with:

wg-quick up ./wiretap_relay.conf
wg-quick up ./wiretap.conf

Copy and paste the Wiretap arguments printed by the configure command into the server machine prompt. It should look like this:

WIRETAP_RELAY_INTERFACE_PRIVATEKEY=<key> WIRETAP_RELAY_PEER_PUBLICKEY=<key> WIRETAP_RELAY_PEER_ENDPOINT=10.1.0.2:51820 WIRETAP_E2EE_INTERFACE_PRIVATEKEY=<key> WIRETAP_E2EE_PEER_PUBLICKEY=<key> WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve

Test

The WireGuard handshake should be complete. Confirm with:

wg show

If the handshake was successful the client should be able to reach the target network transparently. Confirm by running the same test that failed before:

client$ curl http://10.2.0.4

That's it! Try scanning, pinging, and anything else you can think of (please submit an issue if you think something should work but doesn't!). Here are a few ideas:

  • HTTP
    • curl http://10.2.0.4
    • curl http://[fd:2::4]
  • Nmap
    • nmap 10.2.0.4 -v
    • nmap -6 fd:2::4 -v
  • ICMP
    • ping 10.2.0.4
    • ping fd:2::4
  • UDP
    • nmap -sU 10.2.0.4 -v
    • nmap -sU -6 fd:2::4 -v

Exercise

Try to reach the second target by adding another server! You should be able to successfully run curl http://10.3.0.5 from the client host if performed correctly. The status command should output something similar to:

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Wiretap Network Status โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚client               โ”‚
  โ”‚                     โ”‚
  โ”‚  relay: Ta75SvIb... โ”‚
  โ”‚   e2ee: cXddDGWC... โ”‚
  โ”‚                     โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚server               โ”‚
  โ”‚  relay: kMj7HwfY... โ”‚
  โ”‚   e2ee: 3ipWthpJ... โ”‚
  โ”‚                     โ”‚
  โ”‚    api: ::2         โ”‚
  โ”‚ routes: 10.2.0.0/16 โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
             โ”‚
  โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
  โ”‚server               โ”‚
  โ”‚  relay: GMkUzfDy... โ”‚
  โ”‚   e2ee: YOVI9nOv... โ”‚
  โ”‚                     โ”‚
  โ”‚    api: ::3         โ”‚
  โ”‚ routes: 10.3.0.0/16 โ”‚
  โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

Teardown

To bring down the WireGuard interfaces on the client machine, run:

wg-quick down ./wiretap_relay.conf
wg-quick down ./wiretap.conf

Experimental

TCP Tunneling

Note
Performance will suffer, only use TCP Tunneling as a last resort

If you have no outbound or inbound UDP access, you can still use Wiretap, but you'll need to tunnel WireGuard traffic through TCP. This should only be used as a last resort. From WireGuard's Known Limitations page:

TCP Mode

WireGuard explicitly does not support tunneling over TCP, due to the classically terrible network performance of tunneling TCP-over-TCP. Rather, transforming WireGuard's UDP packets into TCP is the job of an upper layer of obfuscation (see previous point), and can be accomplished by projects like udptunnel and udp2raw.

Another great tool that has similar cross-platform capabilities to Wiretap is Chisel. We can use chisel to forward a UDP port to the remote system over TCP. To use:

Run chisel server on the client system, specifying a TCP port you can reach from the server system:

./chisel server --port 8080

On the server system, forward the port with this command using the same TCP port you specified in the previous command and using the ListenPort you specified when configuring Wiretap (the default is 51820). The format is <localport>:0.0.0.0:<remoteport>/udp.

In this example, we're forwarding 51821/udp on the server to 51820 on the client:

./chisel client <endpoint address>:8080 51821:0.0.0.0:51820/udp

Finally, run Wiretap with the forwarded local port as your endpoint on the server system:

WIRETAP_RELAY_INTERFACE_PRIVATEKEY=<key> WIRETAP_RELAY_PEER_PUBLICKEY=<key> WIRETAP_E2EE_INTERFACE_PRIVATEKEY=<key> WIRETAP_E2EE_PEER_PUBLICKEY=<key> WIRETAP_E2EE_PEER_ENDPOINT=172.16.0.1:51821 ./wiretap serve --endpoint localhost:51821

More Repositories

1

toyplot

Interactive plotting for Python.
Jupyter Notebook
422
star
2

Albany

Sandia National Laboratories' Albany multiphysics code
C++
281
star
3

scot

Sandia Cyber Omni Tracker (SCOT)
JavaScript
237
star
4

qthreads

Lightweight locality-aware user-level threading runtime.
C
170
star
5

dr_robot

This tool can be used to enumerate the subdomains associated with a company by aggregating the results of multiple OSINT (Open Source Intelligence) tools.
Python
138
star
6

pyGSTi

A python implementation of Gate Set Tomography
Jupyter Notebook
134
star
7

seacas

The Sandia Engineering Analysis Code Access System (SEACAS) is a suite of preprocessing, postprocessing, translation, and utility applications supporting finite element analysis software using the Exodus database file format.
C
131
star
8

snl-quest

An open source, Python-based software platform for energy storage simulation and analysis developed by Sandia National Laboratories.
Python
128
star
9

InterSpec

spectral radiation analysis software
C++
120
star
10

omega_h

Simplex mesh adaptivity for HPC
C++
105
star
11

slycat

Web-based data science analysis and visualization platform.
JavaScript
75
star
12

pecos

Python package for performance monitoring of time series data
Python
64
star
13

gr-pdu_utils

GNU Radio PDU Utilities
C++
61
star
14

UQTk

Sandia Uncertainty Quantification Toolkit
Fortran
59
star
15

chama

Python package for sensor placement optimization
Python
57
star
16

bcnn

3D Bayesian Convolutional Neural Network (BCNN) for Credible Geometric Uncertainty. Code for the paper: https://arxiv.org/abs/1910.10793
Python
56
star
17

gr-fhss_utils

Bursty modem utilities
C++
56
star
18

Whetstone

Python
47
star
19

TChem

TChem - A Software Toolkit for the Analysis of Complex Kinetic Models
Jupyter Notebook
44
star
20

tracktable

Tracktable: moving object trajectory analysis in C++ and Python
C++
39
star
21

tbnn

This code implements the Tensor Basis Neural Network (TBNN) as described in Ling et al. (Journal of Fluid Mechanics, 2016).
Python
38
star
22

hyram

Python
38
star
23

reverse_argparse

A Python library to determine what exactly the user ran at the command line, along with default values, and any transformations that happened after parsing arguments.
Python
38
star
24

pyapprox

Python
37
star
25

Spitfire

Spitfire is a Python/C++ library for constructing tabulated chemistry models and solving differential equations.
Python
37
star
26

portals4

Portals is a low-level network API for high-performance networking on high-performance computing systems developed by Sandia National Laboratories, Intel Corporation, and the University of New Mexico. The Portals 4 Reference Implementation is a complete implementation of Portals 4, with transport over InfiniBand VERBS and UDP. Shared memory transport is available as an optimization, including Linux KNEM support. The Portals 4 reference implementation is supported on both modern 64 bit Linux and 64 bit Mac OS X. The reference implementation has been developed by Sandia National Laboratories, Intel Corporation, and System Fabric Works. For more information on the Portals 4 standard, please see the Portals 4 page.
C
34
star
27

cross-sim

CrossSim: accuracy simulation of analog in-memory computing
Python
33
star
28

NuMAD

Numerical Manufacturing And Design Tool (NuMAD) -- A design tool for wind and water turbine composite blades
MATLAB
33
star
29

Prove-It

A tool for proving and organizing general theorems using Python.
Jupyter Notebook
27
star
30

SpecUtils

A library for opening, manipulating, and exporting gamma spectral files
C++
26
star
31

optimism

Computational solid mechanics made easy with Jax
Python
26
star
32

spack-manager

A project and machine deployment model using Spack
Python
25
star
33

gr-timing_utils

GNU Radio Timing Utilties
C++
25
star
34

MATLAB_PV_LIB

MATLAB PV function library
HTML
24
star
35

lgrtk

Tool Kit for Lagrangian Grid Reconnection
C++
22
star
36

mac-sandbox

This is a malware analyzer for Mac OS X that extends the Cuckoo Sandbox project (https://cuckoosandbox.org/)
Python
22
star
37

gait

Zeek Extension to Collect Metadata for Profiling of Endpoints and Proxies
Zeek
21
star
38

n2a

An object-oriented language for modeling large-scale neural systems, along with an IDE for writing and simulating models.
Java
21
star
39

MEWS

Multi-scenario Extreme Weather Simulator (MEWS)
Python
20
star
40

spat

A graphical user interface for measuring and performing inter-active analysis of physical unclonable functions (PUFs)
Python
20
star
41

compadre

Compadre (Compatible Particle Discretization and Remap)
C++
20
star
42

pyttb

Python Tensor Toolbox
Python
19
star
43

poblano_toolbox

Nonlinear optimization for MATLAB.
MATLAB
19
star
44

pycheron

Pycheron - A python library for quality control of seismic data based on IRIS Mustang.
Python
18
star
45

MatMCNP

A utility code for generating material cards for MCNP
Python
18
star
46

Zoltan

Zoltan Dynamic Load Balancing and Graph Algorithm Toolkit -- Distribution site
C
18
star
47

pvOps

A set of documented functions for supporting operations research of photovoltaic energy systems.
Jupyter Notebook
18
star
48

verdict

verdict
C++
17
star
49

Chordly

Chordly is a javascript library that may be used to detect and act upon key sequences entered by a user.
JavaScript
17
star
50

SandiaDecay

Easy to use C++ library to calculate nuclear decays and emissions
C++
17
star
51

CACTUS

CACTUS (Code for Axial and Cross-flow TUrbine Simulation) is a turbine performance simulation code, based on a free wake vortex method, to study wind turbines and marine hydrokinetic (MHK) devices.
Fortran
17
star
52

sceptre-phenix

phenix is an orchestration tool and GUI for Sandia's minimega platform
JavaScript
17
star
53

Gulliver

Gulliver is a C# utility package and library engineered for the manipulation of arbitrary sized byte arrays accounting for appropriate endianness and jagged byte length.
C#
15
star
54

PyRIID

ML-based radioisotope identification and estimation from gamma spectra in Python.
Python
15
star
55

suncal

Suncal - Sandia PSL Uncertainty Calculator
Python
14
star
56

Fugu

Python
14
star
57

cambio

Spectroscopic file conversion tool
C
14
star
58

mesquite

Mesquite: Mesh Quality Improvement Toolkit
HTML
14
star
59

sandialabs.github.io

JavaScript
14
star
60

packet2vec

Word2Vec embeddings over packet capture data n-grams.
C++
14
star
61

parapint

Parallel solution of structured nonlinear optimization problems
Python
13
star
62

WecOptTool

WEC Design Optimization Toolbox
Python
13
star
63

Matrices

Contains the matrix generation software and normed matrices described in "Recreating Raven's: Software for systematically generating large numbers of Raven-like matrix problems with normed properties," published in Behavior Research Methods in 2010
13
star
64

SNL-Delft3D-CEC

Fortran
12
star
65

staged-script

A Python package enabling the development of robust automation scripts that are subdivided into stages.
Python
12
star
66

p3a

Portably Performant Physical Algebra
C++
12
star
67

LCM

Laboratory for Computational Mechanics
C++
12
star
68

gr-sandia_utils

Misc blocks
C++
12
star
69

RUBRIC

C++
12
star
70

parsegen-cpp

A C++17 library for parser generation for LALR(1) languages
C++
12
star
71

snl-pstess

The Power and Energy Storage Systems Toolbox
MATLAB
12
star
72

sibl

Sandia Injury Biomechanics Laboratory (SIBL)
Python
11
star
73

shadow

Shadow semi-supervised consistency regularization PyTorch library
Python
11
star
74

lim1tr

Lithium-Ion Modeling with 1-D Thermal Runaway (LIM1TR)
Python
11
star
75

StrideSearch

Storm detection in climate data
C++
11
star
76

SNL-SWAN

SNL-SWAN
Fortran
11
star
77

sceptre-bennu

Modeling and simulation of ICS devices
C++
11
star
78

barcs

Ballistic Asynchronous Reversible Computing with Superconductors -- Tool for functional element enumeration and classification.
Python
10
star
79

lapart-python

Python
10
star
80

TIGER

Target / Integrative Genetic Element Retriever: precisely maps IGEs (a defined type of genomic island) in bacterial and archaeal genomes; package also includes orthogonal program Islander
Perl
10
star
81

miniIsosurface

A mini-app to explore algorithms for generating contours from 3D volumes.
C++
10
star
82

chemical-recommender-system

Platform for rapid computation of molecular similarity and integration of custom machine learning models
Python
9
star
83

sdynpy

A Structural Dynamics Python Library
Python
9
star
84

quinn

Quantification of Uncertainties in Neural Networks
Python
9
star
85

Arcus

Arcus, developed by Sandia National Laboratories, is a C# library for calculating, parsing, formatting, converting and comparing both IPv4 and IPv6 addresses and subnets. It accounts for 128-bit numbers on 32-bit platforms.
C#
9
star
86

SpokeDartsPublic

SpokeDarts sphere-packing sampling in any dimension. Advancing front sampling from radial lines (spokes) through prior samples.
C++
9
star
87

linkshop

Python
8
star
88

capp

A simple, portable package manager for applications
CMake
8
star
89

pyperc

Python package to model invasion percolation
Python
8
star
90

Fenix

Fenix: A Portable, Flexible Fault Tolerance Programming Framework for MPI Applications
C
8
star
91

svp_1547.1

Test scripts for IEEE 1547.1
Python
8
star
92

pyNuMAD

pynumad is an object-oriented, open-source software program written in Python which simplifies the process of creating a three-dimensional model of a wind turbine blade.
Python
8
star
93

rattlesnake-vibration-controller

Vibration Controller targetting Multiple-Input-Multiple-Output (MIMO) and Combined Environments Control
Python
8
star
94

mcdn-3d-seg

Monte Carlo Dropout Network for 3D Image Segmentation
Python
8
star
95

phoenix

An astrodynamics library.
Scala
7
star
96

xyz

zip metadata extraction tool
Python
7
star
97

CSPlib

Computational singular perturbation analysis library
Jupyter Notebook
7
star
98

BioCompoundML

BioCompoundML is a software tool for rapidly screening chemicals by chemical properties, using machine learning.
Python
7
star
99

miniGraphics

Miniapp to demonstrate parallel rendering in an MPI environment using a sort-last parallel rendering approach.
C++
7
star
100

PRIME

PRIME is a modeling framework designed for the "real-time" characterization and forecasting of partially observed epidemics
Python
7
star