Métadonnées de script

Pour que vous puissiez utiliser le script dans Security Controls, il doit contenir des métadonnées qui l'identifient de manière unique et décrivent ses fonctions et ses paramètres d'entrée. Cette section explique comment créer ces métadonnées.

Commençons par un script d'une seule ligne, très simple, avec un seul paramètre d'entrée :

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Le script complet, avec les métadonnées nécessaires pour Security Controls est présenté ci-dessous. Certaines informations sont facultatives et chaque élément sera décrit en détail plus loin.

<name>GetServices</name>

<author>Mon entreprise</author>

<modifiesTarget>false</modifiesTarget>

</options>

<category>Informations</category>

<purpose>Obtention des services de la machine cible</purpose>

<inputs>Nom de service avec caractère générique</inputs>

<outputs>Liste des services installés</outputs>

</description>

<name>serviceName</name>

<description> Service(s) à interroger, avec caractère générique </description>

</parameter>

</parameters>

</stScript>

Get-Service $serviceName -ComputerName "$ST_ComputerName"

Bloc de métadonnées

On appelle métadonnées un fragment de code XML dans un commentaire de script.

Les délimiteurs de commentaire de script sont « ». Pour nous, ces délimiteurs doivent être seuls sur leur ligne et commencer en colonne 1.

L'élément racine du document XML est « stScript ». Il porte un seul attribut, l'ID unique du script. Il s'agit d'un GUID (ID unique global). Un GUID comprend 32 caractères hexadécimaux, au format « xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ». Il existe de nombreux outils standard pour générer des GUID.

Les éléments de début et de fin doivent être seuls sur leur ligne et commencer en colonne 1. Par conséquent, tous les scripts utilisés dans Security Controls doivent commencer par ces deux lignes (et chaque script contient un GUID différent) :

Et ils doivent finir par ces deux lignes :

</stScript>

Les autres éléments doivent apparaître dans l'ordre indiqué ci-après.

name

Cet élément obligatoire indique le nom du script tel qu'il apparaît dans Security Controls. Le nom doit comprendre entre 1 et 100 caractères. Le nom peut contenir des espaces et des caractères spéciaux.

Exemple :

<name>GetServices</name>

version

Cet élément obligatoire spécifie la version du script. La version est indiquée sous forme de quatre nombres entiers séparés par des points. Lorsque vous modifiez un script, la nouvelle version doit porter un numéro de version supérieur à celui des versions utilisées précédemment.

Exemple :

author

Cet élément obligatoire identifie l'auteur du script. En général, l'on utilise le nom de l'auteur ou celui de son entreprise. Ce champ peut contenir entre 1 et 256 caractères, et ne doit pas être vide.

Exemple :

<author>Mon entreprise</author>

scriptType

Cet élément facultatif spécifie le type d'exécution du script. Il comporte un attribut obligatoire, « type », qui doit porter l'une des valeurs suivantes :

type=“any” indique que le script s'exécute sur une ou plusieurs machines cible, mais n'a pas besoin des fonctions PowerShell à distance. Il s'agit du type de script le plus courant, et du type par défaut si l'élément scriptType n'est pas spécifié.
type=”consoleOnly” indique que le script est exécuté uniquement sur la console, pas sur un ensemble de machines cible. Ce type de script ne peut pas s'exécuter sur des groupes de machines ni sur les machines sélectionnées. Ce type de script apparaît dans la liste des scripts disponibles uniquement quand vous sélectionnez Outils > Exécuter les scripts ITScripts de la console, dans le menu Security Controls.
type=”remote” indique que le script s'exécute sur une ou plusieurs machines cible, et nécessite les fonctions PowerShell à distance pour exister et pouvoir être configuré sur les machines cible.
type=”esxServer” indique que le script est exécuté sur un serveur ESXi ou un serveur vCenter. Les scripts de ce type s'exécutent uniquement sur les groupes de machines contenant des serveurs ESXi. Si le groupe de machines contient d'autres machines, elles sont ignorées lors de l'exécution du script.

Exemple :

minEngineVersion

Cet élément facultatif indique la version minimale du moteur ITScripts nécessaire pour exécuter le script. Si aucune valeur n'est spécifiée, le script doit être écrit pour s'exécuter avec toutes les versions du moteur ITScripts.

Exemple :

modifiedTarget

Cet élément facultatif indique si le script apporte des modifications aux machines cible. Si vous ne spécifiez aucune valeur, le système utilise par défaut « false », qui indique que le script se contente de collecter des informations, sans modifier les machines cible. Utilisé uniquement pour information. Cette valeur ne garantit pas que le script ne modifie pas les machines cible.

Exemple :

<modifiesTarget>false</modifiesTarget>

options

Cet élément facultatif et ses 4 sous-éléments indiquent au moteur ITScripts les fichiers de sortie standard à générer. Par défaut, le moteur génère les fichiers de sortie standard suivants :

runoutput.txt : Un seul fichier pour l'ensemble de l'exécution si une sortie d'exécution est générée.
runerror.txt : Un seul fichier pour l'ensemble de l'exécution si des erreurs ont été détectées.
machineoutput.txt : Un fichier pour chaque machine cible si une sortie machine est générée.
machineerror.txt : Un fichier pour chaque machine cible si des erreurs ont été détectées.

Si vous spécifiez ce qui suit dans les métadonnées, les fichiers runoutput.txt et runerror.txt ne sont pas générés :

Si vous spécifiez ce qui suit dans les métadonnées, les fichiers machineoutput.txt et machineerror.txt ne sont pas générés :

Pour que les fichiers machineoutput.txt de toutes les machines soient concaténés dans le fichier runoutput.txt et que tous les fichiers machineerror.txt soient concaténés dans runerror.txt, spécifiez l'option suivante :

Si vous choisissez de combiner les fichiers de sortie et d'erreur de chaque machine, vous pouvez choisir de supprimer les fichiers séparés en spécifiant ce qui suit :

Exemple :

</options>

concurrency

Cet élément facultatif indique le niveau maximal de simultanéité par défaut à appliquer quand un script est exécuté sur un ensemble de machines cible. Vous pouvez ignorer cette valeur dans Security Controls en créant un modèle ITScripts et en spécifiant une valeur de simultanéité différente. Si aucune valeur n'est spécifiée, le niveau maximal de simultanéité par défaut est défini sur 32.

Exemple :

description

L'élément « description » et ses 4 sous-éléments sont tous obligatoires. Les informations entrées ici s'affichent dans Security Controls.

purpose

L'élément obligatoire « purpose » est un enfant de l'élément description. Il doit comprendre entre 1 et 1 024 caractères. Il doit contenir une description concise et précise du but dans lequel le script est utilisé.

inputs

L'élément obligatoire « inputs » est un enfant de l'élément description. Il doit comprendre entre 1 et 1 024 caractères. Il doit décrire précisément les paramètres d'entrée nécessaires pour le script. S'il n'y a aucun paramètre d'entrée, utilisez simplement « None » (Aucun).

outputs

L'élément obligatoire « outputs » est un enfant de l'élément description. Il doit comprendre entre 1 et 1 024 caractères. Il doit décrire précisément la sortie générée par le script.

Exemple :

<category>Informations</category>

<purpose>Obtention des services de la machine cible</purpose>

<inputs>Nom de service avec caractère générique</inputs>

<outputs>Liste des services installés</outputs>

</description>

parameters

Vous devez spécifier l'élément « parameters » si le script nécessite des paramètres d'entrée. Il doit exister un élément enfant « parameter » pour chaque paramètre d'entrée. Chaque élément « parameter » doit comporter trois éléments enfant :

name : Paramètre d'entrée, sans le caractère $ de début. Le nom indiqué doit être un nom de variable PowerShell valide utilisé dans le script.
description : Cette description s'affiche dans Security Controls.
default : Cet élément précise la valeur par défaut utilisée pour le paramètre si l'utilisateur ne précise aucune autre valeur dans un modèle, ou lors du lancement ou de la planification de l'exécution du script. Si la valeur par défaut est une chaîne, placez-la entre apostrophes ou entre guillemets. Les apostrophes permettent d'inclure dans la chaîne des caractères ayant une signification particulière dans PowerShell, comme $ et les guillemets. Pour mettre ce type de caractère entre guillemets, faites-les précéder d'une apostrophe oblique (`).

Exemple :

<name>serviceName</name>

<description>Service(s) à trouver, avec caractère générique</description>

</parameter>

</parameters>