Das Büro-Werkzeug hat Tests. Zwei Dinge fehlen noch, bevor es in eine Pipeline darf: Ein Werkzeug soll jeden Lauf auf bekannte Fehler prüfen, ohne dass ein Mensch hinsieht (das leistet der Analyzer), und es darf nie ein Geheimnis in eine Ausgabe, ein Protokoll oder eine Kommandozeile schreiben. Danach geht es um Azure: Welches Werkzeug, welche Anmeldung, und wie bleibt das Skript auch dort ohne Passwort.

Ausgeführt wurde in PowerShell 7.6.9 mit PSScriptAnalyzer 1.25.0. Was mit einem Azure-Konto, einem Key Vault oder einem Mandanten zu tun hat, ist als nicht ausgeführt, gegen Learn gelesen gekennzeichnet; jeder solche Abschnitt hat einen Teil, der ohne Dienst läuft.

PSScriptAnalyzer: der Prüfer für Skripte

PSScriptAnalyzer liest Ihr Skript, ohne es auszuführen, und meldet Verstöße gegen eine Sammlung von Regeln: nicht empfohlene Muster, Fehler in der Machart, Sicherheitsrisiken. Das Modul installieren Sie wie Pester: Install-PSResource -Name PSScriptAnalyzer -Scope CurrentUser. Ein Skript mit absichtlichen Fehlern, bad.ps1:

PowerShell
param(
    [string]$Password,
    [string]$Folder
)

$unused = 1
gci $Folder | ForEach-Object { Write-Host $_.Name }
Invoke-Expression "Get-Date"
function Remove-Everything {
    Remove-Item $Folder -Recurse
}
PowerShell
Invoke-ScriptAnalyzer -Path .\bad.ps1 | Format-Table Line, Severity, RuleName -AutoSize
Line Severity RuleName
---- -------- --------
   8  Warning PSAvoidUsingInvokeExpression
   2  Warning PSAvoidUsingPlainTextForPassword
   2  Warning PSReviewUnusedParameter
   9  Warning PSUseShouldProcessForStateChangingFunctions
   6  Warning PSUseDeclaredVarsMoreThanAssignments
   7  Warning PSAvoidUsingCmdletAliases

Jede Zeile nennt Zeile, Schwere und Regel. Was die Regeln hier sagen:

  • PSAvoidUsingInvokeExpression: Invoke-Expression führt eine Zeichenkette als Code aus. Gelangt ein fremder Wert hinein, führt Ihr Skript fremden Code aus.
  • PSAvoidUsingPlainTextForPassword: Ein Parameter namens Password mit Typ string. Learn nennt die Namen, auf die die Regel achtet (unter anderem Password, Pass, Passphrase), und verlangt den Typ SecureString.
  • PSUseShouldProcessForStateChangingFunctions: Die Funktion Remove-Everything ändert etwas (ihr Verb ist Remove), kennt aber kein SupportsShouldProcess. Das ist der Analyzer-Spiegel von PS.3.1.
  • PSAvoidUsingCmdletAliases: gci ist ein Alias; in Skripten steht der volle Name.
  • PSUseDeclaredVarsMoreThanAssignments und PSReviewUnusedParameter: Etwas ist zugewiesen oder deklariert und wird nie gelesen. Im Beispiel gehört das zu der Funktion, die den Parameter $Folder des Skripts benutzt, ohne ihn selbst zu deklarieren.

Mit -Fix schreibt der Analyzer, was er sicher reparieren kann, in die Datei. Auf einer Kopie der Datei ausgeführt:

PowerShell
Copy-Item .\bad.ps1 .\fixed.ps1
Invoke-ScriptAnalyzer -Path .\fixed.ps1 -Fix | Out-Null

Danach stand in fixed.ps1: [SecureString]$Password statt [string]$Password und Get-ChildItem statt gci. Die vier anderen Meldungen blieben, weil sie eine Entscheidung verlangen. Heben Sie den Parameter mit -Fix nie unbesehen in Ihr Skript: Aus string wurde SecureString, aber jeder Aufrufer, der dem Skript einen Text übergibt, bricht jetzt. Lassen Sie -Fix deshalb auf einer Kopie laufen und lesen Sie den Unterschied (git diff).

Eine Einstellungsdatei

Welche Regeln gelten, bestimmt eine Einstellungsdatei, damit alle im Team und die Pipeline dieselbe Prüfung fahren. PSScriptAnalyzerSettings.psd1, eine Hashtable:

PowerShell
@{
    Severity     = @('Error', 'Warning')
    ExcludeRules = @('PSAvoidUsingWriteHost')
}

Severity begrenzt auf Fehler und Warnungen (ohne reine Hinweise); ExcludeRules schaltet eine Regel ab, die in Ihrem Projekt keinen Sinn hat. Jede ausgeschaltete Regel gehört begründet, am besten in einer Zeile darüber. Aufruf: Invoke-ScriptAnalyzer -Path . -Recurse -Settings .\PSScriptAnalyzerSettings.psd1. Auf ein Skript, das gegen eine einzelne Zeile verstößt, die Sie bewusst so lassen, passt statt der Einstellungsdatei ein Unterdrückungs-Attribut an der Stelle (das beschreibt Learn unter „Suppressing rules“).

Das Tor in der Pipeline

Invoke-ScriptAnalyzer setzt keinen Exit-Code; es gibt Objekte aus. Eine Pipeline braucht ein Tor, das den Lauf scheitern lässt, wenn es Meldungen gibt. gate.ps1:

PowerShell
param([Parameter(Mandatory)][string]$Path)
$findings = @(Invoke-ScriptAnalyzer -Path $Path -Recurse -Settings "$PSScriptRoot\PSScriptAnalyzerSettings.psd1")
$findings | Format-Table Line, RuleName, ScriptName -AutoSize | Out-String -Width 160
"findings: $($findings.Count)"
if ($findings.Count -gt 0) { exit 1 }

@(…) macht aus dem Ergebnis immer ein Array, sodass .Count auch bei null oder einem Treffer stimmt (denken Sie an @($null).Count aus PS.2). Mit pwsh -NoProfile -File .\gate.ps1 -Path .\bad.ps1 endete der Lauf mit Exit-Code 1 und sechs Treffern; auf das Modul OfficeTools.psm1 aus der letzten Lektion mit 0 und findings: 0. Dass das Modul sauber ist, war kein Zufall: Es hat SupportsShouldProcess, keinen Alias und keine Klartext-Passwörter. Die Manifestdatei OfficeTools.psd1 dagegen bekam beim Prüfen eine Warnung PSUseBOMForUnicodeEncodedFile: New-ModuleManifest hatte (mit der deutschen Spracheinstellung) Kommentare mit Umlauten geschrieben, und die Regel verlangt dafür eine Datei mit Byte-Order-Mark. Wer das Manifest also nach der Erzeugung prüft, sieht diese Meldung zuerst. Lösungen: die Kommentare löschen, die Datei mit BOM speichern oder die Regel für die Datei begründet ausnehmen.