Connecteur Microsoft PowerShell

Les fonctionnalités du connecteur Microsoft PowerShell reposent sur le connecteur Python Script générique . Elles sont implémentées par un script Python, powershell-event.py , fourni par Matrix42 à partir de la version 2026.1. Ce script permet d'appeler les scripts PowerShell des clients depuis un serveur Windows distant via une connexion SSH.

Lorsque Microsoft PowerShell Connector est utilisé, il requiert que

• Le client possède son propre serveur Windows hébergeant ces scripts PowerShell pour appeler
• Ce même serveur Windows doit avoir un serveur SSH activé et configuré pour prendre en charge l'authentification par clé privée/publique (les autres méthodes d'authentification ne sont pas prises en charge).
• Le client a créé un utilisateur Windows disposant des autorisations nécessaires pour exécuter des scripts MS PowerShell et se connecter au serveur via SSH.
• Les détails du connecteur sont renseignés et la tâche basée sur un événement est configurée pour déclencher PowerShell.
• Le flux de travail doit contenir un nœud d'orchestration pour appeler la tâche événementielle et la déclencher.
• Matrix42 crée une paire de clés privée/publique et envoie la clé publique au client. Cette clé publique doit être configurée sur le serveur SSH. Matrix42 configure ensuite la clé privée dans la configuration du connecteur.

Fonctionnalités non prises en charge

• PowerShell ne peut pas être déclenché à partir de tâches planifiées à l'aide de ce script Python powershell-event.py

Configurer le connecteur

Pour accéder à la gestion des connecteurs, l'utilisateur doit disposer des autorisations nécessaires pour la configuration de la plateforme.

1. Ouvrez la zone d'administration (symbole d'engrenage).
2. Ouvrir la vue des connecteurs.
3. Choisissez + nouveau connecteur

4. Sélectionnez Generic Python Script comme type de source de données.

5. Fournir les informations

• Indiquez le nom unique du connecteur.
• Sélectionnez powershell-event.py script provenant du champ de script de provisionnement.
• Un mot de passe de chiffrement des paramètres est nécessaire pour masquer/révéler les paramètres après l'enregistrement du connecteur (n'oubliez pas de stocker le mot de passe dans un endroit sûr).
  
  Exemple de commande Linux pour générer une paire de clés privée/publique :
  ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_windows_automation
  Laissez le champ du mot de passe vide.
  
  Les paramètres doivent être au format exact suivant :
  { "ssh": {"private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\nb4ClbnNzaC1rZXktdjEAbbAABG5vbmUAAAAxxxxxxQAAAAAAAAABAAAAMwAAAAtzc2gtZW\nQyNTUxOQAAACB2zQv/80M8ICgv95iT7jCIxnn/YL1tzLvm6S+QaC3bDAAAALBayLNTWsiz\nUwAAAAtzc2gtZWQyNTUxOQAAACB2zQv/80M8ICgv95iT7jCIxnn/YL1tzLvm6S+QaC3bDA\nAAAEAeY5TsWlBuSeX+3Sz/tJTqJU+XgpHHr7QjfRlbr/f7RHbNC//zRXsgKC/3mJPuMIjG\nef9gvW3Mu+bpL5BoLdsMAAABKXJpa3BuaWVtaW5lbkBSaWt1cy1NYWNCb29rLVByby0yMD\nI0LmxvY2FsAQIDAB==\n-----END OPENSSH PRIVATE KEY-----", "user": "MATRIX42\\sshrunneruser", "host": "1.2.3.4", "timeout": 30,    "remote_command": { "executable": "powershell.exe", "arguments": ["-No Pro file" ]  } }, "redirect_stderr_to_stdout": true}
  
  Les sauts de ligne de la valeur private_key doivent être remplacés par \n comme dans l'exemple ci-dessus. Cette clé privée sert à la connexion user au serveur Windows via SSH.
  user est un utilisateur utilisé pour se connecter au serveur Windows et exécuter des scripts PowerShell.
  host correspond à l'adresse IP ou au nom d'hôte du serveur Windows qui contient ces scripts PowerShell.
  timeout peut être laissé à sa valeur par défaut de 30, comme dans l'exemple ci-dessus.
  remote_command doit être exactement comme dans cet exemple ci-dessus

• Un utilisateur WebAPI est nécessaire lorsque le connecteur écrit des données dans la solution du client.
• Le mot de passe WebAPI est requis lorsque le connecteur écrit des données dans la solution du client.

6. Enregistrez le connecteur à l'aide du bouton Enregistrer. Le connecteur est maintenant configuré et vous pouvez passer à la configuration de la tâche basée sur les événements.

Configurer la tâche basée sur les événements

Créer une nouvelle tâche basée sur un événement

1. Définir un nom de tâche descriptif
2. Utilisation de la tâche : Événement
3. Type de mappage : Modèle générique
4. Définir le modèle cible : à partir duquel les données sont envoyées à cette tâche d’événement
5. Définir le dossier cible : à partir duquel les données sont envoyées à cette tâche événementielle

6. Créer des mappages

Vous devez toujours avoir au moins un mappage : ps_script_path_and_name, qui doit être associé à un attribut contenant ces informations ; sinon, la tâche d'événement ne saura pas quel script PowerShell déclencher.

De plus, vous pouvez avoir un ou plusieurs paramètres. Vous devez les associer à une table de correspondance nommée exactement comme dans l'exemple : paramètre1, paramètre2, paramètre3, etc., selon le nombre de paramètres attendus par votre script PowerShell.

7. Enregistrer la tâche de l'événement.
8. Ensuite, vous devez créer un flux de travail avec un nœud d'orchestration appelant cette tâche d'événement.

Tâche d'appel d'événement depuis le flux de travail

Ajoutez un nœud d'orchestration à votre flux de travail.

1. Nom - définir un nom descriptif
2. Description
3. Orchestration - Connecteurs natifs
4. Source de données - Python Script générique
5. Activité - Exécuter la tâche d'événement
6. Cible - Sélectionnez la tâche d'événement que vous avez créée précédemment à cet effet.
7. Réponse - sélectionnez l'attribut utilisé pour stocker la sortie PowerShell exécutée avec succès
8. Exception de Pro : sélectionnez l’attribut utilisé pour stocker les messages d’erreur de l’appel PowerShell ayant échoué.

Format de script PowerShell pris en charge par notre connecteur Microsoft PowerShell

• Lit les paramètres du script sous forme de paramètres de type chaîne de caractères (comme dans l'exemple).
• Peut contenir de 0 à n paramètres.
• Quittez le script avec le code de sortie 0 en cas de succès. Vous pouvez également renvoyer un message de confirmation au format JSON, à stocker dans le champ de réponse du nœud de la carte de données.
• Quitter le système avec un code de sortie supérieur à 0 en cas d'erreur. Vous pouvez également renvoyer le message d'erreur au format JSON, afin de le stocker dans le champ d'exception de provisionnement de la carte de données.

L'exemple vérifie que deux paramètres ont été fournis, puis les enregistre dans un fichier sur une machine Windows. Si le premier paramètre est égal à « failuretest », un code d'erreur et un message sont renvoyés au flux de travail.

param (
    [string]$Param1,
    [string]$Param2
)

# Validate required parameters
if ([string]::IsNullOrEmpty($Param1) -or [string]::IsNullOrEmpty($Param2)) {
    $errorJson = @{ error = "Wrong number of attributes for Powershell script" } | ConvertTo-Json -Compress
    Write-Output $errorJson
    exit 1
}

# Folder where this script is located
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
$file = Join-Path $scriptDir "pstest.txt"

# Failure case
if ($Param1 -eq "failuretest") {
    $errorJson = @{ error = "Calling powershell FAILED" } | ConvertTo-Json -Compress
    Write-Output $errorJson
    exit 1
}

# Success case: write file
"$Param1`n$Param2" | Out-File -FilePath $file -Encoding UTF8 -Force

$successJson = @{ response = "Calling powershell successfull" } | ConvertTo-Json -Compress
Write-Output $successJson
exit 0