Use functions in rules to identify specific information about resource types. Functions use the following syntax:
<function>(<argument>)
Following are the functions used in NGL:
len
Usage: len is a function which calculates the length of a list property or a string property, and returns it as an integer value.
Syntax: len(list_property1)
Example:
microsoft365 malwarefilterpolicy should-have len(FileTypes) > 0
Explanation: NGL will return all Microsoft365 apps’ malware filter policy whose length of file type is greater than 0.
age
Usage: age is a function which calculates the time difference of a time property till the current time. It takes two parameters, the time property name and unit of time as a string, and returns an integer representing the time difference of that time property measured in the units provided to the function. The value of the property should be an integer representing an Epoch (Unix) time. days and hours as time units are supported.
Syntax: age(time_property1, “unit_of_time”)
Example:
github repository should-have age(created_at , "days") > 1
Explanation: NGL will return a list of GitHub repositories which have been created before 1 day and greater.
text match
Usage: textmatch is a function which evaluates the specified regular expression against a given string property. If the string contains the pattern, It returns true otherwise false. See different expressions used with textmatch in How to use the textmatch function article.
Syntax: textmatch(string_property, regex_pattern)
Example:
azuread oauth2permissiongrant should-not-have textmatch(scope, "AppRoleAssignment.ReadWrite.All") = true
Explanation: NGL will generate findings if the ‘scope‘ value is equal to the string “AppRoleAssignment.ReadWrite.All” (i.e. true).
Common Errors
This section outlines errors that may occur with the functions.
| Error Scenario | Incorrect NGL Example | Sample Error Message | Steps to fix the error |
|---|---|---|---|
| Undefined function | AzureAD oauth2permissiongrant should-not-have text-match(scope, "AppRoleAssignment.ReadWrite.All") = true | Error: undefined function text-match | Use correct function name. For example: AzureAD oauth2permissiongrant should-not-have textmatch(scope, "AppRoleAssignment.ReadWrite.All") = true |
| Wrong type for len function | AzureAD User should-have len(employeeHireDate) = 5 | Error: len() only supports string and list type, got number | Use a property that satisfies the required data type. See DOM files to learn more. For example: AzureAD User should-have len(mobilePhone) < 11 |
| First parameter for textmatch is not a property | AzureAD User should-have textmatch("5", "5") = true | Error: textmatch() only accepts property as the first parameter, got string. | Use first parameter as property in textmatch. See textmatch function for more info. For example: AzureAD User should-have textmatch(department, "eng") = true |
| Property used for textmatch is not a string nor a list of string | AzureAD User should-have textmatch(employeeHireDate, "department") = true | Error: textmatch() only supports a property of data type 'string' or 'list | Use a property that satisfies the required data type. For example:AzureAD User should-have textmatch ( department, "Retail") = true |
| Second parameter for textmatch is not string | AzureAD User should-have textmatch (department, 5) = true | Error: textmatch() pattern should be a string, got number | Use string pattern to match. For example: AzureAD User should-have textmatch ( department, "Retail") = true |
| First parameter for age is not a property | AzureAD User should-have age("createdDateTime", "days") > 1 | Error: age() only accepts property as the first parameter, got string | Use property as first parameter. For example: AzureAD User should-have age(createdDateTime, "days") > 1 |
| Wrong conversion unit | AzureAD User should-have age(createdDateTime, "years") > 1 | Error: date-time conversion parameter should be days or hours, got years | Use the correct time unit. For example: AzureAD User should-have age(createdDateTime, "days") > 1 |
| Identifier is not a number | AzureAD User should-have age(department, "days") > 1 | Error: age() only supports a property of data type number, got 'department' of type 'string' | Use numeric data type properties with age. For example: AzureAD User should-have age(createdDateTime, "days") > 1 |