Added NetflowCommon struct and doc. (#78)

* Added NetflowCommon.

---------

Co-authored-by: mikemiles-dev <[email protected]>

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "netflow_parser"
 description = "Parser for Netflow Cisco V5, V7, V9, IPFIX"
-version = "0.4.0"
+version = "0.4.1"
 edition = "2021"
 author = "[email protected]"
 license = "MIT OR Apache-2.0"

README.md

@@ -48,6 +48,42 @@ let parsed = NetflowParser::default().parse_bytes(&v5_packet);
 let v5_parsed: Vec<NetflowPacket> = parsed.into_iter().filter(|p| p.is_v5()).collect();
 ```
 
+## Netflow Common
+
+For convenience we have included a `NetflowCommon` structure.  This will allow you to use common
+Netflow fields without unpacking specific versions (fields like `src_port`, `dst_port`, etc.).  If the
+packet flow does not have the matching field it will simply be left as `None`.
+
+### Netflow Common fields:
+```
+src_addr: Option<IpAddr>,
+dst_addr: Option<IpAddr>,
+src_port: Option<u16>,
+dst_port: Option<u16>,
+protocol_number: Option<u8>,
+protocol_type: Option<ProtocolTypes>,
+first_seen: Option<u32>,
+last_seen: Option<u32>,
+```
+
+```rust
+use netflow_parser::{NetflowParser, NetflowPacket};
+
+let v5_packet = [0, 5, 0, 1, 3, 0, 4, 0, 5, 0, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3,
+    4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1,
+    2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7];
+let netflow_common = NetflowParser::default()
+                     .parse_bytes(&v5_packet)
+                     .first()
+                     .unwrap()
+                     .as_netflow_common()
+                     .unwrap();
+
+for common_flow in netflow_common.flowsets.iter() {
+    println!("Src Addr: {} Dst Addr: {}", common_flow.src_addr.unwrap(), common_flow.dst_addr.unwrap());
+}
+```
+
 ## Re-Exporting flows
 
 Netflow Parser now supports parsed V5, V7, V9, IPFix can be re-exported back into bytes.

RELEASES.md

@@ -1,3 +1,8 @@
+# 0.4.1
+ * Added NetflowCommon structure.  This acts as a helper for common Netflow Fields (like src_ip, src_port, etc).
+ * V5, V7 SysUpTime, First, Last times now u32 from Duration.
+ * IPFix export time u32 from Duration.
+
 # 0.4.0
  * NetflowPacketResult now simply NetflowPacket.
  * General parser cleanup and removal of uneeded code.

src/lib.rs

@@ -48,6 +48,42 @@
 //! let v5_parsed: Vec<NetflowPacket> = parsed.into_iter().filter(|p| p.is_v5()).collect();
 //! ```
 //!
+//! ## Netflow Common
+//!
+//! For convenience we have included a `NetflowCommon` structure.  This will allow you to use common
+//! Netflow fields without unpacking specific versions (fields like `src_port`, `dst_port`, etc.).  If the
+//! packet flow does not have the matching field it will simply be left as `None`.
+//!
+//! ### Netflow Common fields:
+//! ```ignore
+//! src_addr: Option<IpAddr>,
+//! dst_addr: Option<IpAddr>,
+//! src_port: Option<u16>,
+//! dst_port: Option<u16>,
+//! protocol_number: Option<u8>,
+//! protocol_type: Option<ProtocolTypes>,
+//! first_seen: Option<u32>,
+//! last_seen: Option<u32>,
+//! ```
+//!
+//! ```rust
+//! use netflow_parser::{NetflowParser, NetflowPacket};
+//!
+//! let v5_packet = [0, 5, 0, 1, 3, 0, 4, 0, 5, 0, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3,
+//!     4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1,
+//!     2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7];
+//! let netflow_common = NetflowParser::default()
+//!                      .parse_bytes(&v5_packet)
+//!                      .first()
+//!                      .unwrap()
+//!                      .as_netflow_common()
+//!                      .unwrap();
+//!
+//! for common_flow in netflow_common.flowsets.iter() {
+//!     println!("Src Addr: {} Dst Addr: {}", common_flow.src_addr.unwrap(), common_flow.dst_addr.unwrap());
+//! }
+//! ```
+//!
 //! ## Re-Exporting flows
 //! Netflow Parser now supports parsed V5, V7, V9, IPFix can be re-exported back into bytes.
 //! ```rust
@@ -97,11 +133,14 @@
 //!
 //! ```cargo run --example netflow_udp_listener_tokio```
 
+pub mod netflow_common;
 pub mod protocol;
 pub mod static_versions;
 mod tests;
 pub mod variable_versions;
 
+use crate::netflow_common::{NetflowCommon, NetflowCommonError};
+
 use static_versions::{v5::V5, v7::V7};
 use variable_versions::ipfix::{IPFix, IPFixParser};
 use variable_versions::v9::{V9Parser, V9};
@@ -145,6 +184,10 @@ impl NetflowPacket {
     pub fn is_error(&self) -> bool {
         matches!(self, Self::Error(_v))
     }
+
+    pub fn as_netflow_common(&self) -> Result<NetflowCommon, NetflowCommonError> {
+        self.try_into()
+    }
 }
 
 #[derive(Nom)]