nat-awareness.py
server-edition/tools/nat-awareness.py · 123 line(s) · py
#!/usr/bin/env python3
"""Explicit, read-only STUN mapping probe. Never changes router/firewall settings."""
from __future__ import annotations
import argparse
import ipaddress
import secrets
import socket
import struct
import sys
MAGIC_COOKIE = 0x2112A442
BINDING_REQUEST = 0x0001
BINDING_SUCCESS = 0x0101
BINDING_ERROR = 0x0111
ATTR_MAPPED_ADDRESS = 0x0001
ATTR_XOR_MAPPED_ADDRESS = 0x0020
def build_request(transaction_id: bytes) -> bytes:
if len(transaction_id) != 12:
raise ValueError("STUN transaction ID must be 12 bytes")
return struct.pack("!HHI", BINDING_REQUEST, 0, MAGIC_COOKIE) + transaction_id
def parse_response(data: bytes, transaction_id: bytes) -> tuple[str, int]:
if len(data) < 20:
raise ValueError("STUN response is shorter than its header")
message_type, length, cookie = struct.unpack("!HHI", data[:8])
if message_type not in (BINDING_SUCCESS, BINDING_ERROR):
raise ValueError("unexpected STUN message type")
if cookie != MAGIC_COOKIE or data[8:20] != transaction_id:
raise ValueError("STUN transaction/cookie mismatch")
if 20 + length > len(data) or length % 4:
raise ValueError("invalid STUN attribute length")
if message_type == BINDING_ERROR:
raise ValueError("STUN server returned a binding error")
offset = 20
end = 20 + length
mapped = None
while offset + 4 <= end:
attr_type, attr_length = struct.unpack("!HH", data[offset:offset + 4])
start = offset + 4
stop = start + attr_length
if stop > end:
raise ValueError("truncated STUN attribute")
value = data[start:stop]
if attr_type in (ATTR_XOR_MAPPED_ADDRESS, ATTR_MAPPED_ADDRESS):
if len(value) < 8 or value[0] != 0:
raise ValueError("unsupported STUN address attribute")
family = value[1]
port = struct.unpack("!H", value[2:4])[0]
raw = value[4:]
if attr_type == ATTR_XOR_MAPPED_ADDRESS:
port ^= MAGIC_COOKIE >> 16
mask = struct.pack("!I", MAGIC_COOKIE) + transaction_id
raw = bytes(a ^ b for a, b in zip(raw, mask))
if family == 0x01 and len(raw) == 4:
mapped = (str(ipaddress.IPv4Address(raw)), port)
elif family == 0x02 and len(raw) == 16:
mapped = (str(ipaddress.IPv6Address(raw)), port)
offset = start + ((attr_length + 3) // 4) * 4
if mapped is None:
raise ValueError("STUN response has no supported mapped-address attribute")
return mapped
def discover(server: str, port: int, timeout: float) -> tuple[str, int, str]:
transaction_id = secrets.token_bytes(12)
request = build_request(transaction_id)
last_error = None
for family, socktype, proto, _, sockaddr in socket.getaddrinfo(
server, port, type=socket.SOCK_DGRAM
):
try:
with socket.socket(family, socktype, proto) as sock:
sock.settimeout(timeout)
sock.connect(sockaddr)
local_ip = sock.getsockname()[0]
sock.send(request)
response = sock.recv(2048)
external_ip, external_port = parse_response(response, transaction_id)
return local_ip, external_port, external_ip
except (OSError, ValueError) as exc:
last_error = exc
raise RuntimeError(f"STUN discovery failed: {last_error}")
def main() -> int:
parser = argparse.ArgumentParser(
description="Read-only STUN mapping check; does not configure NAT or port forwarding."
)
parser.add_argument("--server", default="stun.l.google.com",
help="STUN server hostname (default: stun.l.google.com)")
parser.add_argument("--port", type=int, default=19302)
parser.add_argument("--timeout", type=float, default=3.0)
args = parser.parse_args()
if not 1 <= args.port <= 65535 or not 0 < args.timeout <= 30:
parser.error("--port must be 1..65535 and --timeout must be in (0, 30]")
try:
local_ip, external_port, external_ip = discover(args.server, args.port, args.timeout)
local = ipaddress.ip_address(local_ip)
external = ipaddress.ip_address(external_ip)
print(f"local_source_address={local_ip}")
print(f"stun_mapped_address={external_ip}:{external_port}")
if local != external:
print("assessment=address_translation_or_upstream_mapping_likely")
elif not local.is_global:
print("assessment=non_global_local_address; upstream NAT may still be present")
else:
print("assessment=no_address_translation_observed_by_this_probe")
print("note=STUN is an observation only; it does not prove inbound reachability or identify every NAT type.")
print("note=no router settings, firewall rules, or port forwarding were changed.")
return 0
except (OSError, RuntimeError, ValueError) as exc:
print(f"nat-awareness: {exc}", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main())