Метаданные сценариев

Для использования сценария в Security Controls он должен содержать метаданные, которые однозначно идентифицируют сценарий и описывают его функции и входные параметры. В этом разделе представлено создание метаданных.

Начнем с создания простого однострочного сценария с одним входным параметром:

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Далее представлен сценарий с метаданными, необходимых для Security Controls. Некоторая информация является необязательной, а каждый элемент будет подробно описан далее.

<name>GetServices</name>

<author>My Company</author>

<modifiesTarget>false</modifiesTarget>

</options>

<category>Information</category>

<purpose>Получение списка сервисов на целевом компьютере</purpose>

<inputs>Для и имен сервисов используются подстановочные символы</inputs>

<outputs>Список установленных сервисов</outputs>

</description>

<name>serviceName</name>

<description> Для запроса сервисов используются подстановочные символы </description>

</parameter>

</parameters>

</stScript>

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Блок метаданных

Метаданные - это фрагмент кода XML в комментариях сценария.

Комментарии сценария разделяются с помощью “<#” and “#>. В нашем примере эти разделители должны располагаться отдельно на строках и начинаться в столбце 1.

Корневой элемент документа XML - это “stScript”. Он имеет один атрибут - уникальный идентификатор сценария. Он называется GUID (Globally Unique Identifier). GUID указывается в виде 32 шестнадцатиричных символов в формате "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx". Для создания GUID существует множество стандартных приложений.

Начальный и конечный элементы должны находиться в отдельных строках, начиная со столбца 1. Поэтому все сценарии, используемые в Security Controls, должны начинаться со следующих двух строк (использование иного GUID для каждого сценария):

и завершаться двумя следующими строками:

</stScript>

Остальные элементы должны быть представлены в указанном далее порядке.

name

Этот обязательный элемент содержит имя сценария так, как оно будет отображаться в Security Controls. Длина имени должна быть в пределах от 1 до 100 символов. Имя может содержать пробелы и специальные символы.

Пример:

<name>GetServices</name>

version

Этот обязательный элемент содержит версию сценария. Версия указывается в виде четырех целых разделенных точками чисел. После изменения сценария более новый вариант должен иметь более версию в сравнении с любыми ранее использованными версиями.

Пример:

author

Этот обязательный элемент содержит информацию об авторе сценария. Можно указать имя автора или название компании. Это обязательное для заполнения поле и его длина должна быть в диапазоне от 1 до 256 символов.

Пример:

<author>My Company</author>

scriptType

Этот необязательный элемент определяет тип выполнения сценария. Он имеет обязательный атрибут "type", который должен содержать одно из следующих значений:

type=“any” - указывает, что сценарий выполняется на одном или нескольких целевых компьютерах, но не требует удаленного взаимодействия PowerShell. Это наиболее распространенный тип сценария и используется по умолчанию, если не указан элемент scriptType.
type=”consoleOnly” - указывает, что сценарий не запускается для набора целевых компьютеров. Этот тип сценария не может запускаться на группах компьютеров или выбранных компьютерах. Такой сценарий отображается среди доступных сценариев только после выбора "Сервис > Запустить консоль ITScripts" в меню Security Controls.
type=”remote” - указывает, что сценарий запускается на одном или нескольких целевых компьютерах и требует, чтобы на них было доступно и сконфигурировано удаленное взаимодействие PowerShell.
type=”esxServer” - указывает, что сценарий выполняется на сервере ESXi или vCenter. Сценарии этого типа применяются только к группам компьютеров, которые содержат серверы ESXi. Если группа компьютеров содержит другие компьютеры, они будут игнорироваться при выполнении данного сценария.

Пример:

minEngineVersion

Этот необязательный элемент, указывающий минимальную версию программы программы ITScripts, для выполнения этого сценария. Если он не указан, сценарий должен быть создан для работы с любой версией программы ITScripts.

Пример:

modifiedTarget

Этот необязательный элемент указывает, делает ли сценарий какие-либо изменения на целевых компьютерах. Если он не указан, по умолчанию используется значение "false", означающее, что сценарий только собирает информацию, но не изменяет целевые компьютеры. Он используется только для документирования. Его значение не гарантирует, что сценарий не будет вносить изменения на целевых компьютерах.

Пример:

<modifiesTarget>false</modifiesTarget>

options

Этот необязательный элемент и его четыре вложенных элемента сообщают программе ITScripts о том, какие нужно создать стандартные выходные файлы. По умолчанию программа создает следующие стандартные выводные файлы:

runoutput.txt: Один файл для всего выполнения, если ожидается какой-либо вывод.
runerror.txt: Один файл для всего выполнения, если обнаружены ошибки.
machineoutput.txt: Один файл для каждого целевого компьютера, если ожидается какой-либо вывод.
machineerror.txt: Один файл для каждого целевого компьютера, если обнаружены ошибки.

Если вы укажете следующее в метаданных, файлы runoutput.txt и runerror.txt не создаются:

Если вы укажете следующее в метаданных, файлы machineoutput.txt и machineerror.txt не создаются:

Укажите этот параметр, если нужно, чтобы все файлы machineoutput.txt были объединены в файл runoutput.txt для всех компьютеров, а все файлы machineerror.txt - в файл runerror.txt:

Если вы решите объединить выводные файлы и файлы ошибок отдельного компьютера, вы можете удалить отдельные файлы, указав следующее:

Пример:

</options>

concurrency

Этот необязательный элемент определяет максимальный уровень параллелизма по умолчанию, который будет использоваться при выполнении сценария на наборе целевых компьютеров. Вы можете заменить его в Security Controls, создав шаблон ITScripts и указав иное значение параллельного выполнения. Если значение не указано, максимальный параллелизм по умолчанию равен 32.

Пример:

description

Необходимо указать элемент "description" (описание) и его четыре вложенных элемента. Введенная здесь информация будет отображена в Security Controls.

purpose

Обязательный элемент "purpose" (назначение) является дочерним для элемента описания. Длина поля назначения должна быть в пределах от 1 до 1024 символов. Оно должно содержать краткое и точное описание назначения сценария.

inputs

Обязательный элемент "inputs" (вводы) является дочерним для элемента описания. Длина поля назначения должна быть в пределах от 1 до 1024 символов. Оно должно точно описывать используемые в сценарии входные параметры. Если у сценария нет входных параметров, нужно указать "None" (Нет).

outputs

Обязательный элемент "outputs" (выводы) является дочерним для элемента описания. Длина поля назначения должна быть в пределах от 1 до 1024 символов. Оно должно точно описывать создаваемые сценарием выводные данные.

Пример:

<category>Information</category>

<purpose>Получение списка сервисов на целевом компьютере</purpose>

<inputs>Для и имен сервисов используются подстановочные символы</inputs>

<outputs>Список установленных сервисов</outputs>

</description>

parameters

Элемент "parameters" (параметры) должен быть указан, если для сценария обязательно нужно указать какие-либо входные параметры. Для каждого входного параметра должен быть один дочерний элемент "parameter" (параметр). Каждый элемент "параметр" должен иметь три дочерних элемента:

name: Имя вводного параметра без префикса ‘$’. Имя должно быть действительным именем используемой в сценарии переменной PowerShell.
description: Это описание отображается в Security Controls.
default: Этот элемент определяет значение параметра по умолчанию, которое будет использоваться для параметра, если пользователь не укажет иное значение в шаблоне или во время запуска, или во время планирования выполнения сценария. Если по умолчанию используется строка, поместите ее в апострофы или кавычки. Апострофы используются для помещения в строку особых символов PowerShell, например, '$' и кавычек. Для вставки таких символов в кавычки поставьте перед ними символ (`).

Пример:

<name>serviceName</name>

<description>Поиск подстановочных символов</description>

</parameter>

</parameters>