tailnet-guard

A tiny, pure, dependency-free trust barrier for services fronted by a Tailscale tailnet. It answers one question — may I serve this peer? — from facts you supply (the peer's real socket address, never a forwarded header, plus the capability token it presented), and it makes "listen on a public interface" hard to do by accident.

Extracted from a security-reviewed pattern shared by two projects (easy-podcast + antibody-analysis) so the posture lives in one place to audit and fix. Stdlib only (ipaddress, hmac); every check is fail-closed.

Install

pip install tailnet-guard            # once published
pip install git+https://github.com/falahat/tailnet-guard.git   # from source

Use

from tailnet_guard import PeerRequest, GuardOutcome, evaluate_peer, resolve_bind_host

# 1. Refuse to bind anything but a tailnet/loopback interface.
host = resolve_bind_host(args.bind)                 # raises BindError otherwise
#    allow_any=True permits 0.0.0.0 ONLY behind an outer reachability constraint
#    (e.g. a container whose ports are published on a tailnet address).

# 2. Gate each request on the REAL socket address + the capability token.
outcome = evaluate_peer(
    PeerRequest(remote_addr=request.client.host, token=presented_token),
    expected_token=worker_secret,
)
if outcome is not GuardOutcome.ALLOW:
    raise Forbidden()        # flat 403 — don't leak which check failed

Two network policies

The membership predicate is a parameter, so each caller keeps its own policy:

• is_tailnet_or_loopback (default) — strict: only the Tailscale CGNAT range (100.64.0.0/10) or loopback. For a server that should never trust the physical LAN.
• is_local — broad: any non-public address (RFC1918 private, link-local, loopback, tailnet). For a host that also trusts LAN peers.

evaluate_peer(req, secret, membership=is_local)         # admit LAN peers too
resolve_bind_host("192.168.1.10", membership=is_local)  # allow a LAN bind

What's in the box

Security notes

• Pass the real socket peer, e.g. request.client.host (ASGI) or self.client_address[0] (http.server) — never X-Forwarded-For / Host, which a client controls.
• The guard is stateless — it does not provide replay protection. If you need that, add a nonce/freshness layer at your message envelope (Tailscale's WireGuard already authenticates the transport).
• Turn any non-ALLOW outcome into a flat 403 without echoing the reason.