Merge pull request #36 from EFForg/lte-parsing

Add LTE parsing, an Analyzer trait, and an implementation of one analyzer

Cargo.toml

@@ -5,5 +5,6 @@ members = [
     "bin",
     "serial",
     "rootshell",
+    "telcom-parser",
 ]
 resolver = "2"

lib/Cargo.toml

@@ -14,3 +14,4 @@ libc = "0.2.150"
 log = "0.4.20"
 pcap-file = "2.0.0"
 thiserror = "1.0.50"
+telcom-parser = { path = "../telcom-parser" }

lib/src/analysis/analyzer.rs

@@ -0,0 +1,51 @@
+use std::borrow::Cow;
+
+use super::information_element::InformationElement;
+
+/// Qualitative measure of how severe a Warning event type is.
+/// The levels should break down like this:
+///   * Low: if combined with a large number of other Warnings, user should investigate
+///   * Medium: if combined with a few other Warnings, user should investigate
+///   * High: user should investigate
+pub enum Severity {
+    Low,
+    Medium,
+    High,
+}
+
+/// [QualitativeWarning] events will always be shown to the user in some manner,
+/// while `Informational` ones may be hidden based on user settings.
+pub enum EventType {
+    Informational,
+    QualitativeWarning(Severity),
+}
+
+/// Events are user-facing signals that can be emitted by an [Analyzer] upon a
+/// message being received. They can be used to signifiy an IC detection
+/// warning, or just to display some relevant information to the user.
+pub struct Event {
+    pub event_type: EventType,
+    pub message: String,
+}
+
+/// An [Analyzer] represents one type of heuristic for detecting an IMSI Catcher
+/// (IC). While maintaining some amount of state is useful, be mindful of how
+/// much memory your [Analyzer] uses at runtime, since rayhunter may run for
+/// many hours at a time with dozens of [Analyzers](Analyzer) working in parallel.
+pub trait Analyzer {
+    /// Returns a user-friendly, concise name for your heuristic.
+    fn get_name(&self) -> Cow<str>;
+
+    /// Returns a user-friendly description of what your heuristic looks for,
+    /// the types of [Events](Event) it may return, as well as possible false-positive
+    /// conditions that may trigger an [Event]. If different [Events](Event) have
+    /// different false-positive conditions, consider including them in its
+    /// `message` field.
+    fn get_description(&self) -> Cow<str>;
+
+    /// Analyze a single [InformationElement], possibly returning an [Event] if your
+    /// heuristic deems it relevant. Again, be mindful of any state your
+    /// [Analyzer] updates per message, since it may be run over hundreds or
+    /// thousands of them alongside many other [Analyzers](Analyzer).
+    fn analyze_information_element(&mut self, ie: &InformationElement) -> Option<Event>;
+}