Wireshark Veilid Dissector

ABOUT THIS DISSECTOR

wireshark-veilid-plugin.lua is a Wireshark Lua dissector for the Veilid peer-to-peer network protocol. It began by hand-decoding live Veilid traffic before protocol documentation existed and was later refined with completeness checks by Claude Opus 4.6. It was developed as part of the QX9 Network Analysis Toolkit - an open-source project by QX9, an independent cross-functional engineering group bringing forward fully encrypted platform designs for critical communications such as public safety radio dispatch and next-generation 911.

This page provides an architecture overview of the dissector plugin, including the Veilid wire format diagrams and a high-level walkthrough of the plugin's structure. For the full technical reference - display filter tables, expert info entries, compound filter examples, coloring rules, installation, and troubleshooting - see DISSECTOR.md.

ABOUT VEILID

Veilid is an open-source, peer-to-peer application framework created by the Veilid Foundation (veilid.org). It provides encrypted, private, and resilient networking primitives that applications can build on - including end-to-end encrypted messaging, distributed hash table storage, and anonymous routing. Veilid is written in Rust and designed so that every node in the network contributes to the infrastructure, with no central servers required.

QX9's interest in Veilid stems from its potential as the transport layer for private, low-complexity critical communication networks.

INSTALLATION

Copy wireshark-veilid-plugin.lua to your personal Wireshark plugins directory and restart Wireshark (or press Ctrl+Shift+L to reload Lua plugins without restarting).

Plugin directories by platform:

Platform	Path
Windows	`%APPDATA%\Wireshark\plugins`
macOS	`~/.local/lib/wireshark/plugins`
Linux	`~/.local/lib/wireshark/plugins`

Verify the plugin loaded via Help → About Wireshark → Plugins tab. For quick-start usage, display filters, coloring rules, and troubleshooting see DISSECTOR.md.

PLUGIN STRUCTURE

The dissector is a single Lua file organized into clearly separated sections. Each section is documented with inline comments referencing the Veilid source files it was validated against. For complete details on any section, see DISSECTOR.md.

SETUP

DEFINITIONS

Expert Info

Diagnostic entries for malformed packets, unknown FOURCCs, unknown crypto kinds, reserved envelopes, fragment version errors, oversize envelopes, timestamp skew / replay detection, oversize receipts, and unsigned bootstrap (v0) downgrade warnings.

Protocol Fields

Filterable display fields organized by group: common, ENV0/ENV1 envelope, RCP0 receipt, bootstrap, TCP framing, UDP fragment, and hole punch.

Utility Functions

Timestamp conversion, FOURCC reading, TCP frame detection, and crypto kind description helpers.

DISSECTION

Message Dissectors

One function per wire message type: dissect_env0(), dissect_env1(), dissect_rcp0(), dissect_bootstrap(), dissect_udp_fragment(), and dissect_hole_punch().

TCP Reassembly

VL frame header parsing and dissect_tcp_pdus() integration for multi-segment TCP payloads.

Entry Point & Dispatch

Routes packets through TCP (VL framing or direct) or UDP (hole punch, fragment, or direct FOURCC) paths, dispatches by FOURCC to message handlers, and registers on the configured port for both TCP and UDP.

DETECTION

Heuristic Dissectors

Transport-level detection for TCP (VL magic), UDP (fragment header + FOURCC), WebSocket (FOURCC at byte 0), and QUIC (reserved).

Post-Dissector

Labels TCP control packets (SYN/FIN/RST/ACK), replaces IANA 'atmp' with 'veilid' on port 5150, and tags intermediate reassembly segments.

DISSECTOR PIPELINE

The dissector routes every incoming packet through transport detection, optional reassembly, and FOURCC-based dispatch. The flowchart below shows the complete decision path from raw packet to message-specific handler. For TCP/UDP reassembly details and the post-dissector, see DISSECTOR.md.

Incoming Packet
       │
       ├─ TCP (port_type == 2)
       │       │
       │       ├─ VL frame detected? ──→ dissect_tcp_pdus()
       │       │                              │
       │       │                              ├─ get_len: read VL payload length
       │       │                              └─ dissect: VL frame → FOURCC dispatch
       │       │
       │       └─ No VL frame ──→ FOURCC dispatch directly (reassembled tvb)
       │
       ├─ UDP (port_type != 2)
       │       │
       │       ├─ Zero-length? ──→ Hole Punch
       │       │
       │       ├─ Fragment header (ver ≥ 1)?
       │       │       │
       │       │       ├─ Actual fragment ──→ Show fragment fields
       │       │       └─ Unfragmented ──→ Strip 8-byte header → FOURCC dispatch
       │       │
       │       └─ FOURCC dispatch directly
       │
       └─ FOURCC Dispatch Table
               │
               ├─ "BOOT" ──→ dissect_bootstrap("BOOT")
               ├─ "B01T" ──→ dissect_bootstrap("B01T")
               ├─ "RCP0" ──→ dissect_rcp0()
               ├─ "ENV0" ──→ dissect_env0()
               ├─ "ENV1" ──→ dissect_env1()
               └─ Unknown ──→ Expert Info warning

WIRE FORMAT DIAGRAMS

The diagrams below show the exact byte layout of each Veilid wire message type as parsed by the dissector. Each diagram was generated from the same constants and offsets validated against veilid-core 0.5.2 source code. Diagrams are presented in protocol order: transports first (bootstrap, TCP, UDP, WebSocket, QUIC), then message types (RCP0, ENV0, ENV1).

BOOT

Figure 1 - BOOT / B01T Bootstrap Discovery

TCP

TCP Transport (VL Framing) wire format diagram

Figure 2 - TCP Transport (VL Framing)

UDP

UDP Transport (Fragments + Hole Punch) wire format diagram

Figure 3 - UDP Transport (Fragments + Hole Punch)

WS / WSS

Figure 4 - WebSocket Transport

QUIC

Figure 5 - QUIC Transport [Reserved]

RCP0

Figure 6 - RCP0 Out-of-Band Receipt

ENV0

Figure 7 - ENV0 Encrypted Envelope

ENV1

Figure 8 - ENV1 Encrypted Envelope [Reserved]