Add basic, introductory examples for use

Cargo.toml

@@ -7,6 +7,8 @@ members = [
     # Exclude from compilation; many subscriptions takes a long time to compile
     # "examples/filter_stats",
     "examples/protocols",
+    "examples/basic",
+    "examples/basic_file",
 ]
 resolver = "2"
 

README.md

@@ -42,7 +42,7 @@ Fork or clone the main git repository:
 
 `git clone [email protected]:stanford-esrg/retina.git`
 
-Write your first Retina application (see [examples](https://github.com/stanford-esrg/retina/tree/main/examples) and [documentation](https://stanford-esrg.github.io/retina/retina_core/index.html)).
+Write your first Retina application (see [examples](https://github.com/stanford-esrg/retina/tree/main/examples); `basic` and `basic_file` are good starters).
 
 Writing a Retina application consists of defining one or more subscriptions. A subscription is defined by (1) [writing a filter](https://stanford-esrg.github.io/retina/retina_filtergen/index.html) to describe what subset of network traffic you're interested in, (2) choosing [data types to subscribe to](https://stanford-esrg.github.io/retina/retina_datatypes/index.html), and (3) defining a callback function that takes in a subscribable data type and performs operations on the filtered, delivered data.
 

examples/basic/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "basic"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+env_logger = "0.8.4"
+retina-core = { path = "../../core" }
+retina-filtergen = { path = "../../filtergen" }
+retina-datatypes = { path = "../../datatypes" }
+lazy_static = "1.4.0"
+serde = { version = "1.0", features = ["derive"] }
+regex = "1.7.3"

examples/basic/README.md

@@ -0,0 +1,3 @@
+# Basic
+
+An introductory example that logs TLS and DNS transactions, each with associated connection metrics.

examples/basic/src/main.rs

@@ -0,0 +1,24 @@
+use retina_core::{config::default_config, Runtime};
+use retina_datatypes::{ConnRecord, DnsTransaction, TlsHandshake};
+use retina_filtergen::{filter, retina_main};
+
+#[filter("tls")]
+fn tls_cb(tls: &TlsHandshake, conn_record: &ConnRecord) {
+    println!("Tls SNI: {}, conn. metrics: {:?}", tls.sni(), conn_record);
+}
+
+#[filter("dns")]
+fn dns_cb(dns: &DnsTransaction, conn_record: &ConnRecord) {
+    println!(
+        "DNS query domain: {}, conn. metrics: {:?}",
+        dns.query_domain(),
+        conn_record
+    );
+}
+
+#[retina_main(2)]
+fn main() {
+    let config = default_config();
+    let mut runtime: Runtime<SubscribedWrapper> = Runtime::new(config, filter).unwrap();
+    runtime.run();
+}

examples/basic_file/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "basic_file"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+env_logger = "0.8.4"
+retina-core = { path = "../../core" }
+retina-filtergen = { path = "../../filtergen" }
+retina-datatypes = { path = "../../datatypes" }
+lazy_static = "1.4.0"
+serde = { version = "1.0", features = ["derive"] }
+regex = "1.7.3"

examples/basic_file/README.md

@@ -0,0 +1,3 @@
+# Basic (from specification TOML file)
+
+Basic application demonstrating the from-TOML file interface. Logs TLS handshakes matching certain SNIs to a file.

examples/basic_file/spec.toml

@@ -0,0 +1,23 @@
+[[subscriptions]]
+filter = "tls.sni ~ '^.*\\.com$'"
+datatypes = [
+    "TlsHandshake",
+    "FilterStr",
+]
+callback = "tls_cb"
+
+[[subscriptions]]
+filter = "tls.sni ~ '^.*\\.net$'"
+datatypes = [
+    "TlsHandshake",
+    "FilterStr",
+]
+callback = "tls_cb"
+
+[[subscriptions]]
+filter = "tls.sni ~ '^.*\\.edu$'"
+datatypes = [
+    "TlsHandshake",
+    "FilterStr",
+]
+callback = "tls_cb"

examples/basic_file/src/main.rs

@@ -0,0 +1,14 @@
+use retina_core::{config::default_config, Runtime};
+use retina_datatypes::{FilterStr, TlsHandshake};
+use retina_filtergen::subscription;
+
+fn tls_cb(tls: &TlsHandshake, filter_str: &FilterStr) {
+    println!("Matched filter {}: {:?}", filter_str, tls);
+}
+
+#[subscription("./examples/basic_file/spec.toml")]
+fn main() {
+    let config = default_config();
+    let mut runtime: Runtime<SubscribedWrapper> = Runtime::new(config, filter).unwrap();
+    runtime.run();
+}

filtergen/src/lib.rs

@@ -294,7 +294,9 @@ fn generate(input: syn::ItemFn, config: SubscriptionConfig) -> TokenStream {
 
     quote! {
         use retina_core::filter::actions::*;
+        // Import potentially-needed traits
         use retina_core::subscription::{Trackable, Subscribable};
+        use retina_datatypes::{FromSession, Tracked, FromMbuf, StaticData};
 
         #subscribable