retina_core/lib.rs
1#![allow(clippy::needless_doctest_main)]
2// #![warn(missing_docs)]
3
4//! An ergonomic framework for high speed network traffic analysis on commodity hardware.
5//!
6//! Retina provides a simple filter and callback interface that lets users subscribe to network
7//! traffic in real-time and run user-defined analysis code in a standard software environment. It
8//! is a passive analysis framework that supports access to network traffic at one of three
9//! abstraction levels:
10//!
11//! - Individual packets
12//! - Reassembled connections
13//! - Parsed application-layer sessions
14//!
15//! Retina is designed with a focus on performance in real-world, high-volume network environments
16//! (e.g., full-network or full-uplink analysis). It employs an efficient filtering mechanism to
17//! discard out-of-scope traffic, and is not specifically geared towards deep inspection of all
18//! packets (although it can be customized to do so). See [retina_filtergen](../retina_filtergen)
19//! for filter syntax and usage.
20//!
21//! The framework currently comes with built-in support for several [subscribable
22//! types](crate::subscription). Additional modules are welcome and encouraged.
23//!
24//! The following example shows a simple Retina application that prints parsed TLS handshakes to
25//! stdout:
26//!
27//! ```rust
28//! use retina_core::config::default_config;
29//! use retina_core::subscription::TlsHandshake;
30//! use retina_core::Runtime;
31//! use retina_filtergen::filter;
32//!
33//! #[filter("tls.sni ~ '^.*\\.com$'")]
34//! fn main() {
35//! let cfg = default_config();
36//! let callback = |tls: TlsHandshake| {
37//! println!("{:?}", tls);
38//! };
39//! let mut runtime = Runtime::new(cfg, filter, callback).unwrap();
40//! runtime.run();
41//! }
42//! ```
43//!
44
45#[macro_use]
46mod timing;
47pub mod config;
48mod conntrack;
49#[doc(hidden)]
50#[allow(clippy::all)]
51mod dpdk;
52// The filter module must be public to be accessible by the filter_gen procedural macro crate.
53// However, module functions should be opaque to users, so documentation is hidden by default.
54#[doc(hidden)]
55pub mod filter;
56mod lcore;
57mod memory;
58mod port;
59pub mod protocols;
60mod runtime;
61pub mod subscription;
62pub mod utils;
63
64pub use self::conntrack::conn_id::{ConnId, FiveTuple};
65pub use self::memory::mbuf::Mbuf;
66pub use self::runtime::Runtime;
67
68pub use dpdk::rte_lcore_id;
69pub use dpdk::rte_rdtsc;
70
71#[macro_use]
72extern crate pest_derive;
73#[macro_use]
74extern crate lazy_static;
75#[macro_use]
76extern crate maplit;