Wireshark Veilid Dissector

ABOUT THIS DISSECTOR

wireshark-veilid-plugin.lua is a Wireshark Lua dissector for the Veilid peer-to-peer network protocol. Written against veilid-core 0.5.2, it began as hand-decoding of live traffic before protocol documentation existed and was then checked against the veilid-core source with Claude Opus 4.6. That check compares the dissector to the source; it is not a conformance test. The dissector was revalidated on the release of 0.5.3 with no logic change and has since been checked against the source of each later release, with wire formats byte-identical through 0.5.7. It was developed as part of the QX9 Network Analysis Toolkit - an open-source project by QX9, which develops encrypted infrastructure for critical communications and publishes protocol documentation and wire-format analysis tools under open licenses, this dissector among them. QX9's current focus is next-generation 911, with radio dispatch interoperability reserved for future work.

This software is not certified for use in life-safety, emergency-dispatch, or mission-critical communications systems. Do not rely on it for emergency response.

This page covers the plugin's structure, the dissector pipeline, and the wire format diagrams, with installation in brief. DISSECTOR.md is the full reference, covering display filters, expert info, coloring rules, installation, troubleshooting, the wire protocol summary, the Veilid source code map, and the roadmap.

INSTALLATION

Copy wireshark-veilid-plugin.lua to your personal Wireshark plugins directory, then restart Wireshark or press Ctrl+Shift+L to reload Lua plugins. The installation section of DISSECTOR.md lists the directory for each platform and how to confirm the plugin loaded.

PLUGIN STRUCTURE

The dissector is a single Lua file organized into the sections below.

SETUP

DEFINITIONS

DISSECTION

DETECTION

DISSECTOR PIPELINE

The dissector routes each packet it receives through transport detection, optional reassembly, and FOURCC-based dispatch. The flowchart below traces a packet from arrival to its message handler. Its zero-length branch never runs, because Wireshark passes no empty UDP payload to a dissector.

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 (segment not starting with VL)
       │
       ├─ UDP (port_type != 2)
       │       │
       │       ├─ Zero-length? ──→ Hole Punch (never reached)
       │       │
       │       ├─ Over 8 bytes, first byte ≥ 1?
       │       │       │
       │       │       ├─ Version ≠ 1 ──→ Unknown-version warning
       │       │       ├─ Actual fragment ──→ Show fragment fields
       │       │       └─ Unfragmented ──→ Strip 8-byte header → FOURCC dispatch
       │       │
       │       └─ FOURCC dispatch directly
       │
       └─ FOURCC Dispatch Table
               │
               ├─ JSON reply to a captured BOOT/B01T ──→ dissect_bootstrap_response()
               ├─ "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 Veilid's byte layouts, each drawn from constants and offsets validated against the veilid-core source. ENV1 and QUIC are the two exceptions: they sketch a later envelope version and a QUIC transport that veilid-core does not define today, so those layouts are anticipated rather than validated. The bootstrap figure also draws the response, which the dissector matches to the request before it. Diagrams are presented in protocol order: the transports (TCP, UDP, WebSocket, and the anticipated QUIC), then the message types (RCP0, ENV0, and the anticipated ENV1). Bootstrap leads the sequence, though it is a discovery exchange carried over the transports rather than a transport of its own.

BOOT

Figure 1 - BOOT / B01T Bootstrap Discovery

TCP

Figure 2 - TCP Transport (VL Framing)

UDP

Figure 3 - UDP Transport (Fragments + Hole Punch)

WS / WSS

Figure 4 - WebSocket Transport

QUIC

Figure 5 - QUIC Transport [Anticipated]

RCP0

Figure 6 - RCP0 Out-of-Band Receipt

ENV0

Figure 7 - ENV0 Encrypted Envelope

ENV1

Figure 8 - ENV1 Encrypted Envelope [Anticipated]