A Wireshark Lua dissector for CoAP-framed CSMP traffic, TLVs, and Protobuf messages
This is a Wireshark Lua dissector for inspecting CSMP (CoAP Simple Management Protocol) traffic. It is intended to make CSMP exchanges easier to develop, troubleshoot, and validate by decoding the transport framing, CoAP metadata, CSMP TLVs, and their application data in a single Wireshark packet view.
The dissector supports both the CoAP wire format defined by RFC 7252 and the earlier CoAP draft-12 format used by legacy CSMP deployments. It implements its own custom CoAP header decoder for both RFC and draft-12 wire formats. It decodes the fixed header, message type and code, Message ID, token or option count, options, reconstructed URI path, payload marker, and payload. The appropriate wire format can be selected automatically from the UDP ports and packet header or explicitly through the dissector's protocol preference.
After extracting the CoAP payload, the dissector interprets it as a sequence of CSMP Type/Length/Value (TLV) records. It displays each TLV's numeric ID, encoded length, and raw Value bytes. Known TLV IDs are mapped to message types defined in csmp.proto and passed to Wireshark's built-in Protobuf dissector for field-level decoding. Unknown TLVs remain visible as raw data, while new known TLVs can be supported by extending the Protobuf schema and TLV mapping without redesigning or reimplementing the main dissector. This design therefore makes the dissector lightweight, extensible and easy to upgrade and maintain.
Features & Capabilities:
-
RFC and Draft compatibility: Decodes CoAP RFC 7252 on UDP 61628 and CoAP draft-12 on UDP 61624 , with automatic or explicitly forced mode selection preference. Supports CSMP packets from different mesh stackmodes viz., Wi-SUN, Cisco Connected Grid Mesh(CGMESH).
-
Layered protocol visibility: Displays the CoAP header, message metadata, token, options, URI path, payload, CSMP TLVs, raw Value bytes, and known Protobuf fields in one packet tree.
-
Faster fault isolation: Helps distinguish incorrect CoAP framing, option errors, malformed VarInts or TLV lengths, unsupported TLV IDs, and Protobuf decoding problems through Expert Information diagnostics.
-
Searchable evidence: Exposes csmp.* display-filter fields so captures can be narrowed by message metadata, URI, option number, TLV ID, or TLV length.
-
Protobuf decoding with raw fallback: Decodes known TLV IDs using csmp.proto while retaining unknown TLVs as raw bytes for later analysis.
-
Extensible TLV support: Adds new Protobuf-backed TLVs through the schema, mapping table, and supplied helper script (add_tlv.sh) without rebuilding Wireshark or the dissector.
-
Cross-platform support/installation: Works on all Wireshark supported platforms. Package includes installer scripts for macOS, Linux, Windows PowerShell, and Windows Command Prompt.
Dissector GitHub: https://github.com/CiscoDevNet/csmp-agent-lib/tree/main/tools/wireshark-csmp-dissector
Dissector Package: Wireshark-CSMP-Dissector-2.0.zip
Readme: CoAP-CSMP-Wireshark-Dissector-Readme.pdf
