NetGauze: Weaving network protocols into one toolkit

NetGauze is a set of Rust libraries and programs for network monitoring, telemetry collection, and protocol analysis. It provides high-performance, type-safe packet parsing and serialization for key network protocols, along with a network telemetry collector daemon that can be used to collect and process telemetry data from multiple sources.

NetGauze leverages Rust's type system to ensure protocol correctness at compile time when possible — packets are represented as rich, immutable data structures where invalid states are unrepresentable.

Protocol Libraries

BGP

• Packet representation and wire format serialization/deserialization: netgauze-bgp-pkt
• BGP Speaker with connection management and fine-state-machine (FSM): netgauze-bgp-speaker

Supports BGP-4, MP-BGP (IPv4/IPv6 Unicast & Multicast, MPLS VPN, EVPN, BGP-LS), 4-octet ASN, Add-Path, Route Refresh, Extended Messages, and communities (standard, extended, large).

BMP

• Packet representation and wire format serialization/deserialization: netgauze-bmp-pkt
• Support for BMP v3 and v4, including all message types and peer states.
• Service building block for receiving BMP messages: netgauze-bmp-service

IPFIX and NetFlow V9

• Packet representation and wire format serialization/deserialization: netgauze-flow-pkt
• Service building block for receiving messages: netgauze-flow-service

Includes a code generator for IANA IPFIX Information Elements as well as support for enterprise-specific IEs (e.g., VMware, Nokia).

UDP-Notif

• Packet representation and wire format serialization/deserialization: netgauze-udp-notif-pkt
• Service building block for receiving messages: netgauze-udp-notif-service

YANG Push

• Data models and YANG validation: netgauze-yang-push

NETCONF

• Protocol types, XML parsing, and SSH client wiring: netgauze-netconf-proto

Collector Daemon

netgauze-collector is a network telemetry collector that ties the protocol libraries together into a deployable service.

Inputs: IPFIX/NetFlow V9, UDP-Notif, YANG Push, and Kafka for enrichment data, while BMP and BGP are currently work in progress.

Publishers: Kafka (Avro, JSON, YANG)

Features:

• Flow aggregation and enrichment
• OpenTelemetry metrics export (OTLP)
• jemalloc memory allocator for production workloads
• YAML-based configuration with per-module log filtering
• RPM packaging support

cargo run -p netgauze-collector -- /path/to/config.yaml

See example configurations in crates/collector/.

Tools

PCAP Decoder

netgauze-pcap-decoder — Swiss army knife CLI tool to decode BGP, BMP, IPFIX/NetFlow, and UDP-Notif from PCAP files into JSON Lines format.

cargo run -p netgauze-pcap-decoder -- --protocol bmp --ports 11019 input.pcap -o output.jsonl

Foundational Crates

These crates provide shared infrastructure used across the protocol libraries:

Quick Start

Add the crate you need to your Cargo.toml:

[dependencies]
netgauze-bgp-pkt = "0.9"

Parse a BGP message from bytes:

use netgauze_bgp_pkt::BgpMessage;
use netgauze_bgp_pkt::wire::deserializer::BgpParsingContext;
use netgauze_parse_utils::{ReadablePduWithOneInput, Span};

let raw: & [u8] = & [ /* BGP message bytes */ ];
let span = Span::new(raw);
let mut ctx = BgpParsingContext::default ();
let (_remaining, message) = BgpMessage::from_wire(span, & mut ctx).unwrap();

Design Principles

NetGauze follows a consistent architecture across all protocol crates, documented in docs/pdu_serde.md:

• Immutable PDUs — packets are immutable once constructed
• Enum-driven correctness — protocol constants are represented as enums so invalid values are caught at compile time
• Separated concerns — packet representation (*-pkt) is independent of wire format parsing (wire/) and service integration (*-service)
• Fuzz-tested — all protocol parsers are continuously fuzzed via cargo-fuzz

Development Documentation

Running Tests

NetGauze uses macro tests from the trybuild crate and PCAP-based regression tests.

# Standard test run
cargo test --features=codec

# Regenerate expected macro test output
TRYBUILD=overwrite cargo test

# Regenerate expected PCAP test output
OVERWRITE=true cargo test

Code Formatting and Linting

cargo +nightly fmt
cargo +nightly clippy --tests -- -Dclippy::all

Running Examples

# List available examples
ls crates/*/examples

# Run the IPFIX/NetFlow printer
cargo run -p netgauze-flow-service --example print-flow

Fuzz Testing

cargo install cargo-fuzz

cargo +nightly fuzz run fuzz-bgp-pkt
cargo +nightly fuzz run fuzz-bgp-pkt-serialize
cargo +nightly fuzz run fuzz-bgp-peer
cargo +nightly fuzz run fuzz-bmp-pkt
cargo +nightly fuzz run fuzz-bmp-pkt-serialize
cargo +nightly fuzz run fuzz-ipfix-pkt
cargo +nightly fuzz run fuzz-netflow-v9-pkt

Building RPMs

cargo install cargo-generate-rpm
cargo build --release -p netgauze-collector
strip target/release/netgauze-collector
cargo generate-rpm -p crates/collector
# Package output: target/generate-rpm/

License

Copyright (C) 2022-present The NetGauze Authors. All rights reserved.

NetGauze is licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0). Attribution notices are in NOTICE. The author list is in AUTHORS.

Authors

NetGauze was created by Ahmed Elhassany (@ahassany), originally started in 2019 as a BGP library. It has since evolved into a full-fledged network telemetry toolkit with contributions from many individuals. The current author list is maintained in AUTHORS; see also the full contributor graph.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.