1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246
//! # Tau Engine
//!
//! This crate provides a library that tags documents by running and matching rules over them.
//! The engine makes use of a Pratt parser and a tree solver in order to evaluate the detection
//! logic of a rule against a document, if the outcome is true the document is considered tagged by
//! that rule.
//!
//!
//! ## Rules
//!
//! A rule is used to tag a document and is made up of three parts:
//! - `detection`: the logic used to evaluate a document.
//! - `true positives`: example documents that must evaluate to true for the given detection.
//! - `true negatives`: example documents that must evaluate to false for the given detection.
//!
//! The detection block is made up of a condition, and identifiers. This allows for simple but
//! expressive rules, below is a brief summary (see [Rules](Rule) for more):
//!
//! ### Identifiers
//!
//! Identifiers are used to help keep the condition concise and generally contain the core of the
//! matching logic. They consist of Key/Value pairs which allow for the extraction of data from the
//! document and the evaluate of its value. It should be noted that mappings are treated as
//! conjunctions, while sequences are treated as disjunctions.
//!
//! Identifiers make use of the following matching logic:
//! - `foobar`: an exact match of foobar
//! - `foobar*`: starts with foobar
//! - `*foobar`: ends with foobar
//! - `*foobar*`: contains foobar
//! - `?foobar`: regex foobar
//!
//! Any of the above can be made case insensitive with the `i` prefix, for example:
//! - `ifoobar`
//! - `ifoobar*`
//!
//! Escaping can be achieved with a combination of `'` and `"`.
//!
//! ### Condition
//!
//! The condition is just a boolean expression and supports the following:
//! - `and`: logical conjunction
//! - `or`: logical disjunction
//! - `==`: equality comparison
//! - `>`, `>=`, `<`, `<=`: numeric comparisons
//! - `not`: negate
//! - `all(i)`: make sequences behave as conjunctions
//! - `of(i, x)`: ensure a sequence has a minimum number of matches
//!
//!
//! ### Examples
//!
//! ```text
//! detection:
//! A:
//! foo.bar: foobar
//!
//! condition: A
//!
//! true_positives:
//! - foo:
//! bar: foobar
//!
//! true_negatives:
//! - foo:
//! bar: foo
//! ```
//!
//! ## Documents
//!
//! A document is anything that can provide data to the engine in a meaningful way, usually through Key/Value
//! pairs, i.e: an event log, json object, yaml file, etc. Implementations are achieved with the
//! [`Document`](Document) trait.
//!
//! ## Solving
//!
//! This is an example of how you can tag a document against a provided rule:
//!
//! ```
//! use std::borrow::Cow;
//!
//! use tau_engine::{Document, Rule, Value};
//!
//! // Define a document.
//! struct Foo {
//! foo: String,
//! }
//! impl Document for Foo {
//! fn find(&self, key: &str) -> Option<Value<'_>> {
//! match key {
//! "foo" => Some(Value::String(Cow::Borrowed(&self.foo))),
//! _ => None,
//! }
//! }
//! }
//!
//! // Write a rule.
//! let rule = r#"
//! detection:
//! A:
//! foo: foobar
//! condition: A
//! true_positives:
//! - foo: foobar
//! true_negatives:
//! - foo: foo
//! "#;
//!
//! // Load and validate a rule.
//! let rule = Rule::from_str(rule).unwrap();
//! assert_eq!(rule.validate().unwrap(), true);
//!
//! // Create a document.
//! let foo = Foo {
//! foo: "foobar".to_owned(),
//! };
//!
//! // Evalute the document with the rule.
//! assert_eq!(rule.matches(&foo), true);
//! ```
//!
//! ## Features
//!
//! The following are a list of features that can be enabled or disabled:
//! - **core**: Exposes some of Tau Engine's internals.
//! - **ignore_case**: Force the engine to always be case insensitive, this will ignore
//! the `i` prefix and for that reason is not compatible with case sensitive rules.
//! - **json**: Enable serde json support, this will allow the tau-engine to solve on
//! `serde_json::Value`.
//!
//!
//! ### JSON
//!
//! When JSON support is enabled for the tau-engine, the result is a solver that can now reason over
//! any document that can be deserialized into `serde_json::Value`.
//!
//! ```ignore
//! # use serde_json::json;
//! use tau_engine::{Document, Rule};
//!
//! // Write a rule.
//! let rule = r#"
//! detection:
//! A:
//! foo: foobar
//! condition: A
//! true_positives:
//! - foo: foobar
//! true_negatives:
//! - foo: foo
//! "#;
//!
//! // Load and validate a rule.
//! let rule = Rule::from_str(rule).unwrap();
//! assert_eq!(rule.validate().unwrap(), true);
//!
//! // Create a document.
//! let foo = json!({
//! "foo": "foobar",
//! });
//!
//! // Evalute the document with the rule.
//! assert_eq!(rule.matches(&foo), true);
//! ```
#![cfg_attr(feature = "benchmarks", feature(test))]
#[cfg_attr(test, macro_use)]
#[cfg(feature = "benchmarks")]
extern crate test;
pub use self::document::Document;
pub use self::error::{Error, Kind as ErrorKind};
pub use self::optimiser::Optimisations;
pub use self::rule::Rule;
pub use self::solver::solve;
pub use self::value::{Array, AsValue, Object, Value};
pub(crate) use error::Result;
mod document;
mod error;
mod identifier;
#[cfg(feature = "json")]
mod json;
mod optimiser;
mod parser;
mod rule;
mod solver;
mod tokeniser;
mod value;
mod yaml;
#[cfg(feature = "core")]
/// Exposes some of Tau Engine's internals.
pub mod core {
/// Exposes some of Tau Engine's internal optimisations so that Expressions can be built by hand.
pub mod optimiser {
pub use crate::optimiser::*;
}
/// Exposes some of Tau Engine's internal parsing so that Expressions can be built by hand.
pub mod parser {
pub use crate::identifier::*;
pub use crate::parser::*;
pub use crate::tokeniser::*;
}
pub use crate::rule::Detection;
use std::collections::HashMap;
use crate::document::Document;
use crate::parser::Expression;
use crate::solver::SolverResult;
lazy_static::lazy_static! {
static ref IDENTIFIERS: HashMap<String, Expression> = HashMap::new();
}
/// Evaluates a `Document` with the provided expression.
///
/// # Panics
///
/// This method will panic if an invalid expression is provided
pub fn solve(expression: &Expression, document: &dyn Document) -> bool {
match super::solver::solve_expression(expression, &IDENTIFIERS, document) {
SolverResult::True => true,
SolverResult::False | SolverResult::Missing => false,
}
}
/// Evaluates a `Document` with the provided expression, and identifiers.
///
/// # Panics
///
/// This method will panic if an invalid expression is provided
pub fn solve_expression(
expression: &Expression,
identifiers: &HashMap<String, Expression>,
document: &dyn Document,
) -> bool {
match super::solver::solve_expression(expression, identifiers, document) {
SolverResult::True => true,
SolverResult::False | SolverResult::Missing => false,
}
}
}