A function call is a function ID followed by a list of arguments in parentheses, which can be empty. The value of such an expression is the value returned by the function. Functions can be built-in or custom.
The built-in function library includes string operations, math operations, access to the event store and so on. A detailed list of built-in functions is given further on.
The syntax for defining custom functions is as follows:
def name([argument_list]) := { expression }
The general ID naming rules apply to names of internal functions. The list of internal function arguments (if any) is a comma-separated list of parameter names with optional default values. The arguments of internal functions can be constants, fields and field arrays, and messages. The default value is separated from the argument name by the equals character (=) and is assigned to the argument automatically if the argument is omitted in a function call. You can omit any number of arguments starting from the right, as long as the arguments have default values. The expression in curly braces is the result of the function call.
Example:
def DoDivide(a, b=10) :=
{
a/b
}
def IsLogon() :=
{
in_range( EventID, "529-537, 539, 548-549" )
and striequ( Source, "security" )
}
Custom and built-in functions share the same namespace. Redefining a function results in an error.
When functions are called, whether built-in or custom, the types of the arguments are not checked. When types mismatch, standard type conversion is performed.
REL’s built-in function library includes the following function types:
Function syntax can be described by the following template:
type_of_returned_value function_ID (argument1_type argument1, argument2_type argument2, ...)
where types are specified as string, number, Boolean or message. Brackets ([]) after the argument type specify that the function treats the argument as an array and processes all of its elements. If you specify any-type as the argument type, the function can take arguments of any type.
If the function takes an indefinite number of arguments, this is specified as follows: "type name1, type name2, ...", where type can be any word that describes the meaning of the arguments.
Built-in functions do not check argument types; they simply treat arguments as expressions of the specified type.
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
number count any-type[] expr1 ) |
Returns the number of array elements. For simple types, the returned value is always 1. |
|
boolean empty any-type[] expr1 ) |
Returns true if array expr1 is empty. For simple types, false is always returned. Defined as count(expr1)=0. |
|
boolean exist any-type[] expr1 ) |
Returns true if array expr1 has elements. For simple types, true is returned. Defined as not empty(expr1). |
|
number number any-type expr1 ) |
Converts the expression to the number type. Type conversion functions perform standard conversion and are mainly used for explicitly setting argument types in such functions as equal(), differ() or max(). |
|
string string any-type expr1 ) |
Converts the expression to the string type. |
|
boolean boolean any-type expr1 ) |
Converts the expression to the Boolean type. |
|
boolean equal any-type[] expr1 ) |
Returns true if all array elements are equal. |
|
boolean differ any-type[] expr1 ) |
Returns true if all array elements differ. That is, there are no equal value pairs. Note that the negative result of an equal() is required but not sufficient for the positive result of a differ() with the same arguments. |
|
min number[] expr1 ) |
Returns the least of the array items. |
|
max number[] expr1 ) |
Likewise, returns the greatest of the array items. |
|
boolean in_range any-type exp, ) |
Checks whether exp is within range; range is a string of values which are either comma-separated or specified as ranges. The values can be only positive integers. Example: in_range (EventID, "451, 512-654"). |
|
boolean in string exp, ) |
Tests whether exp is listed in values, which includes strings (literals or regular expressions). The options string specifies how string matching is performed:
Example: in( strcat( String4, "\\", String3 ), "wi", array("DOMAIN1\\guest", "DOMAIN2\\*") ) |
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
number abs number expr ) |
Returns the absolute value of the argument. |
|
number sqr number expr ) |
Returns the square root of the numeric value of expr. |
|
number sqrt number expr ) |
Returns the square root of the numeric value of expr. If the value of expr is negative, –1 is returned. |
|
number sum number[] expr1 ) |
Returns the sum of all arguments. If the argument is an array, its value is the sum of all its elements. |
|
number product number[] expr1 ) |
Returns the product of all arguments. |
|
number difference number[] expr1 ) |
Returns the numeric difference between the greatest and least elements in the argument sequence. Defined as (max(expr1)-min(expr1)). |
|
number average number[] expr1 ) |
Returns the arithmetical mean of arguments. This is the equivalent of sum(expr1) divided by the number of arguments, including array elements. |
|
number deviation number pos, ) |
Returns the statistic deviation of the pos-th selection element (element indexing starts with 0). Defined as expr_at_pos – average(expr1)). |
|
number mean_deviation number[] expr1 ) |
Returns the mean statistic deviation of the selection. Defined as average(abs(deviation(1, expr1)), abs(deviation(2, expr1)), ...). |
|
number dispersion number[] expr1 ) |
Returns the statistic dispersion of the selection. Defined as average(sqr(expr1[0] – average(expr1), sqr(expr1[1] – average(expr1), ...). |
|
number std_deviation number[] expr1 ) |
Returns the mean square deviation of the selection. Defined as sqrt(dispersion(expr1)). |
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
number strlen string expr1 ) |
Returns the number of characters in the string expr1. |
|
string strcat string expr1, ) |
Returns the string value which is a concatenation of all specified strings. |
|
string substr string expr1, ) |
Returns a substring of the string expr1, beginning with the pos-th position and having a length of length. Characters are numbered starting with 0. If length is –1, everything from pos to the end of the string is returned. |
|
number strstr string expr1, ) |
Returns the position of the first encounter of expr2 in expr1. If expr1 does not contain expr2, –1 is returned. |
|
string strupr string expr1 ) |
Returns the string expr1 where all characters are converted to upper case according to the rules of the local encoding. |
|
string strlwr( string expr1 ) |
Returns the string expr1 where all characters are converted to lower case according to the rules of the local encoding. |
|
number stricmp string expr1, ) |
Compares two strings while ignoring case. Returns the following numeric values: <0 if expr1 < expr2 0 if expr1 = expr2 >0 if expr1 > expr2 |
|
boolean striequ string expr1, ) |
Returns true if two strings are identical. Ignores case. Equivalent to stricmp(expr1, expr2) = 0. |
|
string exp, ) |
Runs regular expression exp on string str. Supported regular expressions are defined by IEEE Std 1003.1-2001 (so-called POSIX regular expressions). Both basic and extended regular expressions are supported. The text value of options can contain the following characters: • e—specifies that exp is an extended regular expression (ERE) • b—specifies that exp is a basic regular expression (BRE) • n—boost::regbase::normal (JavaScript) – default • i—ignore case The function returns a two-dimensional Nx2-sized array containing all substrings matching the regular expression, where N is the total number of matches. The first element of each nested array contains the index of the string start (indexing starts with 0); the second element contains the string length. |
The event creation date and time (Time field) are represented by a string according to the description of the field. Date and time processing functions convert this string to numbers and back, and do math operations on the date and time. If it is specified that the function returns time, it actually returns a string formatted for the Time field.
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
number year string expr ) |
Returns the numeric year value. |
|
number month string expr ) |
Returns the numeric month value. |
|
number day string expr ) |
Returns the numeric day value. |
|
number hour string expr ) |
Returns the numeric hour value. |
|
number minute( string expr ) |
Returns the numeric minute value. |
|
number second string expr ) |
Returns the numeric second value. |
|
number ms string expr ) |
Returns the numeric millisecond value. |
|
number dow string expr ) |
Returns the numeric day-of-the-week value (0 is Sunday, 1 is Monday, and so on). |
|
|
Returns the current system time in local time format. |
|
string time_to_local string expr ) |
Converts GMT time to local time format of the current system. |
|
string time_to_gmt string expr ) |
Does a conversion that is the reverse of time_to_local(). |
|
string time number month, ) |
Returns a string representation based on numeric month, day, year, hour, minute, second and millisecond values of event creation time. You can omit any number of fields. In this case, general rules apply, and the values of omitted fields are assumed to be 0. |
|
string time_diff string expr1, ) |
Returns the string representation of the date and time based on the date difference between expr1 (later event) and expr2 (earlier event). Afterwards, you can use the functions year(), month() and day() to find out how many units of time elapsed between the events. Example: time_diff("4/28/2002", "3/25/2001")="1/3/1" (one year, one month, and three days) |
|
number [xxx]s_diff string expr1, ) |
This family of functions returns the difference between two events (expr1 is the later event) in the number of years, months, hours, minutes, seconds and milliseconds. Afterwards, you can use the resulting values to construct non-normalized time (see time_add()). |
|
string time_add string expr1, ) |
Adds the time expr2 to the time expr1; expr2 can be non-normalized. Non-normalized time means such time representation in which the values of particular fields exceed threshold values (for example, 44 hours and 120 minutes). Normalization means conversion to conventional representation (for the previous example, 1 day and 22 hours). Normalization in general is impossible without a point of reference, because it is not known how many days there are in a month or whether a year is a leap year. Therefore, it applies only to the time_add() function. Examples of date and time processing functions: strcat(day(_LocalTime), ".", month(_LocalTime)) Represents the time of event in "day.month" format. minutes_diff(_LocalTime, _GMT) Time zone in minutes. time_to_local(time_add(_GMT, time(0, 0, 0, 1, 30))) time_to_local(time_add(_GMT, time("1:30"))) time_to_local(time_add(_GMT, time("0:90"))) Represents one and a half hours since the event was generated in the server’s local time format. |
These functions provide access to a store of received real-time monitoring messages and perform array filtering. The two function categories interoperate closely, because conditions for selection and filtering are somewhat different, and these functions complement each other.
Message selection functions do not consider the message that is currently being processed.
Mind that these functions evaluate each tested expression within its own scope rather than in the scope of the current expression. Such expressions are evaluated for each message that comes in from the data source, and must return true if the message meets selection conditions. The tested condition is the Z parameter of the expression, and its fields are accessed using the "Z." prefix.
Expressions used in selection functions do not have access to the parameters of the root expression. In these expressions, you cannot use message selection and filtering functions. In other words, such expressions can only set conditions, which are independent of the scope of the expression currently being processed.
The reason for such limitations is selection optimization. Events that pass the filter are stored in a buffer and returned when functions are called.
No such limitations exist for expressions that are parameters of the filtering function. Access to the processed message is performed the standard way, while the filtering element is stored in the Z parameter. Thus, complex selection rules are implemented in two stages:
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
message[] select expr1, ) |
Selects all messages that meet condition expr1 and are within a time interval no less than time relative to the current message. The time string is formatted for the Time field (see Date and Time Processing Functions). If no matching message is found, an empty array is returned. The condition expr1 is evaluated before the main expression. Thus, if the current event meets this condition, it will be present in the array of events returned by the select() function. The events in the array are sorted in ascending order by arrival time, so select()[0] is the first (oldest) event. When the rule is matched, the select() function's event buffer is freed. If the buffer was not empty when the match occurred, then the filter will be applied to subsequent events and stored in the buffer starting with the time expressed as OldestEvent._LocalTime + period, where period is the time interval set in select(). This prevents the rule from being matched too frequently in case there is an intense flow of events that meet the conditions of the select() function. |
|
message[] previous expr ) |
Returns the previous message that meets the specified condition. The function’s parameters are identical to the parameters of select(). The difference is that this function does not consider event generation time. The limitations for expr1 are the same as in select(). If no matching message is found, an empty array is returned. The condition expr1 is evaluated after the main expression. This means that the current event can never be the result of this function. If the rule is matched, the event stays in the buffer. |
|
message[] previous_lim expr1, ) |
This version of the previous() function returns the message that meets the specified condition and occurred after the specified time (time). Condition evaluation occurs in the same way as for previous(). |
|
message[] consolidate expr1, ) |
Consolidates message array expr1 based on the fields id1, id2, ... This means that any two or more messages with identical values for the specified fields are merged together. For the other fields, values are taken from the latest message. |
|
any-type[] filter any-type[] expr1, ) |
Evaluates expr2 for each element of the one-dimensional expr1 array in a row. Returns an array of elements for which the condition is met. The Z parameter is used to refer to an array element. |
|
message[] select_filtered expr1, ) |
This function is almost identical in effect to the following construction: filter(select(expr1, string period), expr2). The main difference is that when the rule is matched, only those events are extracted that pass both the expr1 and the expr2 filter. expr1 is a filter with a condition that does not depend on the current event (generalized filter), and expr2 filters the current event (context filter). expr2 uses temporary variable Z, which iterates through each array element (as in the filter() function) Example: count(select_filtered(EventID=100, Z.User = User, 10:00)) >= 10 This stores all events where EventID is 100. As soon as there are 10 events about a particular user, the rule is matched, and only events about this user are removed from the buffer. In contrast, using select() has the disadvantage of removing all events. |
|
message[] select_matches expr1, ) |
When the rule is matched, the event array is placed in a buffer with expiration time set to period. This function is mainly intended to prevent multiple rule matches. Example: count(select_filtered(EventID=100, Z.User = User, 10:00)) >= 10; With this expression, if there are 100 events about the same user, the rule is matched 10 times. To limit the number of matches, rewrite it as follows: count(select_filtered(EventID=100, Z.User = User, 10:00)) >= 10 and empty(select_matches(Z[0].User = User, 10:00)); This ensures the rule is matched no more frequently than once in 10 minutes. Examples of message database and filtering function usage: count( filter( select( Z.EventID = 100, "1:00:00" ), Z.User = User ) ) > 5; The condition is met if there have been more than five events during the past hour where the EventID is 100 and the User field has the same value as in the current event. EventID=100 and not exist(previous_lim(Z.EventID=200,"00:10:00")); The condition is met if an event with EventID=100 has come in and there have been no events with EventID=200 in the past 10 minutes. |
This function defines real-time messages that were not received when expected. The function can consider absolute time and relative time intervals.
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
boolean missing expr condition, ) |
This function returns true if the event that matches expr did not occur during one of the specified time intervals. Arguments:
Example 1: missing(Z.Source="Backup", "0 23 * * 3,6", "1:00"); Specifies that an event from the backup system is expected every Wednesday and Saturday from 11:00 PM until midnight. Example 2: missing(true, "0 * * * *", "0:30") or missing(true, "30 * * * *", "0:30"); Specifies that at least one event of any kind is expected in the log once every half-hour. |
|
FUNCTION PROTOTYPE |
DESCRIPTION |
|---|---|
|
boolean direct_member_of string user, ) |
This function returns true if the user user is a direct member of one of the groups listed in the groups array. The any_group parameter specifies whether membership in one of the groups (true) or all of the groups (false) is verified. The user and groups strings can be names or SIDs (which start with "S-1.") The default parameter is the value that the function returns if membership verification fails (for example, if access is denied.) Important: It is assumed that the listed groups are global or universal Active Directory security groups. Domain local groups with matching names are ignored, because their memberships and privileges can vary from domain to domain across the forest. Either or both of the last two parameters can be omitted. The following default values are assumed: any_group = false, default = false |
|
boolean is_current_user string domain, ) |
Returns true if domain and username are the same as the account that is calling the function. If domain is an empty string, then username can be the SID of the account you want to check. boolean is_current_logon_session(string session) Returns true if the specified string matches the current logon session. The string must have the following format: (<hex_num>, <hex_num>) Example: (0x0,0x3E7) (as in EventLog) |
|
boolean in_OU string domain, ) |
Tests whether the specified account (domain, name) belongs to the specified Active Directory organizational units (specified as plain OU names, such as "Accounting" and "Human Resources"). If domain is specified, then name is the account name. Otherwise, name can be the principal name or SID. The anyGroup and defaultValue parameters are used as in the direct_member_of() function. By default, anyGroup = true, defaultValue = false |
|
boolean member_of string user, string[] groups, ) |
This function returns true if user is a direct or indirect member of the specified groups. The any_group and default parameters are used as in the direct_member_of() function. Important: It is assumed that the listed groups are global or universal Active Directory security groups. Domain local groups with matching names are ignored, because their memberships and privileges can vary from domain to domain across the forest. By default, anyGroup = false, defaultValue = false. |
|
number get_account_type string computer, ) |
Queries the type of the specified account (account) on the specified computer (computer). If the value of computer is an empty string, the local computer is assumed. The account type is determined through NetUserGetInfo.
Additional flags:
If the type query fails, 0 is returned. |
|
boolean is_primary_group string user, ) |
Tests whether one of the specified groups is the primary group of the specified user (user). Examples: (EventID = 632 or EventID = 636) The expression tests whether the account used for adding a user to the "guests" group is different from the InTrust Server account. (get_account_type(Computer, Account) & Tests whether the account is a user not a computer. |
PowerShell Script is a Windows-specific scripting environment that InTrust can use for real-time monitoring rule response actions.
InTrust does not provide any additional PowerShell cmdlets.
InTrust functionality extensions rely on the following:
For details, see the following topics:
On Windows computers, Windows Script Host objects are available to InTrust (where applicable). For more information, refer to MSDN resources.
On other platforms, it is recommended that InTrust have access to the ECMAScript object model. The following ECMAScript objects are especially useful for InTrust operations:
For details about these objects, refer to MSDN or the ECMA-262 specification, depending on the object model you are using.
© ALL RIGHTS RESERVED. Feedback Terms of Use Privacy Cookie Preference Center
