Metadados de script

Para que um script seja usado no Security Controls, ele deve conter metadados que o identifiquem de forma exclusiva e descrevam suas funcionalidades e parâmetros de entrada. Esta seção descreve como criar esses metadados.

Vamos começar com um script simples, de uma linha, que tem um parâmetro de entrada:

Get-Service $serviceName -ComputerName "$ST_ComputerName"

O script completo, com os metadados exigidos pelo Security Controls, é mostrado abaixo. Algumas informações são opcionais, e cada elemento será descrito em detalhes posteriormente.

<name>GetServices</name>

<author>Minha Empresa</author>

<modifiesTarget>false</modifiesTarget>

</options>

<category>Informação</category>

<purpose>Obter os serviços na máquina alvo</purpose>

<inputs>Curinga do nome de serviço</inputs>

<outputs>Lista de serviços instalados</outputs>

</description>

<name>serviceName</name>

<description> Serviços curinga a consultar </description>

</parameter>

</parameters>

</stScript>

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Bloco de metadados

Os metadados são um fragmento de XML dentro de um comentário do script.

Os delimitadores de comentários do script são "<#" e "#>". Para os nossos propósitos, esses delimitadores devem estar sozinhos nos linhas e começar na coluna 1.

O elemento raiz do documento XML é "stScript". Ele tem um atributo, o identificador exclusivo do script. Trata-se de um identificador global exclusivo (GUID, na sigla em inglês). O GUID é especificado por 32 caracteres hexadecimais, no formato "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx". Existem muitas ferramentas convencionais para gerar GUIDs.

Os elementos inicial e final devem estar em linhas independentes, começando na coluna 1. Portanto, todo script usado no Security Controls deve começar com estas duas linhas (com um GUID diferente para cada script):

e terminar com estas duas linhas:

</stScript>

Os outros elementos devem aparecer na ordem descrita abaixo.

name

Este elemento obrigatório fornece o nome do script, da forma como aparecerá no Security Controls. O nome deve ter entre 1 e 100 caracteres. O nome pode conter espaços e caracteres especiais.

Exemplo:

<name>GetServices</name>

version

Este elemento obrigatório especifica a versão do script. A versão é especificada com quatro números inteiros separados por pontos. Quando você modifica um script, a versão mais recente dele deve ser maior que todas as versões anteriores que você já usou.

Exemplo:

author

Este elemento obrigatório identifica o autor do script. É comum usar o nome do autor ou o nome da empresa. Este campo deve ter entre 1 e 256 caracteres e não deve ficar em branco.

Exemplo:

<author>Minha Empresa</author>

scriptType

Este elemento opcional especifica o tipo de execução do script. Ele tem o atributo obrigatório “type”, que deve conter uma das seguintes opções:

type = “any” indica que o script é executado em uma ou mais máquinas alvo, mas não requer comunicação remota do PowerShell. Este é o tipo de script mais comum, sendo o padrão se o elemento scriptType não for especificado.
type = ”consoleOnly” indica que o script não é executado em um conjunto de máquinas alvo. Este tipo de script não pode ser executado em grupos de máquinas ou máquinas selecionadas. Tal script aparecerá nos scripts disponíveis apenas quando você selecionar Ferramentas > Executar ITScripts de Console no menu do Security Controls.
type = ”remote” indica que o script é executado em uma ou mais máquinas alvo e exige que a comunicação remota do PowerShell esteja disponível e configurada nas máquinas alvo.
type = ”esxServer” indica que o script é executado em um servidor ESXi ou vCenter. Scripts desse tipo são executados apenas em grupos de máquinas que contêm servidores ESXi. Se o grupo de máquinas contiver outras máquinas, elas serão ignoradas quando o script for executado.

Exemplo:

minEngineVersion

Este elemento opcional especifica a versão mínima do mecanismo ITScripts que é necessária para executar o script. Se não for especificado, o script deve ser escrito para rodar com qualquer versão do mecanismo ITScripts.

Exemplo:

modifiedTarget

Este elemento opcional indica se o script faz alguma modificação nas máquinas alvo. Se não for especificado, assume como padrão "false", sugerindo que o script apenas coleta informações, mas não modifica as máquinas alvo. É apenas para documentação. Seu valor não garante que o script não modificará as máquinas alvo.

Exemplo:

<modifiesTarget>false</modifiesTarget>

options

Este elemento opcional e seus quatro subelementos informam ao mecanismo ITScripts quais arquivos de saída padronizados devem ser gerados. Por padrão, o mecanismo gerará estes arquivos de saída padronizados:

runoutput.txt: um arquivo para a execução inteira, se alguma saída for gerada
runerror.txt: um arquivo para a execução inteira, se forem detectados erros
machineoutput.txt: um arquivo para cada máquina alvo, se qualquer saída de máquina for gerada
machineerror.txt: um arquivo para cada máquina alvo, se erros forem detectados

Se você especificar o seguinte parâmetro nos metadados, os arquivos runoutput.txt e runerror.txt não serão gerados:

Se você especificar o seguinte parâmetro nos metadados, os arquivos machineoutput.txt e machineerror.txt não serão gerados:

Se desejar que os arquivos machineoutput.txt de todas as máquinas sejam concatenados no arquivo runoutput.txt e que todos os arquivos machineerror.txt sejam concatenados em runerror.txt, especifique esta opção:

Se optar por combinar os arquivos de saída e erro individuais das máquinas, poderá excluir os arquivos individuais especificando o seguinte:

Exemplo:

</options>

concurrency

Este elemento opcional especifica o nível padrão máximo de simultaneidade a ser usado quando um script é executado em um conjunto de máquinas alvo. Você pode substituí-lo no Security Controls criando um modelo ITScripts e especificando um valor de simultaneidade diferente. Se não especificado, a simultaneidade máxima padrão é definida como 32.

Exemplo:

description

O elemento "description" e seus quatro subelementos são todos obrigatórios. As informações inseridas aqui serão exibidas dentro do Security Controls.

purpose

O elemento obrigatório "purpose" é um filho do elemento descrição. Deve conter entre 1 e 1024 caracteres. Ele deve conter uma descrição concisa e precisa da finalidade do script.

inputs

O elemento obrigatório "inputs" é um filho do elemento descrição. Deve conter entre 1 e 1024 caracteres. Ele deve descrever com precisão os parâmetros de entrada exigidos pelo script. Se não houver parâmetros de entrada, basta especificar "Nenhum".

outputs

O elemento obrigatório "outputs" é um filho do elemento descrição. Deve conter entre 1 e 1024 caracteres. Ele deve descrever com precisão a saída gerada pelo script.

Exemplo:

<category>Informação</category>

<purpose>Obter os serviços na máquina alvo</purpose>

<inputs>Curinga do nome de serviço</inputs>

<outputs>Lista de serviços instalados</outputs>

</description>

parameters

O elemento "parameters" deve ser especificado se o script exigir algum parâmetro de entrada. Deve haver um elemento filho "parameter" para cada parâmetro de entrada. Cada elemento "parameter" deve ter três elementos filhos:

name: o nome do parâmetro de entrada sem '$' à esquerda. O nome deve ser o nome da variável válida do PowerShell usada no script.
description: esta descrição aparecerá no Security Controls.
default: este elemento especifica o valor padrão a ser usado no parâmetro se o usuário não especificar outro valor em um modelo ou quando iniciar ou agendar a execução do script. Se o padrão for uma string, coloque-a entre apóstrofos ou aspas. Os apóstrofos permitem que a string contenha caracteres com significado especial no PowerShell, como $ e aspas. Para colocar tais caracteres dentro de aspas, preceda-os de um caractere de crase (`).

Exemplo:

<name>serviceName</name>

<description>Serviços curinga a localizar</description>

</parameter>

</parameters>