Skip to content

Latest commit

 

History

History
158 lines (121 loc) · 7.22 KB

README.md

File metadata and controls

158 lines (121 loc) · 7.22 KB
Raw

Siemens Industrial Edge Edgeshark

Containershark Extcap Plugin for Wireshark

PkgGoDev GitHub build and test Go Report Card

Important

Wireshark 4.4.0 is not supported as it breaks extcaps such as this one. Wireshark 4.4.1 scheduled for Oct 9th 2024 will contain two fixes so that this extcap plugin will be able to correctly work again.

Take a deep dive into your container host virtual networking, even if it's in a remote location. No fiddling with special containers and juggling error-prone CLI Docker commands. Simply click on a "fin" capture button inside one of the containers in Ghostwire's web UI to start a Wireshark live capture session:

Click the Fin!

Confirm and we're live capturing.

What You See Is What You Get

  • Capture network traffic live from your containers (and pods), straight into your Desktop Wireshark on Linux and Windows.

  • Capture from any container without preparing or modifying it for capturing. Just go capturing.

  • Supports stand-alone container hosts, including the Siemens Industrial Edge.

  • Remotely capture not only from containers, but also from the container host itself, process-less network namespaces, et cetera.

  • this Wireshark plugin can be build for Windows 64bit (x86) as well as Linux 64bit (x86, ARM). Currently, we support the .apk, .deb, and .rpm package formats on Linux.

Installation

  • Linux:

    • Alpine, Debian, Fedora: head over to our releases page and download the package matching your CPU architecture (amd64 or arm64) and distro package format. Install the downloaded package as usual.
    • Arch:
      1. download PKGBUILD into a preferably clean directory: 
        wget https://raw.githubusercontent.com/siemens/cshargextcap/main/packaging/aur/PKGBUILD
      2. makepkg -s -r -c in the directory you've downloaded PKGBUILD into.
      3. either install only the excapt plugin, or additionally the Wireshark QT desktop integration: 
        # plugin only for tshark usage, without desktop Wireshark dependency
pacman -U cshargextcap-git-cli*.zst
# with desktop integration
pacman -U cshargextcap-git-*.zst
      4. You can later update to new releases without the need to download the PKGBUILD file again, as it will automatically build and install from the latest release.

  • Mac OS: head over to our releases page and...

    1. download the .tar.gz archive for Darwin/macos arm64 or amd64 (Intel). Extract the contained cshargextcap plugin binary and copy/move it to /Applications/Wireshark.app/Contents/MacOS/extcap.
    2. download the packetflix-handler.zip archive.
    3. run the CLI command xattr -d com.apple.quarantine packetflix-handler.zip.
    4. unpack packetflix-handler.zip by double clicking it in Finder.
    5. copy packetflix-handler(.app) to your Applications folder, /Applications.
    6. go to "System Preferences" > "Security and Privacy" > tab "General" or "Security" section. Allow the packetflix-handler. In case you don't see anything here, try to start a capture from the web UI first, and as this will be blocked, you should now see here a notice with a button to enable the packetflix-handler.

  • Windows: head over to our releases page and download the ZIP archive for Windows amd64. Double click in file explorer to open its contents, then double click on the installer .exe. You don't need to extract the other files, as the installer perfectly works on its own.

See below for the Quick Start.

Project Map

The Containershark extcap plugin is part of the "Edgeshark" project that consist of several repositories:

Quick Start

Please deploy the G(h)ostwire discovery service and Packetflix packet streaming service on your Docker host.

Then install this plugin: on Windows download and install the cshargextcap installer artifact. On Linux, download and install the cshargextcap package for your distribution (apk, deb, or rpm). In case you want to create the installation files yourself, then simply run make dist in the base directory of this repository. Please note that this will also test install the packages in distro-specific test containers to ensure the distro packages are fine. Afterwards, installation files can be found in the dist/ directory.

Now fire up Wireshark. If the installation went through correctly, Wireshark now should show two new "interfaces", as shown below:

Container Live Capture

It's as easy as this:

  1. click the ⚙ gear icon next to the network interface named "Docker host capture".
  2. enter your Docker host's IP address or DNS name, as well as port :5001 into the field "Docker host URL".
  3. click the refresh button to get the list of available pods (and more...).
  4. pick your container.
  5. click the Start button.

...and your live capture starts immediately.

🛈 Wireshark creates the UI for our capture plugin and unfortunately we're therefore (quite) limited to what Wireshark has on offer. Please don't create UI/UX feature requests as we don't have any control over Wireshark's UI – with the exception of our own bugs: please create issues for them in this project's issue tracker.

Please find more details in our csharg Extcap ⚙ Plugin Manual.

Finally, there's also some technical background information in our csharg ⚙ Plugin Technical Details.

Contributing

Please see CONTRIBUTING.md.

License and Copyright

(c) Siemens AG 2023-24

SPDX-License-Identifier: MIT