Script Metadata

In order for a script to be used in Security Controls, it must contain metadata that uniquely identifies the script and describes its functionality and input parameters. This section will describe how to create that metadata.

Let’s start with a simple one-line script that has one input parameter:

Get-Service $serviceName -ComputerName "$ST_ComputerName"

The complete script with the metadata that is required by Security Controls is shown below. Some of the information is optional, and each element will be described in detail later.

<name>GetServices</name>

<author>My Company</author>

<modifiesTarget>false</modifiesTarget>

</options>

<category>Information</category>

<purpose>Get the services on the target machine</purpose>

<inputs>Wildcard of service name</inputs>

<outputs>List of installed services</outputs>

</description>

<name>serviceName</name>

<description> Wildcard service(s) to query </description>

</parameter>

</parameters>

</stScript>

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Metadata Block

The metadata is an XML fragment inside a script comment.

The script comment delimiters are “<#” and “#>. For our purposes, these delimiters must be on lines by themselves and begin in column 1.

The root element of the XML document is “stScript”. It has one attribute, the unique identifier of the script. This is a globally unique identifier (GUID). A GUID is specified by 32 hex characters in the format “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”. There are many standard tools for generating GUIDs.

The beginning and ending elements must be on lines by themselves, beginning in column 1. Therefore, all script used in Security Controls should begin with these two lines (substituting a different GUID for each script):

and end with these two lines:

</stScript>

The other elements should appear in the order described below.

name

This required element provides the name of the script as it will appear within Security Controls. The name must be between 1 and 100 characters. The name may contain spaces and special characters.

Example:

<name>GetServices</name>

version

This required element specifies the version of the script. The version is specified as four integer numbers separated by periods. When you modify a script, the newer version must have a version which is greater than any previous versions you have used.

Example:

author

This required element identifies the author of the script. It is customary to use either the author’s name or the name of the company. This field must be between 1 and 256 characters and must not be blank.

Example:

<author>My Company</author>

scriptType

This optional element specifies the type of script execution. It has a required attribute, “type”, which must contain one of the following:

type=“any” indicates that the script runs against one or more target machines, but does not require PowerShell remoting. This is the most common script type and is the default if the scriptType element is not specified.
type=”consoleOnly” indicates that the script does not run against a set of target machines. This type of script cannot be run against machine groups or selected machines. Such a script will appear in the available scripts only when your select Tools > Run console ITScripts from the Security Controls menu.
type=”remote” indicates that the script runs against one or more target machines and requires PowerShell remoting to be available and configured on the target machines.
type=”esxServer” indicates that the script runs against an ESXi Server or a vCenter Server. Scripts of this type run only against machine groups that contain ESXi Servers. If the machine group contains any other machines, they will be ignored when this script executes.

Example:

minEngineVersion

This optional element specifies the minimum ITScripts engine version required to execute this script. If not specified, the script should be written to run with any version of the ITScripts engine.

Example:

modifiedTarget

This optional element indicates whether the script makes any modifications to the target machines. If not specified, it defaults to “false”, suggesting that the script only gathers information but does not modify the target machines. This is for documentation only. Its value does not guarantee that the script does not modify the target machines.

Example:

<modifiesTarget>false</modifiesTarget>

options

This optional element and its four sub-elements tell the ITScripts engine which standard output files should be generated. By default, the engine will generate these standard output files:

runoutput.txt: One file for the entire run if any run output is generated
runerror.txt: One file for the entire run if errors were detected
machineoutput.txt: One file for each target machine if any machine output is generated
machineerror.txt: One file for each target machine if errors were detected

If you specify the following in the metadata, the runoutput.txt and runerror.txt files will not be generated:

If you specify the following in the metadata, the machineoutput.txt and machineerror.txt files will not be generated:

If you’d like all the machineoutput.txt files for all machines to be concatenated into the runoutput.txt file, and all the machineerror.txt files concatenated into runerror.txt, then specify this option:

If you choose to combine the individual machine output and error files, then you can choose to delete the individual files by specifying the following:

Example:

</options>

concurrency

This optional element specifies the default maximum concurrency level to use when a script is executed against a set of target machines. You can override this in Security Controls by creating an ITScripts template and specifying a different concurrency value. If not specified, the default maximum concurrency is set to 32.

Example:

description

The “description” element and its four sub-elements are all required. The information entered here will be displayed within Security Controls.

purpose

The required “purpose” element is a child of the description element. It must contain between 1 and 1024 characters. It should contain a concise and accurate description of what the script is used for.

inputs

The required “inputs” element is a child of the description element. It must contain between 1 and 1024 characters. This should accurately describe the input parameters required by the script. If there are no input parameters, simply specify “None”.

outputs

The required “outputs” element is a child of the description element. It must contain between 1 and 1024 characters. This should accurately describe the output generated by the script.

Example:

<category>Information</category>

<purpose>Get the services on the target machine</purpose>

<inputs>Wildcard of service name</inputs>

<outputs>List of installed services</outputs>

</description>

parameters

The “parameters” element must be specified if the script requires any input parameters. There must be one “parameter” child element for each input parameter. Each “parameter” element must have three child elements:

name: The input parameter name with no leading ‘$’. The name must be the valid PowerShell variable name used in the script.
description: This description will appear in Security Controls.
default: This element specifies the default parameter value that will be used for the parameter unless the user specifies an alternate value in a template or when starting or scheduling the script execution. If the default is a string, enclose it in apostrophes or quotes. Apostrophes allow the string to contain characters that have special meaning in PowerShell, such as the $ and quote. To embed such characters within quotes, precede them with the tic character (`).

Example:

<name>serviceName</name>

<description>Wildcard service(s)to find</description>

</parameter>

</parameters>