2026-08-12 14:32:34 +00:00
|
|
|
# gatuna
|
|
|
|
|
|
2026-08-12 18:20:51 +00:00
|
|
|
A raw-Ethernet tunnel for reaching services on a peer machine when a WFP
|
|
|
|
|
killswitch on the local machine blocks normal IP traffic. Two programs carry
|
|
|
|
|
bytes between their respective loopbacks over a private L2 protocol, bypassing
|
|
|
|
|
the IP stack (and therefore the killswitch) entirely.
|
|
|
|
|
|
|
|
|
|
## Why this works
|
|
|
|
|
|
|
|
|
|
WireGuard-for-Windows installs its killswitch as WFP filters at the ALE layers
|
|
|
|
|
only (`ALE_AUTH_CONNECT_V4/V6`, `ALE_AUTH_RECV_ACCEPT_V4/V6`). It never installs
|
|
|
|
|
MAC-layer callouts — the L2 code in `tunnel/firewall/` is commented out. Raw
|
|
|
|
|
Ethernet frames sent via a packet driver (Npcap on Windows, `AF_PACKET` on
|
|
|
|
|
Linux) never enter the IP stack, so they never reach the ALE classify path and
|
|
|
|
|
pass unimpeded. See `wireguard-windows/tunnel/firewall/blocker.go:156`.
|
|
|
|
|
|
|
|
|
|
## Components
|
|
|
|
|
|
|
|
|
|
- `gatunad` — Rust server. Runs on the peer (Linux) that owns the real
|
|
|
|
|
services. Announces upstreams and relays TCP between the tunnel and
|
|
|
|
|
`127.0.0.1:<port>`.
|
|
|
|
|
- `gatuna` (planned) — .NET WinForms client. Runs on the killswitched Windows
|
|
|
|
|
box. Discovers the server, presents its upstreams as local loopback
|
|
|
|
|
listeners, and hauls bytes over the same L2 protocol.
|
|
|
|
|
|
|
|
|
|
This repository builds `gatunad` first.
|
|
|
|
|
|
|
|
|
|
## Transport
|
|
|
|
|
|
|
|
|
|
- **Medium:** raw Ethernet frames on a shared L2 segment.
|
|
|
|
|
- **Ethertype:** `0x6969` (hardcoded).
|
|
|
|
|
- **No IP stack involvement.** Frames carry only our 6-byte header + payload.
|
|
|
|
|
- **BPF:** the server attaches a classic BPF filter `ether proto 0x6969` to its
|
|
|
|
|
`AF_PACKET` socket so it only wakes on our ethertype. No eBPF authoring.
|
|
|
|
|
|
|
|
|
|
## Protocol
|
|
|
|
|
|
|
|
|
|
See [`PROTOCOL.md`](PROTOCOL.md) for the full wire format. Summary:
|
|
|
|
|
|
|
|
|
|
- 6-byte header, big-endian: `[ version:1 ][ type:1 ][ session_id:4 ][ payload:N ]`.
|
|
|
|
|
- `version` = `1`. No length field (frame length comes from the capture). No
|
|
|
|
|
CRC. Ethertype discriminates our frames from everything else.
|
|
|
|
|
- Discovery: client broadcasts `DISCOVER`; server unicasts `MANIFEST` back.
|
|
|
|
|
- Sessions: `OPEN` → `OPEN_ACK` (or `OPEN_NAK`) → `DATA`* ↔ `DATA`* → `CLOSE`.
|
|
|
|
|
- v1 ships TCP only. UDP frame types are reserved but unimplemented.
|
|
|
|
|
|
|
|
|
|
## `gatunad` usage
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
gatunad IFACE PORT [PORT...]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- `IFACE` — L2 interface name (e.g. `eth0`).
|
|
|
|
|
- `PORT` — `int[:label]`; a TCP upstream relayed to `127.0.0.1:int`. The label
|
|
|
|
|
is optional, max 255 bytes, carried in the MANIFEST for the client to display.
|
|
|
|
|
At least one required. Upstream ID = 1-based positional index in cmdline order.
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
```
|
|
|
|
|
sudo ./gatunad eth0 22 8800:site-a 8080:site-b
|
|
|
|
|
```
|
|
|
|
|
Exposes upstreams `1→127.0.0.1:22`, `2→127.0.0.1:8800` (label `site-a`),
|
|
|
|
|
`3→127.0.0.1:8080` (label `site-b`).
|
|
|
|
|
|
|
|
|
|
## Privileges
|
|
|
|
|
|
|
|
|
|
`AF_PACKET` requires `CAP_NET_RAW`. Run as root, or grant the binary the
|
|
|
|
|
capability once:
|
|
|
|
|
```
|
|
|
|
|
sudo setcap cap_net_raw+ep ./target/release/gatunad
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Logging
|
|
|
|
|
|
|
|
|
|
Errors only, to stdout. Normal lifecycle (DISCOVER/OPEN/CLOSE) is silent.
|
|
|
|
|
|
|
|
|
|
## v1 limitations
|
|
|
|
|
|
|
|
|
|
- TCP only. UDP wire types reserved, code paths stubbed.
|
|
|
|
|
- No retransmit at the L2 layer. A dropped `DATA` frame breaks the TCP session
|
|
|
|
|
irrecoverably because the localhost socket already ACKed the bytes. Acceptable
|
|
|
|
|
on a healthy switched link.
|
|
|
|
|
- No auth/crypto. Anyone on the same L2 segment can `DISCOVER` and `OPEN`.
|
|
|
|
|
- Single server instance per interface.
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
CC0 1.0 Universal. See [`LICENSE`](LICENSE).
|
