Łącznik Microsoft PowerShell

Możliwości łącznika Microsoft Powershell są oparte na łączniku Generic Python Script . Funkcjonalność ta jest implementowana przez skrypt Pythona powershell-event.py , dostarczany przez Matrix42 od wersji 2026.1. Skrypt ten odpowiada za wywoływanie skryptów Powershell klientów ze zdalnego serwera Windows przez połączenie SSH.

W przypadku korzystania z programu Microsoft Powershell Connector wymagane jest:

• Klient ma własny serwer Windows, na którym można wywołać skrypty programu PowerShell
• Ten sam serwer Windows musi mieć włączony serwer SSH i być skonfigurowany do obsługi uwierzytelniania kluczem prywatnym/publicznym (inne metody uwierzytelniania nie są obsługiwane).
• Klient utworzył użytkownika Windows z uprawnieniami potrzebnymi do uruchamiania skryptów MS Powershell i logowania się do serwera za pomocą protokołu SSH.
• Szczegóły łącznika są wypełnione, a zadanie oparte na zdarzeniach jest skonfigurowane w celu wyzwalania programu PowerShell.
• Przepływ pracy musi zawierać węzeł Orchestration, aby można było wywołać zadanie oparte na zdarzeniu i go wyzwolić.
• Matrix42 tworzy parę kluczy prywatny/publiczny i wysyła klucz publiczny do klienta. Klucz publiczny musi zostać skonfigurowany na serwerze SSH. Matrix42 konfiguruje klucz prywatny w konfiguracji łącznika.

Funkcje, które nie są obsługiwane

• Nie można uruchomić programu PowerShell z poziomu zadań zaplanowanych za pomocą tego skryptu Python powershell-event.py

Konfiguruj złącze

Aby uzyskać dostęp do zarządzania łącznikami, użytkownik musi mieć uprawnienia do konfiguracji platformy.

1. Otwórz obszar administracyjny (symbol koła zębatego).
2. Otwórz widok złączy.
3. Wybierz + nowy łącznik

4. Wybierz typ źródła danych: Python Script

5. Uzupełnij informacje

• Wpisz unikalną nazwę złącza dla złącza
• Wybierz powershell-event.py skrypt z pola skryptu provisioningowego.
• Hasło szyfrujące parametry jest potrzebne do ukrycia/ujawnienia parametrów po zapisaniu łącznika (pamiętaj, aby zapisać hasło w bezpiecznym miejscu).
  
  Przykładowe polecenie systemu Linux generujące parę kluczy prywatnych i publicznych:
  ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_windows_automation
  Pozostaw hasło puste.
  
  Parametry muszą być podane w następującym formacie:
  { "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}
  
  Podziały wierszy wartości private_key należy zastąpić znakiem \n jak w powyższym przykładzie. Ten klucz prywatny służy do logowania user do serwera Windows przez SSH.
  user to użytkownik używany do logowania się do serwera Windows i uruchamiania skryptów programu PowerShell
  host to adres IP lub nazwa hosta serwera Windows, który zawiera te skrypty programu PowerShell
  timeout można pozostawić na wartości domyślnej 30, jak w powyższym przykładzie
  remote_command powinno wyglądać dokładnie tak jak w powyższym przykładzie

• Użytkownik WebAPI jest potrzebny, gdy łącznik zapisuje dane do rozwiązania klienta
• Hasło WebAPI jest potrzebne, gdy łącznik zapisuje dane do rozwiązania klienta

6. Zapisz złącze za pomocą przycisku „Zapisz”. Złącze jest teraz skonfigurowane i możesz przejść do zadania konfiguracji opartego na zdarzeniach.

Skonfiguruj zadanie oparte na zdarzeniach

Utwórz nowe zadanie oparte na zdarzeniu

1. Ustaw opisową nazwę zadania
2. Wybierz użycie zadania: Wydarzenie
3. Ustaw typ mapowania: Szablon ogólny
4. Ustaw szablon docelowy: z którego dane są wysyłane do tego zadania zdarzenia
5. Ustaw folder docelowy, z którego dane są wysyłane do tego zadania zdarzenia

6. Utwórz mapowania

Zawsze musisz mieć co najmniej jedno mapowanie: ps_script_path_and_name, które powinno być mapowane na atrybut zawierający tę informację, w przeciwnym razie zadanie zdarzeń nie będzie wiedziało, który program PowerShell ma wyzwolić.

Dodatkowo możesz mieć jeden lub wiele parametrów. Musisz je ustawić na tabelę mapowania o nazwie dokładnie takiej jak w przykładzie: parametr1, parametr2, parametr3 itd., w zależności od tego, ile parametrów spodziewa się Twój skrypt programu PowerShell.

7. Zapisz zadanie zdarzenia.
8. Następnie należy utworzyć przepływ pracy z węzłem orkiestracji wywołującym to zadanie zdarzenia.

Wywołanie zadania zdarzenia z przepływu pracy

Dodaj węzeł orkiestracji do swojego przepływu pracy

1. Nazwa - ustaw nazwę opisową
2. Opis
3. Orchestrate - natywne łączniki
4. Źródło danych – ogólny Python Script
5. Aktywność – Wykonaj zadanie zdarzenia
6. Cel — wybierz zadanie zdarzenia utworzone wcześniej w tym celu
7. Respose — wybierz atrybut, który jest używany do przechowywania pomyślnie wykonanych wyników programu PowerShell
8. Wyjątek Pro : wybierz atrybut, który służy do przechowywania komunikatów o błędach nieudanego wywołania programu PowerShell

Format skryptu programu PowerShell obsługiwany przez nasz łącznik Microsoft PowerShell

• Odczytuje parametry skryptu jako parametry łańcuchowe (jak w przykładzie).
• Może zawierać od 0 do n parametrów.
• Wyjście z kodem wyjścia 0 po pomyślnym wykonaniu skryptu. Można również zwrócić komunikat OK w formacie JSON, który zostanie zapisany w polu odpowiedzi węzła karty danych.
• Wyjście z kodem wyjścia większym niż 0 w przypadku wystąpienia błędu. Można również zwrócić komunikat o błędzie w formacie JSON, który zostanie zapisany w polu wyjątku provisioningu karty danych.

Przykładowy magazyn sprawdza, czy podano 2 parametry, a następnie zapisuje je do pliku na komputerze z systemem Windows. Jeśli pierwszy parametr był równy „failuretest”, zwraca kod błędu i komunikat do przepływu pracy.

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