Edgeshark

...or watch the recording of the Edgeshark class at SharkFest 2023 in Brussels, with quick start, Docker networking, the Edgeshark architecture, below the surface of Docker Desktop, and more:

Discover the virtual communication of containers in (Docker) container hosts, such as the Siemens Industrial Edge. And capture container traffic live from the comfort of your Desktop's Wireshark with a simple click. Edgeshark additionally is KinD-aware and supports further container engines, such as containerd.

Learn more about what Edgeshark has on offer from our Edgeshark online manual.

Quick Start

• plain Docker Host with docker compose v2
• plain Docker Host Without Composer – just Docker and bash.
• Siemens Industrial Edge

Docker Host

We provide multi-architecture Docker images for linux/amd64 and linux/arm64. First, ensure that you have the Docker compose plugin v2 installed. For Debian users it is strongly recommended to install docker-ce instead of docker.io packages, as these are updated on a regular basis.

Make sure you have a Linux kernel of at least version 4.11 installed, however we highly recommend at least kernel version 5.6 or later.

To expose service TCP port 5001 only on localhost:

wget -q --no-cache -O - \
  https://github.com/siemens/edgeshark/raw/main/deployments/wget/docker-compose-localhost.yaml \
  | docker compose -f - up

Warning

The following quick start deployments will expose TCP port 5001 (or 5500) also to clients external to your host. Make sure to have proper network protection in place.

To expose service TCP port 5001 to remote clients:

wget -q --no-cache -O - \
  https://github.com/siemens/edgeshark/raw/main/deployments/wget/docker-compose.yaml \
  | docker compose -f - up

To expose alternate service TCP port 5500 to remote clients (download and edit to export on a different host port, then deploy using your local composer file):

wget -q --no-cache -O - \
  https://github.com/siemens/edgeshark/raw/main/deployments/wget/docker-compose-5500.yaml \
  | docker compose -f - up

Finally, visit http://localhost:5001 and start looking around your container host virtual networking.

If you want to live capture traffic using Wireshark, please download the csharg extcap plugin for the OS/distribution and install it.

Docker Host Without Composer

Alternatively, a bash script can be used to bring the Edgeshark services up or down, without needing an installed docker compose plugin.

wget -q --no-cache -O - \
  https://github.com/siemens/edgeshark/raw/main/deployments/nocomposer/edgeshark.sh \
  | bash -s up

Siemens Industrial Edge

Please head over to our releases page to download the latest (and greatest) Edgeshark app (amd64 only at this time):

1. download the edgeshark.zip file.
2. unpack the downloaded ZIP archive.
3. import the edgeshark.app file into the catalog of your IEM.
4. deploy ... and enjoy!

If you want to live capture traffic using Wireshark, please download the csharg extcap plugin for the OS/distribution and install it. Please also check the cshargextcap installation instructions, especially for macos users regarding the additional packetflix URL handler installation.

Project Structure

The "Edgeshark" project consist of several repositories:

• 🖝 Edgeshark Hub repository 🖜
• G(h)ostwire discovery service
• Packetflix packet streaming service
• Containershark Extcap plugin for Wireshark
• support modules:
  • turtlefinder
  • csharg (CLI)
  • mobydig
  • ieddata

Working on the Manual

The Edgeshark manual uses docsify so there is no need for processing the documentation files first. Instead, they can be directly copied one-to-one to a place from where they can be served as-is, such as the Edgeshark live manual on github.com.

When working on the documentation, simply serve the manual artifacts as-is in order to see an automatically updating live "preview" (which actually is quite "what you see is what you get" in this case):

make docsify

When updating or adding icons in icons/_media/icons, make sure to optimize and sync them to docs/_media/icons:

sudo npm -g install svgo
make icons

Do not edit the icons in docs/_media/icons; edit only the "source" icons in icons/_media/icons.

Contributing

Please see CONTRIBUTING.md.

License and Copyright

(c) Siemens AG 2023, 2024

SPDX-License-Identifier: MIT