Ghostwire Virtual Communication Discovery

G(h)ostwire discovers the virtual (or not) network configuration inside Linux hosts – and can be deployed as a REST service or consumed as a Go module. It comes with its unique container engine discovery that auto-discovers multiple container engines in hosts, including engines inside containers. Ghostwire not only understands containers, but also Composer projects and Kubernetes pods.

Currently supported container engines are:

containerd,
Docker,
CRI-O,
podman – when set up to be socket-activated by systemd (see also podman Quick Start: Starting the service with systemd). Please note that we only support the Docker-compatible API, but not the podman-proprietary workload features, such as podman pods.

Ghostwire is also Kubernetes-aware and even understands that KinD simulates Kubernetes nodes in Docker containers.

Quick Start

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.

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

Finally, visit http://localhost:5000 and start looking around the virtual container networking, IP and DNS configuration, open and forwarded ports, and much more.

⚠ This quick start deployment will expose TCP port 5000 also to clients external to your host. Make sure to have proper network protection in place.

Eye Candy!

Lots of Virtual "Wires"

A slightly busy Industrial Edge host:

IP & DNS Configuration

...lots of gory configuration details:

For instance: container/process capabilities, with Docker non-standard capabilities being highlighted. Open and connected ports, and forwarded ports, all with the containers and processes serving them. Other Docker containers addressable from your container using DNS names for Docker services and containers.

See the Current System State

Information is gathered as much as possible from Linux APIs in order to show the current effective state, instead of potentially invalid or stale engineering configuration. Container engines are only queried in order to understand which processes and network elements have a user-space meaning beyond the kernel-space view.

Teaming up Ghostwire with Packetflix makes Wireshark container-aware: a simple click on one of the "shark fin" buttons starts a Wireshark session, directly capturing network traffic inside a container (or even KinD pod).

Edgeshark Project Context

ghostwire/v2 is part of the "Edgeshark" project that consist of several repositories:

Edgeshark Hub repository
🖝 G(h)ostwire discovery service 🖜
Packetflix packet streaming service
Containershark Extcap plugin for Wireshark
support modules:

Documentation

For deployment, usage and development information, please see the accompanying documentation in docs/. The most convenient way to view this documentation is with the help of docsify:

make docsify

Then navigate to http://localhost:3300 to read on.

Build & Deploy

Building the Packetflix service requires the Go toolchain, make, a C compiler (used by cgeo), and finally Docker installed.

The preferred build method is as a containerized service. For development, a standalone binary as well as the webui assets can be built outside of any container.

IMPORTANT: the Ghostwire service exposes (read-only) host information on port 5000. Never expose this services without taking additional security measures.

Container Service

To build and deploy the Gostwire containerized service and exposing it at port 5000 of the host (requires the build(x) plugin to be installed, which is GA on Linux for some time now):

make deploy

Alternatively, you can build and deploy a pprof-enabled service, which enables pprof information at :5000/debug/pprof.

make pprofdeploy

For more information, please refer to the (docsified) documentation in docs/.

Standalone Service Binary

ensure that Go 1.20 (or later) is installed.
ensure that nodejs 16+, npm, and yarn (npm install --global yarn) are installed.

make yarnsetup # if not done already so
make build-embedded
./gostwire --debug

VSCode Tasks

The included gostwire.code-workspace defines the following tasks:

View Go module documentation task: installs pkgsite, if not done already so, then starts pkgsite and opens VSCode's integrated ("simple") browser to show the csharg documentation.

Aux Tasks

pksite service: auxilliary task to run pkgsite as a background service using scripts/pkgsite.sh. The script leverages browser-sync and nodemon to hot reload the Go module documentation on changes; many thanks to @mdaverde's Build your Golang package docs locally for paving the way. scripts/pkgsite.sh adds automatic installation of pkgsite, as well as the browser-sync and nodemon npm packages for the local user.
view pkgsite: auxilliary task to open the VSCode-integrated "simple" browser and pass it the local URL to open in order to show the module documentation rendered by pkgsite. This requires a detour via a task input with ID "pkgsite".

Make Targets

make: lists all targets.
make dist: builds snapshot packages and archives of the csharg CLI binary.
make pkgsite: installs x/pkgsite, as well as the browser-sync and nodemon npm packages first, if not already done so. Then runs the pkgsite and hot reloads it whenever the documentation changes.
make report: installs @gojp/goreportcard if not yet done so and then runs it on the code base.
make vuln: install (or updates) govuln and then checks the Go sources.

Contributing

Please see CONTRIBUTING.md.

License and Copyright

SPDX-License-Identifier: MIT

siemens / ghostwire