NetCalyx is a fork of NetGauze, licensed under Apache-2.0. See NOTICE for attribution and AUTHORS for the author list.
NetCalyx 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.
NetCalyx 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.
- Packet representation and wire format serialization/deserialization:
netcalyx-bgp-pkt - BGP Speaker with connection management and finite-state machine (FSM):
netcalyx-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).
- Packet representation and wire format serialization/deserialization:
netcalyx-bmp-pkt - Support for BMP v3 and v4, including all message types and peer states.
- Service building block for receiving BMP messages:
netcalyx-bmp-service
- Packet representation and wire format serialization/deserialization:
netcalyx-flow-pkt - Service building block for receiving messages:
netcalyx-flow-service
Information Elements are generated at build time by
netcalyx-ipfix-code-generator from the IANA registry, together with
enterprise-specific IEs (VMware, Nokia, NetCalyx).
- Packet representation and wire format serialization/deserialization:
netcalyx-udp-notif-pkt - Service building block for receiving messages:
netcalyx-udp-notif-service
- Data models and YANG validation:
netcalyx-yang-push
- Protocol types, XML parsing, and SSH client wiring:
netcalyx-netconf-proto
netcalyx-collector is a network telemetry collector that ties the protocol libraries
together into a deployable service.
Inputs: IPFIX/NetFlow V9, YANG-Push (UDP-Notif), and BMP. Enrichment data can be fed from Kafka and from files.
Publishers: Kafka (JSON, Avro, YANG) and HTTP
Features:
- Flow aggregation and enrichment
- YANG-Push message validation and YANG schema registration in a Schema Registry
- OpenTelemetry metrics export (OTLP)
- jemalloc memory allocator for production workloads
- YAML-based configuration with per-module log filtering
- RPM and DEB packaging support
cargo run --package netcalyx-collector -- /path/to/config.yamlSee example configurations in crates/collector/.
netcalyx-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 --package netcalyx-pcap-decoder -- --protocol bmp --ports 11019 --input input.pcap --output output.jsonlnetcalyx-pcap-tools — CLI utilities to manipulate PCAP files containing network
telemetry protocols (e.g. bmp-split to rewrite a BMP capture so that each TCP segment carries exactly one BMP message).
cargo run --package netcalyx-pcap-tools -- bmp-split --input in.pcap --output out.pcap --ports 1790netcalyx-yang-consumer — CLI tool that consumes YANG-encoded messages from
Kafka and validates them against YANG schemas fetched from a Schema Registry.
cargo run --package netcalyx-yang-consumer -- --helpThese crates provide shared infrastructure used across the protocol libraries:
| Crate | Purpose |
|---|---|
netcalyx-iana |
IANA registry constants for address families, capabilities, etc. |
netcalyx-parse-utils |
Traits and helpers for nom-based protocol parsing |
netcalyx-serde-macros |
Procedural macros for error location tracking in parsers |
netcalyx-locate |
Binary span types for tracking byte positions during parsing |
netcalyx-analytics |
Analytics and aggregation primitives |
netcalyx-pcap-reader |
Simple PCAP reader used by the tests and the PCAP tools |
Add the crate you need to your Cargo.toml:
[dependencies]
netcalyx-bgp-pkt = "0.3"Parse a BGP message from bytes:
use netcalyx_bgp_pkt::BgpMessage;
use netcalyx_bgp_pkt::wire::deserializer::BgpParsingContext;
use netcalyx_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();NetCalyx 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
NetCalyx 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 testcargo +nightly fmt
cargo +nightly clippy --tests -- -Dclippy::all# List available examples
ls crates/*/examples
# Run the IPFIX/NetFlow printer
cargo run --package netcalyx-flow-service --example print-flowBenchmarks use criterion and live under crates/*/benches. Some crates gate them
behind a feature (e.g. bench for netcalyx-bgp-pkt), see the crate's Cargo.toml and README.
To compare a branch against main, save a baseline on main and compare against it on the branch. Always pass
--bench <name> when using criterion options, otherwise the libtest harness of the lib target rejects them.
git checkout main
cargo bench --package netcalyx-bgp-pkt --features bench --bench serde_benchmark -- --save-baseline main
git checkout <branch>
cargo bench --package netcalyx-bgp-pkt --features bench --bench serde_benchmark -- --baseline mainRun both on an idle machine back to back; differences of a few percent are usually noise.
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-ipfix-pkt-serialize
cargo +nightly fuzz run fuzz-netflow-v9-pkt
cargo +nightly fuzz run fuzz-netflow-v9-pkt-serialize
cargo +nightly fuzz run fuzz-flow-codec
cargo +nightly fuzz run fuzz-udp-notif-pkt
cargo +nightly fuzz run fuzz-udp-notif-pkt-serialize
cargo +nightly fuzz run fuzz-netconfRPM:
cargo install cargo-generate-rpm
cargo build --release -p netcalyx-collector
strip target/release/netcalyx-collector
cargo generate-rpm -p crates/collector --auto-req find-requires
# Package output: target/generate-rpm/DEB:
cargo install cargo-deb
cargo build --release -p netcalyx-collector
cargo deb -p netcalyx-collector --no-build
# Package output: target/debian/Pre-built packages and binaries for netcalyx-collector, netcalyx-pcap-decoder, netcalyx-pcap-tools and
netcalyx-yang-consumer are attached to the GitHub Releases.
Copyright (C) 2026-present The NetCalyx Authors. All rights reserved. Copyright (C) 2022-present The NetGauze Authors. All rights reserved.
NetCalyx 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.
See the AUTHORS file; see also the full contributor graph.
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.
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.