Struct tau_engine::Rule

pub struct Rule {
    pub detection: Detection,
    pub true_positives: Vec<Yaml>,
    pub true_negatives: Vec<Yaml>,
    /* private fields */
}

A rule used by the solver to evaluate a Document.

A rule contains the detection logic, along with the true positive and negative tests. The inclusion of these basic test allows for a basic level of verification to be ensured.

Rules are written in YAML and have a simple but powerful syntax.

Syntax

There are two parts to a rule’s logic: the condition & the identifiers.

Condition

The condition is the main expression and describes the top level logic for the rule. It can be comprised of the following:

Expression	Description
_ and _	The logical conjunction of two operands, where the operands are any of the following: expression: a nested expression. identifier: a key that matches an identifier in the detection block.
_ or _	The logical disjunction of two operands, where the operands are any of the following: expression: a nested expression. identifier: a key that matches an identifier in the detection block.
_ == _	The equality comparison of two operands, where the operands are any of the following: integer: an integer. string: a string. int(field): a field that should be cast as an integer. str(field): a field that should be cast as a string.
_ > _	The greater than comparison of two operands, where the operands are any of the following: integer: an integer. int(field): a field that should be cast as an integer.
_ >= _	The greater than or equal comparison of two operands, where the operands are any of the following: integer: an integer. int(field): a field that should be cast as an integer.
_ < _	The less than comparison of two operands, where the operands are any of the following: integer: an integer. int(field): a field that should be cast as an integer.
_ <= _	The less than or equal comparison of two operands, where the operands are any of the following: integer: an integer. int(field): a field that should be cast as an integer.
all(i)	An identifier mutator that evaluates to true only if all conditions for identifier i match.
not _	Negate the result of an expression. NOTE: This will only negate a result that is true or false, it will noop if the result is missing.
of(i, x)	An identifier mutator that evaluates to true only if a minimum of x conditions for identifier i match.

Identifiers

Identifiers are used to describe the matching logic for the values contained within documents. These are then collected by the condition in order to create a rule that can be used to tag a document.

Due to the nature of an identifier, they are essentially just variations on key/value pairs. The following variations are supported, where mappings are treated as conjunctions and sequences are treated as disjunctions:

# K/V Pairs
IDENTIFIER:
    KEY: MATCH

# K/V Pairs with multiple matches
IDENTIFIER:
    KEY:
    - MATCH_0
    - MATCH_1

# K/V Pairs (Grouped)
IDENTIFIER:
    - KEY: MATCH

# K/V Pairs (Nested)
IDENTIFIER:
    KEY:
        KEY: MATCH

Identifiers are unique keys that can be referenced in the condition.

Keys are used to get the values from documents. Keys can be wrapped in the following modifiers:

Expression	Description
all(k)	A key mutator that evaluates to true only if all matches for keys k match.
of(k, x)	A key mutator that evaluates to true only if a minimum of x matches for key k match.

Matches are the expressions which are evaluated against values returned by keys. They support the following syntax:

Expression	Description
foo	An exact match
foo*	Starts with
*foo	Ends with
*foo*	Contains
?foo	Regex
i_	A prefix to convert the match into a case insensitive match.

To escape any of the above in order to achieve literal string matching, combinations of ' and " can be used.

Examples

Here is a very simple rule example:

detection:
  A:
    foo: "foo*"
    bar: "*bar"
  B:
    foobar:
    - foobar
    - foobaz

  condition: A and B

true_positives:
- foo: foobar
  bar: foobar
  foobar: foobar

true_negatives:
- foo: bar
  bar: foo
  foobar: barfoo

Here is a slightly more complex rule example:

detection:
  A:
    all(phrase):
    - "*quick*"
    - "*brown*"
  B:
    phrase: ibear

  condition: A and not B

true_positives:
- phrase: the quick brown fox

true_negatives:
- foo: the quick brown BEAR

Fields

detection: Detection

true_positives: Vec<Yaml>

true_negatives: Vec<Yaml>

Implementations

impl Rule

pub fn load(path: &Path) -> Result<Self, Error>

Load a rule from a YAML file.

pub fn from_str(s: &str) -> Result<Self, Error>

Load a rule from a YAML string.

pub fn from_value(value: Value) -> Result<Self, Error>

Load a rule from a YAML Value.

pub fn optimise(self, options: Optimisations) -> Self

Optimise the rule with the optimisations provided.

pub fn matches(&self, document: &dyn Document) -> bool

Evaluates the rule against the provided Document, returning true if it has matched.

pub fn validate(&self) -> Result<bool, Error>

Validates the rule’s detection logic against the provided true positives and negatives.

Trait Implementations

impl Clone for Rule

fn clone(&self) -> Rule

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Rule

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Rule

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Rule

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where __S: Serializer,

Serialize this value into the given Serde serializer.