Protocol 20 of 81Layer 3FrameAssembly v3.1.2
llms-full.txt
wireguardWireGuard Noise_IK Secure Network Tunnel

Modern Noise-IK VPN Handshakes & Transport Data (wireguard UDP 51820)

Default Port / Protocol
UDP 51820
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
wg
Standards & Specs
WireGuard Whitepaper (NDSS 2017)
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6WireGuard (UDP 51820)

What It Does on the Wire

Four clean message types on UDP 51820 (initiation, response, cookie, data) with little-endian sender/receiver indices — wireguard lets you test egress VPN policies in four lines.

WireGuard (wireguard) is a modern cryptographic VPN tunnel built on the Noise_IKpsk2 handshake, ChaCha20-Poly1305 AEAD, BLAKE2s, and Curve25519 over UDP dstport 51820. WireGuard packets are famously fixed-size during the handshake—148 bytes for Type 1 Handshake Initiation, 92 bytes for Type 2 Handshake Response, and 64 bytes for Type 3 Cookie Reply—plus variable-length 16-byte padded Type 4 Transport Data packets.

FrameAssembly encodes the exact little-endian WireGuard header fields (Message Type + 3 zero reserved bytes, 32-bit sender / receiver session indices, and 64-bit AEAD counter) and enforces exact protocol wire lengths so stateful DPI engines and Wireshark recognize every message type immediately.

Shadow VPN & Unauthorized WireGuard Egress Detection

Generate 148-byte initiation -> 92-byte response -> data sequences on both standard UDP 51820 and non-standard ports (dstport 443) to test NDR behavioral signatures.

DoS Under-Load Cookie Reply (type 3) Validation

Emit 64-byte wireguard cookie replies to verify perimeter DDoS mitigation appliances and client retry logic.

Mesh Overlay MTU & IPv6 Roaming Captures

Test dual-stack WireGuard transport packets (counter 0, counter 1, ...) across IPv4 and IPv6 endpoints.

Minimal Quickstart (wireguard_quickstart.frasm)

Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.

wireguard_quickstart.frasm7 lines
Open in Playground
host wg_laptop { ip 198.51.100.42 }
host wg_relay { ip 203.0.113.10 }
compile {
wg_laptop -> wg_relay wireguard initiation sender 0x01020304 wait 2ms
wg_laptop <- wg_relay wireguard response sender 0x0a0b0c0d receiver 0x01020304
}

What the Compiler Calculates So You Don't Have To

  • Defaults UDP dstport to 51820 and writes the 4-byte WireGuard message header (Type 1..4 followed by three mandatory 0x00 reserved bytes).
  • Emits exact-length handshake structures: 148 bytes for initiation (Type 1), 92 bytes for response (Type 2), and 64 bytes for cookie (Type 3).
  • Encodes sender, receiver, and 64-bit counter in WireGuard little-endian byte order per the WireGuard specification.
Multi-Frame Lab · Ready to Compile

Full 1-RTT Noise_IK Handshake, Transport Data Stream, and Under-Load Cookie

Captures a WireGuard initiator completing a 1-RTT handshake (initiation + response), exchanging encrypted data frames with incrementing counters, and handling a cookie challenge.

wireguard_handshake_data.frasm15 lines
Open in Playground
host roadwarrior { ip 198.51.100.88 }
host corp_wg_gw { ip 203.0.113.5 }
compile {
// 1. Optional DoS Cookie Reply challenge (64 bytes, Type 3)
roadwarrior -> corp_wg_gw wireguard initiation sender 0x11112222 wait 2ms
roadwarrior <- corp_wg_gw wireguard cookie receiver 0x11112222 wait 3ms
// 2. Full 1-RTT Noise_IKpsk2 Handshake (148B Initiation -> 92B Response)
roadwarrior -> corp_wg_gw wireguard initiation sender 0x33334444 wait 2ms
roadwarrior <- corp_wg_gw wireguard response sender 0xaaaabbbb receiver 0x33334444 wait 2ms
// 3. Encrypted Transport Data packets (Type 4) swapping receiver indices
roadwarrior -> corp_wg_gw wireguard data receiver 0xaaaabbbb counter 0 payload "inner-ipv4-syn" wait 1ms
roadwarrior <- corp_wg_gw wireguard data receiver 0x33334444 counter 0 payload "inner-ipv4-synack" wait 1ms
roadwarrior -> corp_wg_gw wireguard data receiver 0xaaaabbbb counter 1 payload "inner-ipv4-ack"
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show wireguard_handshake_data.frasm

# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly wireguard_handshake_data.frasm wireguard_handshake_data.pcap
frameassembly wireguard_handshake_data.frasm wireguard_handshake_data.pcapng

# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse wireguard_handshake_data.pcap wireguard_handshake_data_edited.frasm

All wireguard Keywords & Header Options

Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after wireguard:

src_host -> dst_host wireguard [type <initiation|response|cookie|data> | initiation | response | cookie | data] [sender <number>] [receiver <number>] [counter <number>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
initiation | response | cookie | data | type <...>WireGuard message type keywordinitiation (Type 1)Selects Type 1 Handshake Initiation (148B), Type 2 Handshake Response (92B), Type 3 Cookie Reply (64B), or Type 4 Transport Data (>= 32B).
sender <number>Whole number1Sets the 32-bit Sender Index in initiation and response messages identifying the local session slot.
receiver <number>Whole number2Sets the 32-bit Receiver Index in response, cookie, and data messages referencing the peer Sender Index.
counter <number>Whole number0Sets the 64-bit ChaCha20-Poly1305 AEAD nonce counter in Type 4 data packets.

Cross-Layer Wrappers Valid with wireguard

802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol

10 options
OptionRange / FormatDefaultEffect on Packet
wait <number><ns|us|ms|s|m>Time gap (ns, us, ms, s, m)10msAdvances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back).
payload "<text>" | hexpayload "<hex>"Quoted text or hex bytes (choose one)OmittedAppends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums.
srcmac <mac> | dstmac <mac>Colon, hyphen, or Cisco dot MACHost MAC / RFC multicast MACOverrides the 14-byte Ethernet II source or destination MAC address for this single packet.
vlan <0..4095> [pcp <0..7>] [dei <0|1>]VLAN ID 0..4095, PCP 0..7, DEI 0..1UntaggedWraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority.
qinq <0..4095> [innervlan <0..4095>]Outer S-VLAN 0..4095, Inner C-VLAN 0..4095Untagged (innervlan 1 when qinq is set)Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100).
mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>]Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255Unlabeled (at most 1 mpls tag per packet)Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header.
ttl <0..255> [dscp <0..63>] [ecn <0..3>]TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3ttl 64, dscp 0, ecn 0Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings.
ipid <0..65535> [df] [mf] [fragoffset <0..8191>]IPv4 ID, DF/MF flags, fragment offset 0..8191ipid 1, flags 0, fragoffset 0Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6).
flowlabel <0..1048575>20-bit IPv6 Flow Label (0..1048575)0Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts).
srcport <0..65535> | dstport <0..65535>Port number 0..65535srcport 49152 (remembered), UDP 51820Overrides source or destination port and remembers the port pair automatically on <- replies.

Gotchas & Quick Fixes

Match receiver on Data Frames to the Peer sender Index

Valid v3.1.2 Syntax
a -> b wireguard response sender 0x99 receiver 0x11 a <- b wireguard data receiver 0x99 counter 0

WireGuard Transport Data (data) frames only carry the destination peer receiver index (not sender), which must match the sender index advertised by that peer during the handshake.

Use counter (Not seq) for AEAD Packet Nonces

Avoid
a -> b wireguard data seq 1
Valid v3.1.2 Syntax
a -> b wireguard data receiver 0x99 counter 1

Because WireGuard runs over UDP rather than TCP, TCP seq is not valid here. Use counter for the 64-bit WireGuard packet counter.

Field Guide 05
VLANs, QinQ, MPLS, Tunnel Soup & Dual-Stack IPv6