mirror of
https://github.com/moby/moby.git
synced 2026-01-11 18:51:37 +00:00
ebfafa1561
Contribute a Wireshark plugin for decrypting and dissecting hashicorp/memberlist messages. And contribue a plugin for dissecting the NetworkDB messages transported as memberlist User messages. Add a feature to NetworkDB to log the encryption keys to a file for the Wireshark memberlist plugin to consume, configured using an environment variable. Signed-off-by: Cory Snider <csnider@mirantis.com>
112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
Wireshark Dissectors for NetworkDB
|
|
==================================
|
|
|
|
`memberlist.lua` is a [Wireshark][] plugin
|
|
which registers a `memberlist` protocol
|
|
that can dissect the [memberlist][] TCP and UDP protocols.
|
|
The `memberlist` protocol can be configured to dissect user data
|
|
as the protocol named in the `memberlist.userdata_dissector` preference.
|
|
|
|
`moby-networkdb.lua` is a Wireshark plugin which registers
|
|
a protocol named `networkdbgossip`
|
|
that dissects NetworkDB gossip messages.
|
|
As node-to-node communications for NetworkDB
|
|
are transported as memberlist user messages,
|
|
the memberlist protocol dissector must be configured
|
|
to invoke the networkdbgossip protocol as a sub-dissector.
|
|
(Read: set the preference `memberlist.userdata_dissector:networkdbgossip`)
|
|
|
|
Installation
|
|
------------
|
|
|
|
### Install Wireshark 4.5 or newer.
|
|
Wireshark 4.4 has an incomplete msgpack protocol dissector
|
|
that is unable to properly decode memberlist messages.
|
|
As of 2025-06-30 Wireshark 4.5 has yet to be released.
|
|
A [nightly build][ws.dl] may be required.
|
|
|
|
### Install the plugins
|
|
Configure Wireshark/Tshark to load `memberlist.lua` and `moby-networkdb.lua`.
|
|
Refer to [the Wireshark Lua manual][ws.lua.intro] for further instruction.
|
|
|
|
### Configure the ProtoBuf protocol
|
|
|
|
NetworkDB messages are serialized to protobuf,
|
|
which is not self-describing.
|
|
The ProtoBuf Wireshark protocol needs to be supplied with
|
|
the protobuf IDL definitions of the messages
|
|
in order to dissect them.
|
|
|
|
1. Clone [moby/moby][] for the NetworkDB IDL definitions.
|
|
2. Clone [protocolbuffers/protobuf][] for the protobuf "standard library" IDL.
|
|
3. Configure the ProtoBuf protocol (Preferences -> Protocols -> ProtoBuf)
|
|
as follows:
|
|
- ✅ Load .proto files on startup. (`protobuf.reload_protos`)
|
|
- ✅ Dissect Protobuf fields as Wireshark fields. (`protobuf.pbf_as_hf`)
|
|
- Add entries to the Protobuf Search Paths table (`uat:protobuf.search_paths`):
|
|
- path/to/protocolbuffers/protobuf/src
|
|
- path/to/moby/moby/vendor
|
|
- path/to/moby/moby
|
|
- path/to/moby/moby/libnetwork/networkdb (✅ Load all files)
|
|
- path/to/moby/moby/libnetwork/drivers/overlay (✅ Load all files)
|
|
|
|
Note that it is not sufficient to just grab the .proto files from the repos.
|
|
The directory structure is necessary for the definitions to load properly.
|
|
|
|
### Configure the Memberlist protocol
|
|
|
|
Configure memberlist to dissect user data messages as NetworkDB gossip.
|
|
- In Preferences -> Protocols -> MEMBERLIST,
|
|
set the User Data Dissector to `networkdbgossip`.
|
|
(`memberlist.userdata_dissector`)
|
|
- Optional: set Memberlist TCP+UDP port(s) (`memberlist.ports`) as needed.
|
|
E.g. a value such as `7946,10000-10999` would be useful
|
|
for analyzing packet captures from NetworkDB unit tests.
|
|
|
|
Usage Notes
|
|
-----------
|
|
|
|
### Encryption
|
|
|
|
The memberlist protocol dissector supports decryption
|
|
of encrypted memberlist messages
|
|
when provided with a file containing the encryption keys used.
|
|
In Preferences -> Protocols -> MEMBERLIST,
|
|
set the Encryption Key Logfile Path
|
|
(`memberlist.keylog`)
|
|
to a file containing the encryption keys.
|
|
|
|
The logfile should list the encryption keys
|
|
as hexadecimal strings, delimited by newlines.
|
|
|
|
dockerd may be configured to write the NetworkDB encryption keys to a logfile
|
|
by setting the environment variable `NETWORKDBKEYLOGFILE`
|
|
to the path where the file should reside.
|
|
|
|
### Known Issues
|
|
|
|
The NetworkDB protocol may fail to load with an error when Wireshark is first started:
|
|
|
|
moby-networkdb.lua:4: bad argument #1 to 'new'
|
|
(Field_new: a field with this name must exist)
|
|
|
|
This is due to [a known issue in Wireshark.](https://gitlab.com/wireshark/wireshark/-/issues/20161)
|
|
|
|
Workaround: reload Lua plugins after Wireshark has been initialized.
|
|
|
|
- Menu: Analyze -> Reload Lua Plugins, or
|
|
- Keyboard shortcut: Ctrl-Shift-L (Windows/Linux), ⇧⌘L (macOS)
|
|
|
|
### Limitations
|
|
|
|
- Only memberlist encryption version 1 (AES-GCM 128, no padding) is supported,
|
|
not version 0 (AES-GCM 128 using PKCS#7 padding).
|
|
- Labelled messages cannot currently be decrypted.
|
|
|
|
[memberlist]: https://github.com/hashicorp/memberlist
|
|
[Wireshark]: https://wireshark.org
|
|
[ws.dl]: https://www.wireshark.org/download/automated/
|
|
[ws.lua.intro]: https://www.wireshark.org/docs/wsdg_html_chunked/wsluarm.html#wsluarm_intro
|
|
[moby/moby]: https://github.com/moby/moby
|
|
[protocolbuffers/protobuf]: https://github.com/protocolbuffers/protobuf
|