icsnpp-mpls

Build Status

build-and-test

ICSNPP-MPLS

ICSNPP-MPLS adds MPLS label-stack parsing and logging to Zeek's suite of Industrial Control Systems network protocol parsers. It improves network visibility by decoding MPLS headers that would otherwise remain unlogged.

Overview

This Zeek plugin adds logging for MPLS label stacks. It registers a packet analyzer for MPLS unicast traffic (EtherType 0x8847) carried directly over Ethernet or inside a VLAN, extracts every label in the MPLS stack, and writes the decoded fields to mpls_header.log.

After processing the label stack, the plugin forwards the remaining payload to Zeek's IP analyzer so that normal connection and protocol analysis can continue. The plugin assumes that the payload following the MPLS stack is an IP packet.

Installation (via zkg)

Install the package directly from GitHub:

zkg install https://github.com/idaholab/icsnpp-mpls

If Zeek and zkg use a system-wide installation prefix, the command may need to be run with the permissions required by that installation. Restart any running Zeek processes after installation.

Confirm that Zeek can find the native plugin:

zeek -NN Zeek::MPLSLogging

From a repository checkout, process the included MPLS capture and inspect the decoded label stack:

zeek -C -r testing/Traces/mpls.pcap local
zeek-cut labels experimentals bottom_of_stack time_to_live < mpls_header.log

The capture contains one MPLS packet and produces:

18	0	T	254

To update or remove it later:

zkg upgrade icsnpp-mpls
zkg uninstall icsnpp-mpls

Installation (via git clone)

The manual build requires Zeek development files, zeek-config, a C++ compiler, and CMake 3.15 or newer. Ensure that the zeek-config belonging to the Zeek installation you intend to use is available on PATH.

git clone https://github.com/idaholab/icsnpp-mpls.git
cd icsnpp-mpls
./configure
cmake --build build
cmake --build build --target install

The final installation command may require sudo when installing into a system-owned Zeek prefix:

sudo cmake --build build --target install

Confirm the installation with:

zeek -NN Zeek::MPLSLogging

Log files

The plugin creates mpls_header.log and writes one record for every MPLS packet it processes.

Field Type Description
ts time Packet timestamp.
labels vector[count] MPLS labels, in their order in the label stack.
experimentals vector[count] Three-bit Traffic Class/Experimental value for each label.
bottom_of_stack vector[bool] Bottom-of-stack flag for each label; the final label is normally T.
time_to_live vector[count] TTL value for each label.

The values at the same position in each vector belong to the same MPLS label. For example, index zero in all four vectors describes the outermost label. After MPLS processing, logs such as conn.log may also contain records for the encapsulated IP traffic.

ICSNPP Packages

Additional ICSNPP protocol parsers are available from the ICSNPP project.

License

See LICENSE and NOTICE.txt.

Package Version :