Protocol 49 of 81Layer 7FrameAssembly v3.1.2
llms-full.txt
websocketWebSocket Framed Bidirectional Messaging

RFC 6455 Masked Frames Over Upgraded Sockets (client <-> srv websocket)

Default Port / Protocol
TCP 80
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
websocket
Standards & Specs
RFC 6455
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6TCP 80WebSocket

What It Does on the Wire

Pass maskkey 0x37fa213d on a client -> server websocket text frame and the compiler genuinely XOR-masks your payload bytes on the wire, so you can watch Wireshark unmask and display the cleartext right in the tree!

WebSocket (websocket, RFC 6455) upgrades an HTTP/1.1 TCP connection into a persistent, low-latency bidirectional message channel on TCP port 80 (or custom ports). A critical RFC 6455 wire rule is client-to-server masking: frames sent by a browser or client carry a 32-bit maskkey (MASK=1) that XOR-scrambles the payload bytes on the wire, whereas server-to-client frames travel unmasked (MASK=0).

When you provide maskkey (for example maskkey 0x37fa213d), FrameAssembly sets the MASK bit, writes the 4-byte key into the WebSocket header, and XOR-masks your payload automatically so Wireshark unmasks and displays the exact JSON or text cleanly.

Test IDS / WAF Inspection of XOR-Masked Client Payloads

Verify that Suricata and NGFW deep-packet inspection engines unmask RFC 6455 client frames (maskkey) after an HTTP 101 Switching Protocols upgrade.

Reverse Proxy Idle Timeout & Ping/Pong Keepalive Tuning

Capture websocket ping -> websocket pong heartbeat intervals alongside close frames to troubleshoot NGINX or cloud load balancer disconnects.

Fragmented Multi-Frame Message Reassembly (finbit 0 -> finbit 1)

Test proxy and parser handling of split WebSocket messages using finbit 0 continuation sequences.

Minimal Quickstart (websocket_quickstart.frasm)

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

websocket_quickstart.frasm7 lines
Open in Playground
host browser { ip 10.10.2.15 }
host ws_srv { ip 10.10.2.80 }
compile {
browser -> ws_srv websocket text maskkey 0x37fa213d payload "{\"subscribe\":\"alerts\"}" wait 2ms
browser <- ws_srv websocket text payload "{\"event\":\"link_up\"}"
}

What the Compiler Calculates So You Don't Have To

  • Defaults to TCP destination port 80 (psh ack), text frame (opcode 0x1), and finbit 1 (complete unfragmented message).
  • Encodes RFC 6455 extended 16-bit (126) or 64-bit (127) payload lengths automatically when payloads exceed 125 bytes.
  • Applies RFC 6455 4-byte XOR payload masking automatically whenever maskkey is specified.
Multi-Frame Lab · Ready to Compile

Full HTTP 101 Upgrade Handshake Into Masked WebSocket Stream & Close

Performs a TCP handshake + HTTP 101 Switching Protocols WebSocket upgrade so Wireshark and Suricata track the protocol switch, then exchanges masked client JSON, server events, ping/pong, and close.

websocket_upgrade_session.frasm17 lines
Open in Playground
host dashboard_ui { ip 172.16.10.25 }
host realtime_gw { ip 172.16.10.80 }
compile {
// 1. TCP 3-way handshake + HTTP 101 WebSocket Upgrade
dashboard_ui -> realtime_gw tcp syn srcport 52800 dstport 80 win 65535 mss 1460 wait 1ms
dashboard_ui <- realtime_gw tcp syn ack win 65535 mss 1460 wait 1ms
dashboard_ui -> realtime_gw tcp ack wait 1ms
dashboard_ui -> realtime_gw http get uri "/ws" hosthdr "noc.corp.internal" header "Upgrade" "websocket" header "Connection" "Upgrade" header "Sec-WebSocket-Version" "13" header "Sec-WebSocket-Key" "dGhlIHNhbXBsZSBub25jZQ==" wait 2ms
dashboard_ui <- realtime_gw http status 101 reason "Switching Protocols" header "Upgrade" "websocket" header "Connection" "Upgrade" wait 2ms
// 2. Masked client text frame + unmasked server push + Ping/Pong + Close
dashboard_ui -> realtime_gw websocket text maskkey 0x12345678 payload "{\"op\":\"subscribe\",\"channel\":\"bgp\"}" wait 2ms
dashboard_ui <- realtime_gw websocket text payload "{\"peer\":\"10.0.0.2\",\"state\":\"Established\"}" wait 10ms
dashboard_ui <- realtime_gw websocket ping payload "hb" wait 1ms
dashboard_ui -> realtime_gw websocket pong maskkey 0xabcdef01 payload "hb" wait 5ms
dashboard_ui -> realtime_gw websocket close maskkey 0x11223344
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show websocket_upgrade_session.frasm

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

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

All websocket 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 websocket:

src_host -> dst_host websocket [text | binary | close | ping | pong | opcode "<text>"] [finbit <0|1>] [maskkey <number>] [payload "<text>"]
Keyword / OptionAccepted ValueDefaultEffect on Packet
text | binary | close | ping | pong | opcode "<text>"WebSocket frame opcodetext (0x1)Selects RFC 6455 opcode 0x1 (text), 0x2 (binary), 0x8 (close), 0x9 (ping), 0xa (pong), or "continuation" (0x0).
finbit <0|1>1 (final frame) or 0 (more fragments follow)1Sets the FIN bit in byte 0 of the WebSocket header.
maskkey <number>32-bit masking key (e.g. 0x37fa213d)Unmasked (MASK=0)Sets MASK=1, inserts the 4-byte Masking-Key in the header, and XOR-masks payload bytes on the wire.
payload "<text>"Quoted UTF-8 message payloadEmptySets the WebSocket message data (automatically masked when maskkey is present).

Cross-Layer Wrappers Valid with websocket

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

11 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), TCP 80Overrides source or destination port and remembers the port pair automatically on <- replies.
seq <number> | acknum <number> | win <0..65535> | syn | ack | psh | fin | rstTCP sequence/ack numbers, window size, flags & RFC 7323 optionspsh ack, win 65535, automatic TCP seq/acknumOverrides automatic TCP sequence tracking, flags, or RFC 7323 options (mss, wscale, sackperm, tsval, tsecr).

Gotchas & Quick Fixes

Include HTTP 101 Upgrade If You Want Automatic Wireshark Dissection on Non-Standard Ports

Valid v3.1.2 Syntax
Send http get header "Upgrade" "websocket" -> http status 101 before websocket frames

Wireshark recognizes the transition from HTTP to WebSocket on TCP port 80 best when preceded by the HTTP Upgrade: websocket / 101 Switching Protocols exchange (or via Decode As -> WebSocket).

RFC 6455 Requires maskkey on Client-to-Server Frames

Valid v3.1.2 Syntax
browser -> ws_srv websocket text maskkey 0x37fa213d payload "hello"

Strict WebSocket servers close connections (1002 Protocol Error) if client-to-server frames omit maskkey, while server-to-client replies omit maskkey.

Field Guide 03
Poke Stateful Firewalls, Suricata, Zeek & OT Conduits