Using Functions, Operators, and Keywords

The following functions, operators, and keywords can be used in conditional statements:

• min/max functions
• add and multiply functions
• Boolean operators
• The contains keyword
• The join Function
• Using the Split Function
• Using the Field Exists Function
• Setting a Rule to be Case Insensitive
• Using lt in Switch Statements
• Using gt in Switch Statements
• Using the Wildcard Character in Statements
• Nesting Functions
• Using = with Arrays (Lists)

Using min/max Functions

The min/max functions work for all statement types for number values only. It sets the value of the field in the Enforcement Action to the min/max value of a group of single value fields, an array (list) field, or a group of array fields indicated in the min/max clause.

Using the min/max Function with an Array (List) Field

min has the syntax:

set_value min([adapter.arrayfield])

max has the syntax:

set_value max([adapter.arrayfield])

• Example - Sets the value of the form.field_integer field to the maximum value found in the device.specific_data.data.software_cves.cvss3_score list.

  device all then form.field_integer set_value max([device.specific_data.data.software_cves.cvss3_score])
  

• Example - Sets the value of the form.field_integer field to the minimum value found in the device.specific_data.data.software_cves.cvss3_score list.

  device all then form.field_integer set_value min([device.specific_data.data.software_cves.cvss3_score])
  

  Using the min/max Functions with Multiple Single Value Fields

min has the syntax:

set_value min(item1, item2, ..., itemN)

max has the syntax:

set_value max(item1, item2, ..., itemN)

• Example - Compares the number of logical cores in the following three fields, and sets the value of the form.field_integer field to the maximum value.
  • device.adapters_data.aws_adapter.cpus.logical_cores
  • device.specific_data.data.cpus.logical_cores
  • device.adapters_data.bigid_adapter.cpus.logical_cores

  device all then form.field_integer set_value max([device.adapters_data.aws_adapter.cpus.logical_cores], [device.specific_data.data.cpus.logical_cores], [device.adapters_data.bigid_adapter.cpus.logical_cores])
  

Using the min/max Functions with Multiple Array Fields

The min/max functions can return the minimum or maximum value from multiple array fields. The minimum or maximum value from each field is found and then the minimum or maximum of those values is used.

min/max has the syntax:

set_value min([....],[....],...,[....])
or
set_value max([....],[....],...,[....])

• Example - Sets the value of the form.field_integer field to the maximum value found in either of these array fields:
  • device.specific_data.data.software_cves.cvss3_score
  • device.adapters_data.tenable_security_center_adapter.software_cves.cvss2_score

device all then form.field_integer set_value max([device.specific_data.data.software_cves.cvss3_score], [device.adapters_data.tenable_security_center_adapter.software_cves.cvss2_score])

Using add and multiply Functions

The add and multiply functions can be used in the same way as concat or sum to add/multiply one or more single value numerical fields to/by a number or numbers.

add has the syntax:

add (value1, value2,..., valueN)

multiply has the syntax:

multiply([some.field.name], value)

or

multiply (value1, value2,..., valueN)

• Example - Sets the value of the form.field_integer field to the sum of the following:
  • device.custom.asset_criticality multiplied by 0.4
  • device.custom.asset_severity multiplied by 0.6

device all then form.field_integer set_value
add (multiply([device.custom.asset_criticality], 0.4), multiply([device.custom.asset_severity], 0.6))

Using Boolean Operators in Case Statements

The Boolean operators true and false can be used in switch/case statements to test the value of a Boolean field.

• Example - If device.rapid7.some_boolean_field has the value true, then set its value to 1234. If its value is false, set its value to 4567.

   switch device.rapid7.some_boolean_field
   case field_equal (true) then device.rapid7.some_boolean_field set_value "1234"
   case field_equal (false) then device.rapid7.some_boolean_field set_value "4567"
  

Using the contains Operator

The contains operator for switch statements applies the Enforcement action if the string or array contains the indicated value:

• A string may contain a substring.
• An array must contain the exact value.

contains has the syntax:

switch some.field.name case contains("value") then ...

• Example - This statement verifies that the labels list device.labels contains a value “TAG”and if true, sets the value of the form.color field to "blue".
  For example, if the labels list has the values [“123”, “TAG”, “ANOTHER”], the switch statement applies the enforcement action, i.e., sets the form color field to blue.

  switch device.labels case contains("TAG") then form.color set_value "blue"
  

• Example - This statement verifies that “ABC” is a substring of (or the entire) asset name. (e.g., “ABCDEFG” as asset name returns true), and if yes, assigns the device (device.specific_data.data.assigned_to) to Group ABC.

  switch device.specific_data.name case contains("ABC") then device.specific_data.data.assigned_to set_value "Group ABC"
  

Using the join Function for Array Fields

The join function converts a list (array) into one single string with the items separated by a delimiter. The delimiter can be any character.

join has the syntax:

join (items, delimiter)

• Example - For each device, converts the list of vulnerabilities (device.specific_data.data.vulnerabilities.vulnerability_name) found on the device into a string of vulnerabilities separated by a space and comma. Places the joined string (vulnerability1, vulnerability2, ..., vulnerabilityN) in the Incident Description field of the ticket.

  device all then form.incident_description set_value join ([device.specific_data.data.vulnerabilities.vulnerability_name], " ,")
  

• Example - Join the listed values into one string with the values separated by semicolon and a space.

  join(["string_1", "string_2"], "; ") 
  

  The output will be

  *string1; string2*.
  

• Example - Concatenate a list with a string using join.
  You can use nested functions to concatenate a list with a string.

• Flattens the array device.field.array.1 into its elements with a comma delimiter between each two elements.

• Concatenates "and", the string in device.field.mystring, and "comment" to the joined string, and places the resulting string in form.incident_description.

   device all then form.incident_description set_value 
   concat (join ([device.field.array.1], ","), "and",      [device.field.mystring],"comment")
  

  This statement generates a (single string) value of:

  itemarray1, itemarray2, ..., itemarrayn and mystring comment
  

Using the split Function

The split function splits the string in the indicated field at the specified delimiter, and creates a list of the separate strings separated by a comma.

split has the syntax:

split([field], delimiter)

• Example - A string is split at the delimiter character $.

split("My$Cool$String", "$") 

The output is a list:

["My", "Cool", "String"]

Using the field_exists Operator

The field_exists operator tests whether the specified field exists.

switch device.specific_data.data.name
case field_exists then form.field set_value "exists"

Tests whether the field device.specific_data.data.name exists. If true, sets the value of form.field to "exists".

Using lt in Switch Statements

The lt operator (less than) compares numeric field 1 to numeric field 2 or to a number, and if numeric field 1 is smaller, performs the "then" clause.

• Example - The following example compares two device fields fetched from the adapter.
  • Compares the value of custom_intest to the value of custom_intest2.
  • If custom_intest < custom_intest2, then sets the tag-name field on the form to "failure".

switch device.adapters_data.gui.custom_intest
case lt ([device.adapters_data.gui.custom_intest2]) then form.tag_name set_value "failure"

Using gt in Switch Statements

The gt operator (greater than) compares numeric field 1 to numeric field 2 or to a number, and if numeric field 1 is greater, performs the "then" clause.

• Example - The following example compares two device fields fetched from the adapter.
  • Compares the value of custom_intest to the value of custom_intest2.
  • If custom_intest > custom_intest2, then set the tag-name field on the form to "success".

switch device.adapters_data.gui.custom_intest
case gt ([device.adapters_data.gui.custom_intest2]) then form.tag_name set_value "success"

Using the Wildcard Character in Statements

You can use the wildcard character * in conditional statements.

Using Operators with Arrays (Lists)

When testing an array with any of the operators below, if at least one value matches, the result is TRUE.

This works for the following operators:

• contains
• starts_with
• not_starts_with (no matches)
• ends_with
• not_ends_with
• gt
• lt

Nesting Functions

You can nest functions (functions within functions) when writing conditional statements.

• Example - The following statement includes a sum function within the concat function.

  • sum() - Adds the values in the device.specific_data.data.field array.
  • concat("sum is", sum()) - Adds "sum is" before the calculated sum sum().
  • set_value concat("sum is", sum()) - Sets the tag name on the form (form.tag_name) to "sum is" followed by the calculated sum of the list values. For example: "sum is 124".

  device all then form.tag_name set_value concat("sum is", sum([device.specific_data.data.field]))