Deploying Edgeshark for Docker Network Packet Capture

Overview

Edgeshark is an open-source container observability stack developed and maintained by Siemens under the siemens/edgeshark GitHub organization. It provides two cooperating services that expose the live network topology of a Linux Docker host and enable remote packet capture from a desktop Wireshark installation. The project targets engineers running containerized workloads at the network edge, including industrial IoT gateways, OT/IT bridging hosts, and developer workstations emulating industrial edge environments.

Edgeshark is delivered as a pair of container images that cooperate with the Wireshark extcap plugin named csharg. The containerized side enumerates Docker networks, virtual Ethernet (veth) pairs, and bridge interfaces; the desktop side launches Wireshark and tunnels the capture stream through an SSH connection. Together the components replace the manual workflow of binding tcpdump into a sidecar container, copying .pcap files off the host, and correlating interface names to container identities by hand.

Architecture and Components

An Edgeshark deployment consists of three runtime elements: a discovery/packet-capture service, a preferences service, and the csharg extcap plugin that runs on the analyst workstation. Communication between the workstation plugin and the container side uses a private SSH key generated on first launch.

The container side inspects the host's /proc/net/dev file and the Docker engine API (default unix:///var/run/docker.sock) to discover veth interfaces that connect each container namespace to the host bridge (typically docker0 or a user-defined bridge such as br-7f3a…). When a capture is requested, Edgeshark attaches tcpdump to the appropriate veth and streams the encoded PCAP-NG stream back over the SSH tunnel.

Prerequisites

Before deploying Edgeshark, verify that the target host and analyst workstation meet the following requirements.

Docker host requirements

• Linux kernel 4.9 or newer (kernel 5.10+ recommended for proper BPF and veth statistics).
• Docker Engine 20.10+ with the default bridge networking driver or a user-defined bridge.
• At least 256 MB of free RAM for the Edgeshark services and additional headroom equal to the working-set of the largest container you intend to capture.
• SSH connectivity from the analyst workstation to the Edgeshark capture port (default 22 on the host network namespace, forwarded to the container).

Analyst workstation requirements

• Wireshark 3.6 or 4.0+. The csharg plugin is bundled with the release artifacts in the siemens/edgeshark repository.
• OpenSSH client (ssh, ssh-keygen) in PATH.
• For Linux workstations, setcap cap_net_raw,cap_net_admin+ep $(which dumpcap) is not required because capture is performed remotely; however, the local wireshark binary must still be able to spawn the extcap helper.

Network reachability

Open TCP/22 (or any port you map during deployment) between the workstation and the Docker host. Industrial sites that segment the engineering workstation VLAN from the OT VLAN should route the SSH port via the jump host used for vendor remote access.

Deployment Procedure

The reference deployment is a single docker-compose.yml file. The project repository publishes a ready-to-use compose file in the deployments directory of the siemens/edgeshark repository.

1. Create a project directory and download the compose file:

   mkdir -p ~/edgeshark && cd ~/edgeshark
   wget -q --no-cache -O docker-compose.yml \
     https://raw.githubusercontent.com/siemens/edgeshark/main/deployments/docker-compose/docker-compose.yml

2. Inspect the compose file. The default compose file starts two services on a shared edgeshark network and exposes the SSH capture port on host port 22 and the UI on host port 5000.
3. Start the stack:

   docker compose up -d
   docker compose ps

   The ps output should show both services in the running state.
4. Confirm the discovery API is reachable:

   curl -s http://localhost:5000/api/discover | jq .

   A JSON document containing the id, names, and networks of every container on the host is returned.
5. Retrieve the auto-generated SSH private key that the csharg plugin will use:

   docker compose exec edgeshark-discover cat /etc/edgeshark/id_ed25519

   Copy this key to the workstation path expected by csharg (see the plugin section below).

Wireshark Plugin Configuration

The csharg extcap plugin is the bridge between the Wireshark GUI and the Edgeshark capture backend. Install the plugin on the analyst workstation as follows.

1. Download the release archive that matches your Wireshark major version from the siemens/edgeshark releases page.
2. Extract the archive into the Wireshark extcap directory:
   • Linux: ~/.local/lib/wireshark/extcap/ or /usr/lib/x86_64-linux-gnu/wireshark/extcap/
   • macOS: ~/.config/wireshark/extcap/
   • Windows: %APPDATA%\Wireshark\extcap\
3. Mark the csharg binary as executable (chmod +x csharg on POSIX systems).
4. Place the private key retrieved in the previous section in ~/.config/wireshark/csharg_id_ed25519 with permissions 0600.
5. Restart Wireshark. The capture options dialog will now show a new interface named csharg.

When the capture is started, csharg opens an SSH session to the Edgeshark host, requests the list of available interfaces, and presents each container's veth as a selectable interface. Selecting a veth automatically populates the BPF filter with the container's MAC address so that unrelated traffic is suppressed before it is streamed back to the workstation.

Capturing Container Traffic

After Wireshark is configured, capture proceeds through a normal Wireshark workflow with the additional csharg interface.

1. Open Wireshark and select Capture → Options.
2. From the interface list, choose csharg and click Options next to it. Enter the host address, SSH port, and container name filter.
3. Apply a display filter such as mqtt or opcua to focus on industrial protocol traffic.
4. Click Start. The status bar shows csharg: connected to container plc-runtime-1 when the tunnel is established.
5. Stop the capture with the red square button. The capture file is saved locally as PCAP-NG with per-interface link types, allowing post-capture replay through tshark or editcap.

Industrial Use Cases

Edgeshark's primary field of use is troubleshooting containerized industrial workloads. The following scenarios are common in production deployments.

Containerized PLC runtime capture

A Docker host running a soft-PLC such as the Siemens S7-PLCSIM Advanced instance, CODESYS Control for Raspberry Pi, or an open-source OpenPLC runtime often multiplexes multiple virtual PLCs on a single bridge. Edgeshark exposes each PLC's veth as a discrete capture interface, allowing the engineer to inspect S7comm or Modbus TCP traffic for a specific logical controller without mirroring the entire bridge.

OPC UA gateway inter-container inspection

An OPC UA gateway container typically publishes data from a south-bound protocol (S7, Modbus, EtherNet/IP) to a north-bound broker (MQTT, Kafka, AMQP). When the gateway behaves incorrectly, Edgeshark's web UI shows whether the connection between the gateway container and the broker container traverses a user-defined bridge, the default bridge, or a macvlan interface. The capture then confirms that the south-bound polling actually reaches the PLC by checking the S7comm service IDs in the trace.

Edge-to-cloud MQTT broker debugging

On edge hosts that publish telemetry to a cloud broker, Edgeshark can be co-located with the broker container to capture TLS handshakes. The SSH tunnel keeps the capture off the cloud network, which is critical when the broker container uses a self-signed certificate pinned by the application.

Network segmentation validation

Before commissioning an internal-only Docker network, an engineer can use Edgeshark's web UI to verify that no container has a published port that should remain private. The topology view displays every bridge, overlay, and macvlan attachment, including the auto-generated IPv6 link-local addresses that often expose services unintentionally.

Multi-Host and Cluster Considerations

Edgeshark is designed for a single Linux Docker host. Clustered environments require either multiple Edgeshark instances or alternative tooling.

• Docker Swarm. Deploy one Edgeshark stack per Swarm worker that runs the workloads of interest. Use Swarm's node.labels constraint to pin the Edgeshark services to the targeted node, then expose the capture SSH port only on the overlay IP of that node.
• Kubernetes. Edgeshark does not interpret CNI plugins such as flannel, calico, or cilium. For Kubernetes clusters, use a CNI-aware solution such as Wireshark on a hostPath mount of the node, or run Edgeshark inside a privileged DaemonSet that targets a single worker.
• Proxmox / LXC nested. An LXC privileged container with Docker installed and a routed bridge can host Edgeshark, but the veth names inside the LXC differ from the host. Map the LXC network namespace carefully and verify that ip link show inside the LXC shows the same veth pair that docker network inspect reports.

Security Hardening

Edgeshark exposes significant network visibility and must be treated as a privileged diagnostic tool. The following hardening steps are recommended for industrial environments.

1. Restrict SSH key access. Regenerate the auto-generated Edgeshark SSH key on first launch, store it on a hardware token, and remove it from the container when capture sessions are not active.
2. Network segmentation. Bind the Edgeshark UI and capture ports to a dedicated engineering VLAN. Do not expose port 5000 or 22 to the OT network.
3. Read-only file systems. Mount /etc/edgeshark and the SSH key directory as :ro when the analyst only needs to view topology without starting captures.
4. Disable internal:true discovery for production stacks by setting the EDGESHARK_NETWORK_FILTER environment variable to a comma-separated list of bridge names.
5. Audit logging. Enable Docker's log-driver: json-file with a size cap and forward the Edgeshark container logs to a central syslog server for forensic review.
6. TLS for the topology UI. Place Edgeshark behind a reverse proxy that terminates TLS, such as the nginx or traefik containers already common in industrial stacks.

Troubleshooting Matrix

Performance and Capacity Notes

Edgeshark streams captured frames over SSH and through a single veth. At a 1 Gbit/s link the bottleneck is the SSH encryption on the workstation, not Edgeshark itself. The following limits have been observed in field deployments.

• Up to 200 Mbit/s sustained capture when the workstation is a quad-core x86 with AES-NI enabled.
• Up to 50 containers simultaneously inspected in the topology view before the UI degrades; split the deployment across multiple Edgeshark instances for larger hosts.
• Capture files larger than 2 GB should be rotated with editcap -c 1000 (1000 MB) to keep Wireshark responsive.

Alternatives and When to Choose Them

Edgeshark is not the only Docker visibility tool. Pick the right instrument based on the engineering question being asked.

Frequently Asked Questions