Compliance definitions scripting

Edit online

Standard native, native command and modelled definitions support basic ‘matching' and ‘not matching' capability. Use cases have arisen whereby other forms of matching logic are required and have led to the creation of a script-based definition. Script-based definitions allow the user to compose their own validation logic and hence are in full control of what they are trying to validate. Scripting also allows users to extract and retrieve information from an external source to be used as part of the compliance check.

Syntax

The script must include a function named calculate that accepts one parameter and returns true or false to indicate that the compliance evaluation has succeeded or failed.

Note: The parameter names are not fixed.

Here is an example of the script syntax:

function calculate(helper) {
    //enter javascript logic here
    return true;
}

This could also be written as:

function execute(helperMethods) {
    //enter javascript logic here
    return true;
}

At script runtime, the workflow engine passes the helper class to the function. Whatever name is chosen for the parameter, the name must be used within the body of the function.

Methods

In order to describe the methods that are available for each class, the parameter names in the first example from the Syntax section will be used.

The helper class that is passed into the script function provides a set of utility methods for accessing network resource data, running regular expressions and xpaths and also the ability to run external commands to retrieve information from an external source.

Table 1. Helper methods that support the helper class
Method	Description	Example
String getDeviceName()	Retrieves the device name for the device being validated	var name = helper.getDeviceName();
String getDeviceVendor()	Retrieves the device vendor for the device being validated	var name = helper.getDeviceVendor();
String getDeviceType()	Retrieves the device type for the device being validated	var dType = helper.getDeviceType();
String getDeviceModel()	Retrieves the device normalised model for the device being validated	var model = helper.getDeviceModel();
String getDeviceActualModel()	Retrieves the device actual model for the device being validated	var actualModel = helper.getDeviceActualModel();
String getDeviceOS()	Retrieves the device OS for the device being validated	var os = helper.getDeviceOS();
String getGlobalParameter(String parameterName)	Retrieves a global parameter value that was added to the parameter list within the script definition.	var ntpServerIP = helper.getGlobalParameter(“NTPServerIP”);
List<String> getGroupParameter(String parameterName)	Retrieves values for a group parameter that was added to the parameter list within the script definition.	var loghostList = helper.getGroupParameter(“LoggingServers”);
List<String> getExtractionParameter(String parameterName)	Retrieves values for a extraction parameter that was added to the parameter list within the script definition.	var FEsList = helper.getExtractionParameter(“ExtractFEs”);
void addInfo(String info)	Adds user defined messages to the evaluation log. These messages will be shown in the results data.	helper.addInfo(“This is a message that I want displayed in results”);
List<String> getInfo()	Retrieves the current list of informational messages
boolean regexSearch(String data, String regex)	This utility method supports running a regular expression on a specified piece of data and returns true or false if it finds a match.	var result = helper.regexSearch(getNativeConfig(), “^hostname\s bfotest$”);
boolean xpathSearch(String data, String xpath)	This utility method supports running a xpath on a specified piece of data and returns true or false if it finds a match.	var result = helper.xpathSearch(getModelledConfig(), “configuration/hostname”);
String getNativeConfig()	Retrieves the current native configuration for the device being validated	var nativeConfig = helper.getNativeConfig();
String getModelledConfig()	Retrieves the current modelled configuration for the device being validated	var xmlConfig = helper.getModelledConfig();
List<String> getNativeConfigByDeviceName(String deviceName)	Retrieves the current native configuration for a device where name matches the name passed in.	var nativeConfig = helper.getNativeConfigByDeviceName(“9.111.21.10”);
List<String> getModelledConfigByDeviceName(String deviceName)	Retrieves the current modelled configuration for a device where name matches the name passed in.	var nativeConfig = helper.getModelledConfigByDeviceName(“9.111.21.10”);
String executeSystemCommand(String shellName, String shellArgs, String command, String checksum)	Executes a system command and returns the output of the system command. The system command is a file that contains a shell script. The user must calculate a checksum for the file using icosutil. The checksum must then be entered in a native command set.	var response = helper.executeSystemCommand(“/bin/sh”, “”, “getNetStat.sh”, “<generated checksum>”); To generate a checksum for the script on the server run the following command: `<install_dir>/bin/icosutil CalculateChecksum getNetStat.sh` Important: If an external script is modified after a checksum has been generated, then a new checksum must be generated and the native command set script must be updated.
String executeSystemCommand(String shellName, String shellArgs, String command, String responseRegExp, String checksum)	Executes a system command and returns the result of running a regular expression on the output of the system command. Only the first group match is returned. The system command is a file that contains a shell script. The user must calculate a checksum for the file using icosutil. The checksum must then be entered in a native command set.	var response = helper.executeSystemCommand(“/bin/sh”, “”, “getExternalData.sh”, “^(w+)\s“, <generated checksum>”); To generate a checksum for the script on the server run the following command: `<install_dir>/bin/icosutil CalculateChecksum getExternalData.sh` Important: If an external script is modified after a checksum has been generated, then a new checksum must be generated and the native command set script must be updated.

Disabling scripting

An administration user, that is, a user with View System and Manage System activities, can disable the scripting functionality by setting the following system property to false:

Scripting – Enable script execution: The system checks this property at runtime, and if set to 'false', will not allow scripts to be run.; The default setting is 'true'

Disabling external system commands

An administration user, that is, a user with View System and Manage System activities, can disable external system commands by setting the following system property to false:

Scripting – Enable external system command execution: The system checks this property at runtime, and if set to 'false', will not allow scripts to be run.; The default setting is 'true'

Allowing classes and packages in scripting

To allow external Java classes and packages to be used in a script, the following system properties need to be configured:

Note: In order to change system properties a user must have View System and Manage System activities assigned to their user group.

Scripting - Classes allowed in a script

This system property stores a list of allowed Java classes. It is checked at runtime to determine if classes in a script are permitted.

The default list is empty, which means that no classes are permitted until a system administrator has added them to this list.

The allowed classes list is comma-separated, for example:

java.lang.String

java.lang.String, java.lang.StringBuilder, java.util.ArrayList

Scripting - Packages allowed in a script

This system property stores a list of allowed Java packages. It is checked at runtime to determine if packages in a script are permitted.

The default list is empty, which means that no packages are permitted until a system administrator has added them to this list.

The allowed classes list is comma-separated, for example:

java.util

java.util, java.util.regex, java.text

Setting scripting timeout

An administration user, that is, a user with View System and Manage System activities, can edit the appropriate system property to define the length of time that scripts within a command set or compliance definition are allowed to run without completing before they are stopped:

Scripting - Maximum script execution time: The default script execution limit is 10 minutes, and a system administrator can set a time limit between one and 120 minutes.; If a script within a compliance definition times out, the definition result is marked 'NA'.