Inspecting SAPIENT traffic in Wireshark

What it does

• Decodes BSI Flex 335 v2.0 and v1.0 traffic, registered as separate protocols (sapient_v2 and sapient_v1).
• Strips SAPIENT's 4-byte little-endian length prefix and decodes each message separately, including when several messages share one TCP segment.
• Shows nested messages with field names, and enumerations by name (for example NODE_TYPE_CAMERA(4) rather than 4).
• Works in the Wireshark GUI and in tshark, on live interfaces and saved captures.

It's a short Lua plugin over Wireshark's built-in Protobuf dissector, pointed at the official SAPIENT .proto schema, which the repository includes. Field decoding therefore always follows the schema rather than a hand-written decoder. It has been tested with Wireshark 4.6.

Installation

Two one-off steps. Clone or download the sapient-wireshark-dissector repository first.

1. Point Wireshark at the SAPIENT schema

In Wireshark, open Edit → Preferences → Protocols → ProtoBuf. Under Protobuf search paths, add the repository's proto/ directory and tick Load all files. This is the same on every operating system.

2. Install the Lua plugin

Copy plugins/sapient.lua into your personal Lua plugins folder, then choose Analyze → Reload Lua Plugins or restart Wireshark. Your build's exact folder is shown in Help → About Wireshark → Folders as "Personal Lua Plugins". It is usually:

Use the unversioned Lua folder, not the version-numbered binary plugins folder beside it.

Decoding SAPIENT traffic

SAPIENT doesn't define a standard port, so the dissector isn't tied to one. Tell Wireshark which stream is SAPIENT:

1. Capture on the interface your nodes use, or open a .pcap / .pcapng file.
2. Right-click a packet on the SAPIENT TCP connection and choose Decode As….
3. Set the protocol to SAPIENT (BSI Flex 335 v2.0), or v1.0 for older systems, and click OK.

Each packet now shows a SapientMessage tree in the details pane. Use the display filter sapient_v2 to hide everything else.

Using tshark

The same decoding works from the command line, which is handy for long captures, remote machines and scripts. Pass the port with -d:

# Full decode of every SAPIENT message in a capture on port 5000
tshark -r trial.pcapng -d tcp.port==5000,sapient_v2 -Y sapient_v2 -O sapient_v2,protobuf

# Watch a live interface
tshark -i eth0 -f "tcp port 5000" -d tcp.port==5000,sapient_v2 -O sapient_v2,protobuf

To use the dissector without installing it, for example in CI, load it and the schema on the command line:

tshark -r trial.pcapng \
  -X lua_script:sapient-wireshark-dissector/plugins/sapient.lua \
  -o 'uat:protobuf_search_paths:"sapient-wireshark-dissector/proto","TRUE"' \
  -d tcp.port==5000,sapient_v2 -V

A debugging workflow

When two SAPIENT systems won't work together, capturing the traffic between them usually settles who is at fault faster than reading either side's logs:

1. Capture at the boundary. Run tshark or tcpdump on the Fusion Node host, or on a mirror port, so you record what actually crossed the network rather than what either side logged.
2. Check the framing first. If messages don't decode, or decode into nonsense, the length prefix is usually wrong: big-endian instead of little-endian, missing, or covering two messages.
3. Follow the session. Look for the Registration and RegistrationAck, then check task and alert IDs against their acknowledgements, and the mode in each status report against the tasks sent.
4. Reproduce with the harness. Once you know which message is wrong, the test harness can replay the exchange and report it as a named rule, and you can use that as a regression check once it's fixed.

Keep captures from trials. A .pcapng of a failing exchange is the most useful thing to attach to a bug report, for these tools or for another supplier's system.

Troubleshooting

"SAPIENT" doesn't appear in Decode As

Your Wireshark may have been built without Lua. Check with tshark -v | grep -i lua. The packages in RHEL, Rocky Linux and CentOS are built without it. The repository has a script that builds a current Wireshark with Lua alongside the distribution package.

Nothing loads when running as root

Wireshark silently skips personal Lua plugins when run as root, including inside containers. Run it as an ordinary user.

Protobuf parse errors in old Wireshark versions

Wireshark 3.4 can't parse some of the syntax in the SAPIENT schema. Use a current release; the dissector is tested with Wireshark 4.6.

If something else fails to decode, open an issue and attach a sanitised capture if you can.