Chat now with support
Chat with Support

InTrust 11.3.1 - Customization Kit

REL

REL (Rule Expression Language) is used for defining rules that generate alerts. REL

is also used for filtering events.

The result of expression evaluation is usually a Boolean value, or is converted to

such a value. This value determines whether a specific alert is generated or message

is filtered. The parameters of a REL expression are InTrust events.

Reference

Words

Expressions

Operators

Functions

Words

Expressions are evaluated left to right. Words are separated by white spaces, tabs and carriage returns. There are six types of words in REL:

  • ID
    Name of an argument, field or function. An ID can include alphanumeric characters and the underscore character (_), but cannot begin with a number. IDs are case-sensitive.

  • String constant
    Enclosed in single or double quotes. Use the backslash escape character (\) to specify quotes (as in "quoted text: \"some text\"") or the backslash character itself (as in "domain\\user"). String constants, like expressions, use the encoding of the current locale (depending on implementation). String values of fields are converted to the local encoding when they are processed.

  • Numeric constant
    Begins with a number or a negative sign (-). If a numeric constant begins with "0x", it is interpreted as a hexadecimal value with characters representing the number bitwise (including the sign bit). All numeric constants are signed 32-bit integers.

  • Boolean constant
    True or false.

  • Operator
    The following operators are used:

    • + - * / % > >= < <=

    • = != () | & << >> ? :

    • . [] or and not

  • Auxiliary character

Characters that are part of expression language syntax, such as parentheses, curly braces, and the function definition character.

Formal Language Grammar

expression ::= +(token)

token ::= [*space] (identifier | string | number | boolean | operator | special) [*space]

space ::= " " | "\t" | "\n"

identifier ::= (alpha | "_") *(alpha | numeric | "_")

string ::= single_quoted | double_quoted

single_quoted ::= "’" *(char | ’r;"’ | "\’" | "\\") "’"

double_quoted ::= ’r;"’ *(char | "’" | ’r;\"’ | "\\") ’r;"’

char ::= 0x00 | …… | 0xFF ; all characters except ’r; " \

number ::= (["-"] +numeric) | ("0x" +hex)

boolean ::= "true" | "false"

operator ::= plus | minus | multiply | divide | modulus | greater | greater_equal | less | less_equal | equal | inequal | bit_or | bit_and | bit_xor | shift_left | shift_right | not | or | and | conditional | selection | field_selection | open_sq | close_sq

plus ::= "+"

minus ::= "-"

multiply ::= "*"

divide ::= "/"

modulus ::= "%"

greater ::= ">"

greater_equal ::= ">="

less ::= "<"

less_equal ::= "<="

equal ::= "="

inequal ::= "!="

bit_or ::= "|"

bit_and ::= "&"

bit_xor ::= "^"

shift_left ::= "<<"

shift_right ::= ">>"

not ::= "not"

or ::= "or"

and ::= "and"

conditional ::= "?"

selection ::= ":"

field_selection ::= "."

open_sq ::= "["

close_sq ::= "]"

symbol ::= open_br | close_br | comma | definition | open_cr | close_cr

open_br ::= "("

close_br ::= ")"

comma ::= ","

definition ::= ":="

open_cr ::= "{"

close_cr ::= "}"

Formal Language Syntax

REL_expression ::= *(function_definition) expression

function_definition ::= "def" identifier open_br [ argument_def_list ] close_br definition open_cr expression close_cr

argument_def_list ::= argument_def *(comma argument_def)

argument_def ::= identifier [ equal expression ]

primary_expression ::= constant | identifier | function |

(open_br expression close_br)

constant ::= string | number | boolean

function ::= identifier open_br [argument_list] close_br

argument_list ::= expression *(comma expression)

operator_indexing ::= primary_expression |

operator_indexing field_selection identifier |

operator_indexing open_sq expression close_sq

operator_unary ::= primary_expression |

(minus | not) primary_expression

operator_multiply ::= operator_unary |

operator_multiply (multiply | divide | modulus) operator_unary_minus

operator_add ::= operator_multiply |

operator_add (plus | minus) operator_multiply

operator_shift ::= operator_add |

operator_shift (shift_left | shift_right)  operator_add

operator_bit_and ::= operator_shift |

operator_bit_and bit_and operator_shift

operator_bit_xor ::= operator_bit_and |

operator_bit_xor bit_xor operator_bit_and

operator_bit_or ::= operator_bit_xor |

operator_bit_or bit_or operator_bit_xor

operator_compare ::= operator_bit_or |

operator_compare (greater | greater_equal | less | less_equal) operator_bit_or

operator_equal ::= operator_compare |

operator_equal (equal | inequal) operator_compare

operator_and ::= operator_equal | operator_and and operator_equal

operator_or ::= operator_and | operator_or or operator_and

operator_conditional ::= operator_or |

operator_or conditional expression selection expression

expression ::= operator_conditional

In REL-based event filters, there must be no semicolon at the end of the expression. In rules, the semicolon is required.

Expressions

An expression is a basic language entity. An expression has a value and a type. It consists of constants, events and event fields, and also operators and function calls required for calculations.

Expression examples:

5
A+B
Source
Count<5
strstr(Description, "found")

Expression Types

Simple types

  • string

  • number

  • boolean

  • empty

Complex types

  • message (event)

  • array

Arrays

Use brackets to specify the array element you want to access. The first element of an array has an index of 0.

Arrays can include other arrays. For example, it is possible to return an array of field arrays to denote a set of fields each of which has a set of auxiliary fields.

If you go outside the scope of an array, the returned value is empty (an empty field or a message without fields). Arrays can also be empty; in this case, getting any element of the array returns an empty value.

Type Conversion

REL does not have strong typing. All expression values are converted to other types as necessary, according to the rules described further on.

  • Strings to numbers
    Characters are interpreted as a number. If the expression begins with "0x", the remaining characters are interpreted as a hexadecimal representation of a number. If the string does not represent a number, zero is returned.

  • Numbers to strings
    A number is converted to its decimal representation without leading spaces or zeros.

  • Booleans to strings and numbers
    Boolean values are converted to the strings "true" and "false", and to the numbers 1 and 0, respectively.

  • Numbers to Booleans
    False if the number is 0, and true otherwise.

  • Strings to Booleans
    False if the string is empty.

Converting Arrays

Wherever an array is required, a simple value can substitute it, and the reverse is also true. Conversions are made according to the following rules:

  • Simple value to array
    A message is converted to a message array with a single element. A field is converted to a field array with a single element.

  • Array to simple value
    The first element of the array is returned. In multi-dimensional arrays, this rule is applied recursively multiple times and returns the element which is the first at all nesting levels.

Empties

Empty is a special type used to represent undefined values.

Conversion of empties

  • Empty to number
    0 is returned.

  • Empty to string
    Empty string (same as "").

  • Empty to Boolean
    False.

  • Empty to array
    Array with one element (empty).

Events and Fields

An event is an implicit parameter in a REL expression. Event fields are accessed by name. Example:

EventID = 100

If an event or event array is returned by a function, you can access its fields using the "." operator. Example:

previous_lim(Z.EventID=100, "1:00:00").String1
select(Z.EventID=100, "1:00:00")[0].String1

If the specified field is not found, a value of the "empty" type is returned.

The "." operator can be applied to an event array. In this case, the result is an array of values of the specified field. The size of this array is equal to the size of the event array. Example:

select(Z.EventID=100, "1:00:00")._LocalTime

An event cannot be converted to a simple (scalar) type or an array. This operation returns an empty.

The asterisk character (*) is a special case of field name. This field contains an array of the string values of all message fields.

Operators

The following table shows the operators that REL supports. If an expression is an operator argument and the expression value type is invalid, the value is converted to the necessary type according to standard rules (See Type Conversion).

SYNTAX

OPERAND TYPE

VALUE TYPE

RESULT

Access and indexing operators

expr1 [ expr2 ]

Number array

Field or message

Provides access to an element of a field array or message array.

expr1 . id

Array, ID

Field array

Provides access to message fields or auxiliary fields of a particular field. The expr1 part can be a single message or a field (See Type Conversion).

Math operators

- expr1

Number

Number

A negative value of expr1 defined as (0 – expr1).

expr1 + expr2

Number

Number

Sum of operands.

expr1 – expr2

Number

Number

Difference of operands.

expr1 * expr2

Number

Number

Product of operands.

expr1 / expr2

Number

Number

Ratio of expr1 and expr2. In case of overflow (and division by zero) the result is the maximum possible integer (2^31-1 or –2^31).

expr1 % expr2

Number

Number

Excess of integer division defined as (expr1 – expr1 / expr2 * expr2).

expr1 & expr2

Number

Number

Result of a bitwise AND operation on operands.

expr1 | expr2

Number

Number

Result of a bitwise OR operation on operands.

expr1 ^ expr2

Number

Number

Result of a bitwise XOR operation on operands.

expr1 << expr2

Number

Number

Result of a bitwise signed left shift of the value of expr1 by expr2 bits.

expr1 >> expr2

Number

Number

Result of a bitwise signed left shift of the value of expr1 by expr2 bits.

Comparison operators

expr1 = expr2,

expr1 != expr2

Simple

Boolean

True if operand values are equal or not equal, respectively; false otherwise. If operand types mismatch, the second operand’s type is converted.

expr1 < expr2,

expr1 <= expr2,

expr1 > expr2,

expr1 >= expr2

Simple

Boolean

True if the first operand is less, less than or equal to, greater, or greater than or equal to the second, respectively; false otherwise. If operand types mismatch, the second operand’s type is converted. String comparison is case-sensitive. In Boolean value comparisons, false is always less than true.

Boolean operators

not expr1

Boolean

Boolean

Returns the negation of expr1.

expr1 and expr2

Boolean

Boolean

True if both expressions yield true; false otherwise. The value of expr1 is calculated first. If this value is false, expr2 is not calculated.

expr1 or expr2

Boolean

Boolean

True if at least one of the expressions yields true. The value of expr1 is calculated first. If this value is true, expr2 is not calculated.

expr1 ? expr2 : expr3

expr1: Boolean

expr2: any type

Boolean

The value of the expression is expr2 if expr1 is true; otherwise, the value is expr3. Either way, only one expression is calculated.

This operator accepts all types, including messages, fields and arrays. The expressions expr2 and expr3 can be of different types. In this case, the resulting type depends on the result of expr1.

Operator Precedence

The order of operator processing can be changed by enclosing expressions in parentheses. The access and indexing operators have the highest precedence, math operators come next:

[] .
- (unary) not
* / %
+ -
<< >>
&
^
|

Comparison operators follow:

< > <= >=
= !=

Boolean operators have the lowest precedence:

and
or
?:

Operator usage examples:

  • 18+44 (result: 62)

  • "14"/3 (result: 4)

  • true=2 (result: true)

  • 2=true (result: false)

  • Z._LocalTime (result: local time of event Z)

  • ""?14:false (result: false)

  • "aaa"<"bb" (result: true)

  • (3>=2)+1 (result: 2, number(3>=2)=1)

Related Documents