Chat now with support
Chat with Support

InTrust 11.4.1 - Customization Kit

Functions

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.

 

Custom Functions

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.

Built-In Function Library

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.

General Functions

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,
string range

)

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,
string options,
string[] values

)

Tests whether exp is listed in values, which includes strings (literals or regular expressions).

The options string specifies how string matching is performed:

  • [b|e|c]
    b—basic regex
    e—extended regex
    c—simple comparison (strcmp); this is the default

  • [i|s]
    i —case-insensitive
    s—case-sensitive (default)

  • [w]
    use wildcards

  • [r]
    If this flag is included, a search operation is performed on exp instead of a match operation (which is the default behavior). Searching differs from matching in that matching returns true only if the pattern is at the beginning of exp, and searching returns true if the pattern is anywhere in exp.

Example:

in( strcat( String4, "\\", String3 ), "wi", array("DOMAIN1\\guest", "DOMAIN2\\*") )

Math Functions

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,
number[] expr1

)

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)).

 

String Processing Functions

FUNCTION PROTOTYPE

DESCRIPTION

number strlen
(

string expr1

)

Returns the number of characters in the string expr1.

string strcat
(

string expr1,
string expr2,
...

)

Returns the string value which is a concatenation of all specified strings.

string substr
(

string expr1,
number pos,
number length

)

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,
string expr2

)

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,
string expr2

)

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,
string expr2

)

Returns true if two strings are identical. Ignores case. Equivalent to stricmp(expr1, expr2) = 0.

number[][] regexp
(

string exp,
string str,
string options

)

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.

 

Date and Time Processing Functions

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).

string local_time()

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,
number day,
number year,
number hour,
number minute,
number second,
number ms

)

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,
string expr2

)

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,
string expr2

)

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,
string expr2

)

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.

 

Message Selection and Filtering Functions

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:

  1. Messages are selected by independent parameters.
  2. Filtering rules of any complexity are applied.

FUNCTION PROTOTYPE

DESCRIPTION

message[] select
(

expr1,
string time

)

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,
string time

)

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,
string id1,
string id2,
...

)

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,
expr2

)

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,
expr2,
string period

)

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,
string period

)

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.

 

Function for Defining Missing Messages

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,
string start_time,
string duration

)

This function returns true if the event that matches expr did not occur during one of the specified time intervals. Arguments:

  1. condition—testing condition

  2. start_time—specified in cron format as whitespace-delimited groups of five comma-delimited fields; the fields are as follows and can contain the asterisk (*) wildcard:

    • minute (0-59),

    • hour (0-23),

    • day of the month (1-31),

    • month of the year (1-12),

    • day of the week (0-6 with 0=Sunday).

  1. duration—duration of the time interval; the format is the same as for select() and previous_lim()

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.

 

Windows-Specific Functions

FUNCTION PROTOTYPE

DESCRIPTION

boolean direct_member_of
(

string user,
string groups [],
[boolean any_group],
[boolean default]

)

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,
string username

)

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,
string name,
string[] orgUnits,
[boolean anyGroup],
[boolean defaultValue]

)

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,
[boolean any_group],
[boolean default]

)

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,
string account

)

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.

  • UF_TEMP_DUPLICATE_ACCOUNT 0x0100
  • UF_NORMAL_ACCOUNT 0x0200
  • UF_INTERDOMAIN_TRUST_ACCOUNTv 0x0800
  • UF_WORKSTATION_TRUST_ACCOUNT 0x1000
  • UF_SERVER_TRUST_ACCOUNT 0x2000

Additional flags:

  • UF_SCRIPT 0x0001
  • UF_ACCOUNTDISABLE 0x0002
  • UF_HOMEDIR_REQUIRED 0x0008
  • UF_LOCKOUT 0x0010
  • UF_PASSWD_NOTREQD 0x0020
  • UF_PASSWD_CANT_CHANGE 0x0040
  • UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED 0x0080

If the type query fails, 0 is returned.

boolean is_primary_group
(

string user,
string[] groups

)

Tests whether one of the specified groups is the primary group of the specified user (user).

Examples:

(EventID = 632 or EventID = 636)
and striequ( Source, "security" )
and not is_current_user( String7, String6 )
and in( strcat( String4, "\\", String3 ), "wi", array("*\\Guests", "*\\Domain Guests") );

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) &
(UF_WORKSTATION_TRUST_ACCOUNT | UF_WORKSTATION_TRUST_ACCOUNT)) = 0

Tests whether the account is a user not a computer.

PowerShell Script

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.

Object Library

InTrust functionality extensions rely on the following:

  • Conventional scripting host object models
    For example, on Windows, all Windows Script Host objects are available to ECMAScript-based rules.
  • Additional InTrust-specific objects and functions for auditing and real-time monitoring

Reference

For details, see the following topics:

Standard Objects

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:

  • FileSystemObject
  • ShellObject
  • SystemInformationObject
  • RegKey
  • ActiveXObject
  • Enumerator
  • VBArray

For details about these objects, refer to MSDN or the ECMA-262 specification, depending on the object model you are using.

Related Documents