cshargextcap

package module
v0.10.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2024 License: MIT Imports: 14 Imported by: 0

README

Siemens Industrial Edge Edgeshark

Containershark Extcap Plugin for Wireshark

PkgGoDev GitHub build and test Go Report Card

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.

(c) Siemens AG 2023-24

SPDX-License-Identifier: MIT

Documentation

Overview

Starts a live capture session by opening a websocket stream to the capture service, and then piping the packet capture stream into the pipe (fifo) made available by Wireshark. This module has basically outsourced most of its functionality to the csharg standalone package for better re-use.

Additionally, also edits the beginning of the packet capture stream in order to insert meta data about the container capture origin, such as cluster identity, container identity, et cetera.

An external capture plugin for Wireshark for capturing network packets from inside containers (Docker, others) without having to prepare these containers for capturing. These containers can be deployed on single hosts, but also in Kubernetes clusters.

This OpenSource module implements capture clients for capturing from container hosts (including a KinD host). The following two extcap interfaces are implemented:

  • [MobyNif] connects to a capture service via http: and https: protocol URLs.
  • [PacketflixNif] connects to a capture service described by a packetflix: protocol URL. Under the hood, the packetflix: protocol encodes http: or https: URLs. The use case for packetflix: URLs is to allow easy hand-over from web-browser based UIs to Wireshark.

Index

Constants

View Source 
const (
	// HelpURL points to the help page for this external capture plugin;
	// when a Wireshark user clicks on the "help" button in the configuration
	// dialog for this plugin, then this web page will be navigated to.
	HelpURL = "https://github.com/siemens/cshargextcap"

	// ServiceDefaultPort is the default port of the Packetflix+GhostWire
	// capture service for streaming packet captures snatched up in containers.
	ServiceDefaultPort = int32(5001)
)
View Source 
const SemVersion = "0.9.2"

SemVersion is the semantic version string of the cshargextcap module.

Variables

This section is empty.

Functions

func Capture 

func Capture(st csharg.SharkTank) int

Capture is the workhorse: it opens the named pipe (fifo) offered by Wireshark, then starts a new Capture stream using the given SharkTank client and container target description. Then it lets csharg pump all packet Capture data arriving from the underlying websocket connected to the capture service into the Wireshark pipe.

func ExtcapCapture 

func ExtcapCapture() int

Implements the "--capture" action: it routes the capture action to the specified extcap network interface.

func ExtcapConfigure 

func ExtcapConfigure(w io.Writer) int

Wireshark wants either to know the configuration args for a specific extcap network interface, or it wants to update the value(s) of a specific single configuration arg of a network interface.

func ExtcapDlts 

func ExtcapDlts(w io.Writer) int

Lists the DLTs for a specific external capture network interface, by querying the specified (internally-registered) extcap nif, and finally correctly formatting the answer.

func ExtcapInterfaces 

func ExtcapInterfaces(w io.Writer) int

Lists the available (internally registered) external capture network interfaces.

func ExtcapNifNames 

func ExtcapNifNames() []string

ExtcapNifNames returns the list of names of the registered external capture network interfaces. The names in the returned list are in no particular order.

func ReloadContainerNifs 

func ReloadContainerNifs(w io.Writer)

ReloadContainerNifs reloads the list of network interfaces of a specific container. That is, it refreshes the list of the interface selector config arg. This helper is exported so additional extcaps can make use of it.

Types

type ExtcapNif 

type ExtcapNif struct {
	// contains filtered or unexported fields
}

ExtcapNif represents an individual, named external capture network interface.

func NewExtcapNif 

func NewExtcapNif(name string, description string) ExtcapNif

func (*ExtcapNif) Description 

func (e *ExtcapNif) Description() string

Description returns the short description of an external capture network interface.

func (*ExtcapNif) Name 

func (e *ExtcapNif) Name() string

Name returns the (guess what!) name of an external capture network interface. Surprise, surprise. Go for petty GoDoc rules.

type ExtcapNifActions 

type ExtcapNifActions interface {
	Name() string              // name of extcap network interface
	Description() string       // short description
	DLTs() []ExtcapNifDLT      // data-link layer encapsulation data type
	Configure(w io.Writer) int // dump configuration options
	ReloadOption(w io.Writer)  // dump up-to-date value(s) of specific configuration options
	Capture() int              // start packet capture
}

ExtcapNifActions represents the actions that can be carried out on external capture network interfaces. These actions reflect the actions Wireshark signals to external capture plugins when invoking them. The only additional "internal" action here is returning the name of a specific external capture interface, which is used for looking up --ext-interface arguments.

func ExtcapNifByName 

func ExtcapNifByName(name string) (ExtcapNifActions, bool)

ExtcapNifByName returns the external capture network interface with the specified name. Please note that capture network interfaces need to register their ExtcapNifActions implementation in the plugger group typed as ExtcapNifActions.

type ExtcapNifDLT 

type ExtcapNifDLT struct {
	Number  int    // DLT number
	Display string // display string for this DLT
}

ExtcapNifDLT describes a single DLT in terms of its number and description.

Source Files

View all Source files

Directories

Path Synopsis
Package cfg defines the ID numbers as well as descriptions of config arguments used in the extcap configuration dialogs.
 Package cfg defines the ID numbers as well as descriptions of config arguments used in the extcap configuration dialogs.
cli
action
Package action implements the handling of Wireshark's extcap CLI action flag.
 Package action implements the handling of Wireshark's extcap CLI action flag.
all
Package all ensures to pull in the required packages for (obscure) CLI args as well as the set of extcap implementations
 Package all ensures to pull in the required packages for (obscure) CLI args as well as the set of extcap implementations
cliplugin
Package cliplugin defines the plugin group types for setting up the extcap plugin CLI args in a modular way.
 Package cliplugin defines the plugin group types for setting up the extcap plugin CLI args in a modular way.
debug
Package debug implements the “--debug” and “--debug-file” CLI args.
 Package debug implements the “--debug” and “--debug-file” CLI args.
proxy
show
target
wireshark
cmd
cshargextcap
internal
gen/version
Package nif implements the “moby” and “packetflix” extcap network interfaces for Wireshark.
 Package nif implements the “moby” and “packetflix” extcap network interfaces for Wireshark.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.