wireguardWireGuard Noise_IK Secure Network TunnelModern Noise-IK VPN Handshakes & Transport Data (wireguard 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.
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
dstportto51820and writes the 4-byte WireGuard message header (Type1..4followed by three mandatory0x00reserved bytes). - Emits exact-length handshake structures:
148bytes forinitiation(Type 1),92bytes forresponse(Type 2), and64bytes forcookie(Type 3). - Encodes
sender,receiver, and 64-bitcounterin WireGuard little-endian byte order per the WireGuard specification.
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.
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"}# 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.frasmAll 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 / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| initiation | response | cookie | data | type <...> | WireGuard message type keyword | initiation (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 number | 1 | Sets the 32-bit Sender Index in initiation and response messages identifying the local session slot. |
| receiver <number> | Whole number | 2 | Sets the 32-bit Receiver Index in response, cookie, and data messages referencing the peer Sender Index. |
| counter <number> | Whole number | 0 | Sets 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
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
| Option | Range / Format | Default | Effect on Packet |
|---|---|---|---|
| wait <number><ns|us|ms|s|m> | Time gap (ns, us, ms, s, m) | 10ms | Advances 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) | Omitted | Appends 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 MAC | Host MAC / RFC multicast MAC | Overrides 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..1 | Untagged | Wraps 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..4095 | Untagged (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..255 | Unlabeled (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..3 | ttl 64, dscp 0, ecn 0 | Sets 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..8191 | ipid 1, flags 0, fragoffset 0 | Sets 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) | 0 | Sets 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..65535 | srcport 49152 (remembered), UDP 51820 | Overrides 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
a -> b wireguard response sender 0x99 receiver 0x11
a <- b wireguard data receiver 0x99 counter 0WireGuard 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
a -> b wireguard data seq 1a -> b wireguard data receiver 0x99 counter 1Because WireGuard runs over UDP rather than TCP, TCP seq is not valid here. Use counter for the 64-bit WireGuard packet counter.