Metadatos de la secuencia de comandos

Para utilizar una secuencia de comandos en Security Controls, ésta debe contener metadatos que identifiquen de manera unívoca la secuencia de comandos y que describan su función y parámetros de entrada. Esta sección describirá cómo crear los metadatos.

Empecemos con una secuencia sencilla de una sola línea que tenga un parámetro de entrada:

Get-Service $serviceName -ComputerName "$ST_ComputerName"

A continuación se muestra la secuencia de comandos completa con los metadatos que requiere Security Controls. Parte de la información es opcional y cada elemento se describe con más detalle más tarde.

<name>GetServices</name>

<author>Mi empresa</author>

<modifiesTarget>falso</modifiesTarget>

</options>

<category>Información</category>

<purpose>Obtenga los servicios en el equipo de destino</purpose>

<inputs>Comodín del nombre de servicio</inputs>

<outputs>Lista de servicios instalados</outputs>

</description>

<name>serviceName</name>

<description> Servicio de comodín para consultar</description>

</parameter>

</parameters>

</stScript>

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Bloque de metadatos

Los metadatos son un fragmento de XML dentro de un comentario de la secuencia de comandos.

Los delimitadores del comentario de la secuencia de comandos son “<#” y “#>. Para nuestro objetivo, estos delimitadores deben estar en líneas por sí solos y empezar en la columna 1.

El elemento raíz del documento XML es “stScript”. Tiene un atributo, el identificador único de la secuencia de comandos. Este es un identificador único global (GUID). En el formato “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” se especifica un GUID de 32 caracteres hexadecimales. Hay muchas herramientas estándar para generar GUID.

Los elementos del principio y del final deben estar solos en líneas, empezando por la columna 1. Por tanto, todas las secuencias que se usen en Security Controls deberán empezar con estas dos líneas (sustituyendo un GUID distinto para cada secuencia):

y termine con estas dos líneas:

</stScript>

Los otros elementos deberán aparecer en el orden que se describe a continuación.

nombre

Este elemento requerido proporciona el nombre de la secuencia de comandos tal y como aparecerá en Security Controls. El nombre debe tener entre 1 y 100 caracteres. El nombre puede contener espacios y caracteres especiales.

Ejemplo:

<name>GetServices</name>

Versión

Este elemento requerido especifica la versión de la secuencia de comandos. La versión se especifica como cuatro números enteros separados por puntos. Cuando se modifica una secuencia de comandos, la versión más reciente debe tener una versión superior a cualquiera de las versiones anteriores que haya usado.

Ejemplo:

autor

Este elemento requerido identifica al autor de la secuencia de comandos. Se suele usar el nombre del autor o el nombre de la empresa. Este campo debe tener entre 1 y 256 caracteres y no estar en blanco.

Ejemplo:

<author>Mi empresa</author>

scriptType

Este elemento opcional espeifica el tipo de ejecución de la secuencia de comandos. Es un atributo requerido, “tipo”, que debe contener uno de los siguientes:

type=“any” indica que la secuencia de comandos se ejecuta en uno o más equipos de destino, pero no requiere PowerShell remoto. Este es el tipo de secuencia de comandos más común y es la secuencia predeterminada si no se especifica el elemento scriptType.
type=”consoleOnly” indica que la secuencia de comandos no se ejecuta en un conjunto de equipos de destino. Este tipo de secuencia de comandos no se puede ejecutar en grupos de equipos o en equipos seleccionados. Dicha secuencia de comandos aparecerá en las secuencias de comandos disponibles solo cuando seleccione Herramientas > Ejecutar ITScripts de la consola desde el menú Security Controls.
type=“remote” indica que la secuencia de comandos se ejecuta en uno o más equipos de destino y requiere PowerShell remoto para estar disponible y configurado en los equipos de destino.
type=”esxServer” indica que la secuencia de comandos se ejecuta en un Servidor ESXi o un Servidor vCenter. Las secuencias de comandos de este tipo solo se ejecutan en los grupos de equipos que contienen servidores ESXi. Si el grupo de equipos contiene cualquier otro equipo, se ignorarán cuando se ejecute esta secuencia de comandos.

Ejemplo:

minEngineVersion

Este elemento opcional especifica la versión mínima del motor de ITScripts necesario para ejecutar esta secuencia de comandos. Si no se especifica, la secuencia se deberá escribir para ejecutarse en cualquier versión del motor de ITScripts.

Ejemplo:

modifiedTarget

Este elemento opcional indica si la secuencia de comandos lleva a cabo alguna modificación a los equipos de destino. Si no se especifica, por defecto será “false”, lo que sugiere que la secuencia solo recopila información pero no modifica los equipos de destino. Esto es solo para documentación. Su valor no garantiza que la secuencia de comandos no modifique los equipos de destino.

Ejemplo:

<modifiesTarget>falso</modifiesTarget>

opciones

Este elemento opcional y sus cuatro elementos secundarios indican al motor de ITScripts qué archivo de salida estándar tiene que generar. Por defecto, el motor generará estos archivos de salida estándar:

runoutput.txt: un archivo para toda la ejecución si se generó un archivo de salida
runerror.txt: un archivo para toda la ejecución si se detectaron errores
machineoutput.txt: un archivo para cada tipo de equipo si se genera algún resultado de equipo
machineerror.txt: un archivo por cada equipo de destino si se detectan errores

Si especifica lo siguiente en los metadatos, no se generarán los archivos runoutput.txt y runerror.txt

Si especifica lo siguiente en los metadatos, no se generarán los archivos machineoutput.txt y machineerror.txt

Si desea que todos los archivos machineoutput.txt de todos los equipos se concatenen en el archivo runoutput.txt file, y que todos los archivos machineerror.txt se concatenen en el runerror.txt, luego especifique esta opción:

Si elige combinar los resultados y archivos de error de cada equipo, puede elegir eliminar los archivos individuales si especifica lo siguiente:

Ejemplo:

</options>

concurrencia

Este elemento opcional especifica el nivel de concurrencia máximo predeterminado que se usará cuando se ejecute una secuencia en un conjunto de equipos de destino. Puede reemplazar esto en Security Controls mediante la creación de una plantilla de ITScripts y especificando un valor de concurrencia distinto. Si no se especifica, la concurrencia máxima por defecto se ajusta como 32.

Ejemplo:

descripción

El elemento "descripción" y cuatro elementos secundarios son todos necesarios. La información que se introduzca aquí se mostrará en Security Controls.

categoría

El elemento de "categoría" requerida es un secundario del elemento de descripción. La categoría ayuda a organizar las secuencias de comandos. La categoría debe tener entre 1 y 50 caracteres. Las categorías estándar puede incluir: “Configuración”, “Política de grupos”, “Información”, “Mantenimiento”, “Seguimiento” y “Soporte técnico”.

objetivo

El elemento de "objetivo" requerida es un secundario del elemento de descripción. Debe contener entre 1 y 1024 caracteres. Debe contener una descripción concisa y fiel del uso de la secuencia de comandos.

entradas

El elemento de "entradas" requerida es un secundario del elemento de descripción. Debe contener entre 1 y 1024 caracteres. Ésta deberá describir con exactitud los parámetros de entrada necesarios para la secuencia de comandos. Si no hay parámetros de entrada, sencillamente especifique "Ninguno".

resultados

El elemento de "salidas" requerida es un secundario del elemento de descripción. Debe contener entre 1 y 1024 caracteres. Ésta deberá describir con exactitud el resultado generado por la secuencia de comandos.

Ejemplo:

<category>Información</category>

<purpose>Obtenga los servicios en el equipo de destino</purpose>

<inputs>Comodín del nombre de servicio</inputs>

<outputs>Lista de servicios instalados</outputs>

</description>

parámetros

El elemento "parámetro" se debe especificar sin la secuencia de comandos requiere parámetros de entrada. Debe haber un elemento secundario "parámetro" para cada parámetro de entrada. Cada elemento “parámetro” debe tener tres elementos secundarios:

nombre: el nombre del parámetro de entrada sin ‘$’ delante. El nombre debe ser un nombre de variables de PowerShell válido que se use en la secuencia de comandos.
descripción: Esta descripción aparecerá en Security Controls.
predeterminado: este elemento especifica el valor de parámetro predeterminado que se usará para el parámetro, a menos que el usuario especifique un valor alternativo en una plantilla o cuando se inicia o se programa la ejecución de una secuencia de comandos. Si por defecto es una cadena, deberá ir entre comillas. Los apóstrofes permiten que la cadena contenga caracteres con significado especial en PowerShell, como el $ y las comillas. Para insertar estos caracteres entre comillas, ponga delante el carácter de comilla simple (`).

Ejemplo:

<name>serviceName</name>

<description> Servicio de comodín para encontrar</description>

</parameter>

</parameters>