iris_core/
lib.rs

1#![allow(clippy::needless_doctest_main)]
2// #![warn(missing_docs)]
3
4//! A framework for developing high speed network traffic analysis applications that run on commodity hardware.
5//!
6//! Iris provides a high-level interface for analyzing five-tuple-defined network connections, including
7//! reassembled payloads and parsed application-layer sessions, from an in-network vantage point.
8//!
9//! Iris developers interact with network connections by defining subscriptions.
10//! Each subscription consists of one or more data types (data to analyze), a filter (traffic of interest),
11//! and a callback (analysis code). Each application can consist of one or more subscriptions.
12//!
13//! For simple use-cases, Iris provides built-in data types in the Iris (built-in) data types crate and
14//! a Wireshark-like filter DSL documented in the Iris compiler crate.
15//! For example, only a few lines of code are needed to capture HTTP requests with a specific user agent:
16//!
17//! ```rust,ignore
18//! #[callback("http.user-agent contains 'Mozilla'")]
19//! fn log_http(http: &HttpRequest, ft: &FiveTuple) {
20//!     log::info!("{}: {}", ft.src_subnet(24), http);
21//! }
22//! ```
23//!
24//! For more complex use-cases, Iris developers can define custom filters and data types, as well as stateful
25//! and streaming callbacks.
26//!
27//! Iris processes packets in a connection as they arrive, advancing connections through a set
28//! of protocol state machines. Developers can hook into states and state transitions to extract
29//! data, perform additional computation, or attach state for later use.
30//! The currently-supported states are documented in [`crate::conntrack::conn_state::StateTransition`].
31//! Developers indicate that a struct, type, or function should hook into Iris using the macros exported by
32//! the Iris compiler crate.
33//!
34//! For example, we can define a data type that extracts features from the body of a connection:
35//!
36//! ```rust,ignore
37//! #[datatype]
38//! struct FeatureChunk { /* ... */}
39//!
40//! impl FeatureChunk {
41//!     fn new(first_pkt: &L4Pdu) -> Self { /* ... */}
42//!
43//!     #[datatype_fn("FeatureChunk,InL4Conn")]
44//!     fn update(&mut self, pdu: &L4Pdu) {
45//!         /* ... */
46//!     }
47//! }
48//! ```
49//!
50//! Iris compiles user-defined subscriptions with framework functionality into a connection processing
51//! and analysis pipeline, as described in [the paper](https://thearossman.github.io/files/iris.pdf).
52//! When compiling an application, Iris prints out the "action trees" (mapping from filter predicates to
53//! incremental processing steps) that it will apply at each state transition. We recommend using this as
54//! a sanity check for application behavior.
55
56#[macro_use]
57mod timing;
58pub mod config;
59pub mod conntrack;
60#[doc(hidden)]
61#[allow(clippy::all)]
62mod dpdk;
63pub mod filter;
64pub mod lcore;
65pub mod memory;
66pub mod multicore;
67mod port;
68pub mod protocols;
69mod runtime;
70pub mod stats;
71#[doc(hidden)]
72pub mod subscription;
73pub mod utils;
74
75pub use self::conntrack::conn_id::{ConnId, FiveTuple};
76pub use self::conntrack::pdu::L4Pdu;
77pub use self::conntrack::{StateTransition, StateTxData};
78pub use self::lcore::CoreId;
79pub use self::memory::mbuf::Mbuf;
80pub use self::runtime::Runtime;
81
82pub use dpdk::rte_lcore_id;
83pub use dpdk::rte_rdtsc;
84
85#[macro_use]
86extern crate pest_derive;
87#[macro_use]
88extern crate lazy_static;
89#[macro_use]
90extern crate maplit;
iris_core/lib.rs

iris_core/
lib.rs
