falco_event_serde/
lib.rs

1//! # Serde support for Falco events
2//!
3//! This crate provides serialization and deserialization support for Falco events using Serde.
4//! The serialized format is as follows (using JSON as an example):
5//!
6//! ```json
7//! {
8//!     "ts": 1700000000,     // timestamp in nanoseconds since epoch
9//!     "tid": 12345,         // thread ID
10//!     "GENERIC_E": {        // event type name (as enum variant name)
11//!         "id": 1,          // event parameters
12//!         "native_id": 1001
13//!     }
14//! }
15//! ```
16//!
17//! The event names correspond to variants of [`falco_event_schema::events::AnyEvent`] (i.e.,
18//! with the `PPME_` prefix removed).
19//!
20//! ## Serialization rules for different parameter types
21//!
22//! * Integers (`PT_UINT*`, `PT_INT*`, etc.) and newtype wrappers (`PT_SYSCALLID` etc.) are
23//!   serialized as numbers.
24//!
25//! * Bit flags (`PT_FLAGS*`) and enum flags (`PT_ENUMFLAGS*`) are serialized as numbers, using
26//!   the underlying integer value.
27//!
28//! * Relative timestamps (`PT_RELTIME`) are serialized as the number of nanoseconds in the interval.
29//!
30//! * Absolute timestamps (`PT_ABSTIME`) are serialized as the number of nanoseconds since the epoch.
31//!
32//! * File descriptor lists (`PT_FDLIST`) are serialized as arrays of tuples containing two integers
33//!   for the file descriptor (`u64`) and its associated flags (`PT_FLAGS16_file_flags`).
34//!
35//! * Strings, byte buffers and file paths (`PT_CHARBUF`, `PT_BYTES`, `PT_FSPATH`, `PT_FSRELPATH`)
36//!   are serialized as strings if they contain valid UTF-8 and the serializer marks itself
37//!   as human-readable (e.g., JSON), or as a byte array otherwise.
38//!
39//! * Strings inside arrays of strings (`PT_CHARBUFARRAY`) are serialized with the logic above.
40//!
41//! * Arrays of string pairs (`PT_CHARBUF_PAIR_ARRAY`) are serialized as arrays of tuples (*not*
42//!   as maps) containing two strings, serialized using the same logic as all other strings.
43//!
44//! * Dynamic fields (`PT_DYN*`) are serialized as an enum (using the default externally tagged
45//!   representation).
46//!
47//! *  Socket addresses (`PT_SOCKADDR`) are serialized in different formats, depending on the address
48//!    family:
49//!    * `AF_UNIX`: a string for the path
50//!    * `AF_INET`, `AF_INET6`: a tuple of `ip` (as a string) and `port` (as a number)
51//!    * other: a tuple of a single byte for the address family and a string (or byte array if not
52//!      valid UTF-8) for the address
53//!
54//! * Socket tuples (`PT_SOCKTUPLE`) are serialized depending on the address family:
55//!   * `AF_UNIX`: a tuple of two integers for the source and destination pointers and a string
56//!     for the path
57//!   * `AF_INET`, `AF_INET6`: a tuple of four items: source IP (as a string), source port
58//!     (as a number), destination IP (as a string), and destination port (as a number)
59//!   * other: like `PT_SOCKADDR`
60#![warn(missing_docs)]
61pub mod de;
62pub mod ser;
63
64#[doc(hidden)]
65pub use falco_event_schema::fields;
66
67#[doc(hidden)]
68pub use falco_event_schema::ffi;
falco_event_serde/lib.rs

falco_event_serde/
lib.rs
