Using Functions, Operators, and Keywords

The following are some of the functions, operators, and keywords that you can use in Dynamic Value statements (also referred to as 'statements') :

• min/max functions
• add, multiply, and divide functions
• subtract function
• Boolean operators
• The contains keyword
• The also operator
• The join function
• The by_key function
• The concat function
• The split function
• The count function
• The Field Exists function
• Using lt in Switch Statements
• Using gt in Switch Statements
• Using the Wildcard Character in Statements
• Using Operators with Arrays (Lists)
• Nesting Functions

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, multiply, and divide Functions

The add, multiply, and divide functions can be used in the same way as concat or sum to add/multiply/divide 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)

divide has the syntax:

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

or

divide (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))

• Example - In the following example, calculation is performed starting with the most internal parentheses, outward. Sets the value of the form.field_integer field, as follows:

  • Adds the following:
    cve_severity.critical_count multiplied by 0.9
    and
    cve_severity.high_count multiplied by 0.6

  • Adds cve_severity.high_count and cve_severity.critical_count.

  • Divides the first sum by the second sum to give the result.

device all then form.field_number set_value divide( add( multiply([device.specific_data.data.software_cves.cve_severity.critical_count], 0.9), multiply([device.specific_data.data.software_cves.cve_severity.high_count], 0.6) ), add([device.specific_data.data.software_cves.cve_severity.high_count], [device.specific_data.data.software_cves.cve_severity.critical_count]) )

Using the subtract Function

The subtract function can be used to return the difference between two numbers (typed or values from fields) or two date-time fields.

subtract has the syntax:

subtract (item1, item2)

• Example - For all devices that match the query, sets the value of the DiffDates field (form.field_number) to the result of the current date and time (the value in device.adapters_data.gui.custom_nowdate) minus the date and time that the asset was last seen (value in device.specific_data.data.last_seen).

device all then form.field_number set_value subtract([device.adapters_data.gui.custom_nowdate], [device.specific_data.data.last_seen]) 

The following screen shows the results of the Enforcement Set run:

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 the value of form.category to 1234. If its value is false, then set the value of form.category to 4567.

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

• Example - If device.rapid7.some_boolean_field does not have the value true, then set the value of form.category to 0000. If it does not have the value false, then set the value of form.category to 1111.

switch  device.rapid7.some_boolean_field
case field_not_equal (true) then  form.category set_value "0000"
case field_not_equal (false) then form.category set_value "1111"

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 also Operator

The also operator enables applying dynamic content on multiple action fields in a single dynamic value statement.

• Relevant for 'switch/case' and 'all' statements.
• In the 'all' statement below: In all devices, set form.field1 to the value of adapter.fieldX or if empty, to the value of adapter.fieldY. Also, set form.field2 to the value of adapter.fieldZ.
• In the 'switch/case' statement below: If the value in adapter.fieldX begins with 'A' then set form.field1 to 'aaa' and also set form.field2 to 'XXX'.

also has the syntax:

device all then form.field1 set_value [adapter.fieldX] or [adapter.fieldY] also form.field2 set_value [adapter.fieldZ] 

switch adapter.fieldX
case starts_with "A" then form.field1 set_value "aaa" also form.field2 set_value "XXX"

• Example -
  The following statement does the following:
  For each device that matches the query, set the tag name (form.tag-name) to "gt 2" and the tag color to green (RGB color #32a852).

device all then form.tag_name set_value "gt 2" also form.color set-value "#32a852"  

The following screen shows the results of running the Axonius - Add Tag to Assets enforcement action with the above statement.

Clicking the Successful link displays the 'successful' devices returned from the Enforcement Set query with their tags. The green "gt2" tag is from the current run.

Clicking a device on the above screen (in this case, the one with the enclosed tag) opens its Asset Profile. You can click the Tags category to see the asset's tags:

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 joined string of vulnerabilities separated by a space and comma (vulnerability1, vulnerability2, ..., vulnerabilityN) and places it 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*.
  

Using the by_key Function for Complex Field Objects

The by_key function accepts a complex field path [adapter_complex_field_path] as input, and searches in the specified object (key_to_search_by) of the complex field for a specified value (value_to_search). It then returns the value from a corresponding specified object (key_to_pick).

by_key has the syntax:

by_key ([adapter_complex_field_path], key_to_search_by, value_to_search, key_to_pick)

• Example -
  The following statement does the following:
  For each device that matches the query, for all tag_key objects in the AWS Adapter Tags complex field (device.adapters_data.aws_adapter.tags) that have the string 'ax:state', returns the string in the corresponding tag_value object. It then creates a tag, by concatenating 'the value for the owner is ' with the returned string.

device all then form.tag_name set_value concat ("the value for the owner is ", by_key ([device.adapters_data.aws_adapter.tags], "tag_key", "ax:state", "tag_value")) 

The following screen shows the results of running the Axonius - Add Tag to Assets enforcement action with the above statement.

Clicking the Successful link displays the devices returned from the Enforcement Set query. The following screen shows the resulting tags of the 'successful' devices (added using Edit Columns).

Clicking a device on the above screen (in this case, the one with the enclosed tag) opens its Asset Profile displaying All Fields.

Under Tables, you can click the Adapter Tags complex field to open its objects arranged in a table. Enclosed under Tag Key (key_to_search_by) is ax:state (value_to_search). The function returns 'remove' under Tag Value (key_to_pick).

You can click the Tags category to see the asset's tag:

Using the concat Function for String Arguments

The concat function concatenates the string arguments (values and/or single value string type fields) in a list.

concat has the syntax:

concat (item1, item2,…, itemN)

• 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:

  itemarray.1, itemarray.2, ..., itemarray.n 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 count Function

The count function returns the number of values in a list field.

count has the syntax:

count([field])

• Example - Counts the number of CISA vulnerabilities in the device.adapters_data.gui.cisa_vulnerabilities list field and places the number in form.field_number.

device all then form.field_number set_value count([device.adapters_data.gui.cisa_vulnerabilities])

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 dynamic value 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
• in
• not_in
• 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 dynamic value 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]))