Functions

Purpose

Functions are used to provide you with the ability to dynamically perform different actions, based on data found on the target host. Functions may be used in virtually any RuleKey. Should the syntax for a function be incorrect or return an error, the most common result is is no text output. However you will typically also see an "Inner Event" which is logged in the location the error occurred.

Syntax

The syntax for using functions is:
%functionName(parameter0, parameter1, ..., parametern-1)

Functions may also call other functions, or specify variables, such as in the following example:
%if(%eq(%registryget(HKLM\Software\Microsoft\Windows NT\CurrentVersion\CurrentVersion),5.1),Windows XP, Not Windows XP)

Functions are evaluated from the inside out, so the registryget function is evaluated first and retrieves the registry value at the location of: HKLM\Software\Microsoft\Windows NT\CurrentVersion\CurrentVersion. Next, the value is compared to the static string of "5.1". If they are equal, then the if function prints out the first value, which is "Windows XP". If they are not equal, then the if function prints out the second value, which is "Not Windows XP".

Built In Functions

Function Name Parameters Description
add number0,number1[,...][,numbern-1] This function will add all of the numbers specified together. Either integers or floating point numbers can be added. Depending on what the final value is, there may be trailing zeroes.
and boolean0,boolean1[,...][,booleann-1] Perform a logical "and" operation on two or more boolean values.
cat string0,string1, ...,stringn-1 Concatenate two or more strings.
eq string0, string1, ..., stringn-1 Test two or more strings for equality. This is a case sensitive operation.
gt number0,number1 Test two numbers to see if the first number is greater than the second.
gte number0,number1 Test two numbers to see if the first number is greater than or equal to the second.
if bool,value0,value1
-or-
boolean0,value0,boolean1,value1
-or-
boolean0,value0,boolean1,value1,value2
Perform an "if" statement boolean logic.
Syntax 1: If the boolean0 evaluates to "true", then return value0. If "false", then return value1.
Syntax 2: If the boolean0 evaluates to "true", then return value0. If boolean1 evaluates to "true" then return value1.
Syntax 3: If the boolean0 evaluates to "true", then return value0. If boolean1 evaluates to "true" then return value1. Else, return value2.
NOTE: There is no limit to the number of parameters. This is effectively a giant switch statement and will continue to be evaluated until either the Else condition is reached or the first "true" boolean is reached.
instr string0,string1[,integer0] Search string0 for string1. Start at the position indicated by integer0, which defaults to zero if it is not supplied.
length string Return the length of a string.
lowercase string Return the string supplied as a parameter converted to lowercase.
lt number0,number1 Test two numbers to see if the first number is less than the second.
lte number0,number1 Test two numbers to see if the first number is less than or equal to the second.
max number0,number1,...,numbern-1 Return the number with the highest value of the numbers in the array.
min number0,number1,...,numbern-1 Return the number with the highest value of the numbers in the array.
not boolean Test a boolean value and return the opposite of it.
ne string0,string1,...,stringn-1 Test two or more strings to make sure they are not all equal. This is a case sensitive operation.
or boolean0,boolean1,...,booleann-1 Perform a logical "or" operation on two or more boolean values.
randomstring integer Create a random string with the length specified.
registryget string Get the value contained in the registry specified by the path
registrykeys string0[,string1] Return a delimited list of registry keys based on the registry path specified by string0. If not specified, the default delimiter is a comma.
registryvalues string0[,string1] Return a delimited list of the registry values located in the registry based on the registry path specified by string0. If not specified, the default delimiter is a comma.
replace string0,string1,string2 Search string0 and replace all instances of string1 that are found with string2.
substr string0,integer0[,integer1] Return a substring of string0, starting at integer0. If integer1 is supplied, it indicates the number of characters to copy.
trim string Trim all leading and trailing whitespace from a string.
trimleft string Trim all leading whitespace from a string.
trimright string Trim all trailing whitespace from a string.
uppercase string Return the string supplied as a parameter converted to lowercase.

Hints

Hint 1: If you're working with a long and complicated function, sometimes it's best to declare new RuleKeys whose values are intermediate steps within the greater function. From the example above which is repeated below, we might declare the following RuleKeys:
%if(%eq(%registryget(HKLM\Software\Microsoft\Windows NT\CurrentVersion\CurrentVersion),5.1),Windows XP, Not Windows XP)

RuleKey Value
CurrentVersion =%registryget(HKLM\Software\Microsoft\Windows NT\CurrentVersion\CurrentVersion)
IsRunningXpKernel =%eq(%CurrentVersion%,5.1)
MyFunction =%if(%IsRunningXpKernel%,Windows XP, Not Windows XP)
These are technically equivalent, however MyFunction is much easier to read than the original, due to its length.

Hint 2: Functions are evaluated inline with whatever they are used in and in an order that makes sense. If a variable is referred to by a function, that variable is evaluated before the function is evaluated. Variables can themselves contain functions, which are in turn evaluated prior to returning their value.

Hint 3: If a variable refers to itself, either directly or through other functions, it will return an empty string from the inner-most location.

© 2011-2019 Moon River Software Inc. All rights reserved.
@AuditShark stay in touch