Sicherlich kennst du folgendes Szenario: Das Monitoring und das daraus folgende Alerting ist in der Vergangenheit "historisch gewachsen": verschiedene Überwachungs-Tools werden für die unterschiedlichen Bereiche eingesetzt. Doch eines haben sie gleich: Sämtliche Alarme werden per Mail gesendet.

Dies endet darin, dass sich neben Termineinladungen, Abstimmungen und den Fotos des letzten Team-Events haufenweise Alerting-Nachrichten aus den verschiedenen Monitoring-Systemen und Skripten sammeln.

Da die Infrastruktur aber in stetiger Bewegung ist und der manuelle Pflegeaufwand für diese Alerts in den Monitoring-Systemen gleichzeitig wächst, gibt es immer wieder den ein oder anderen Kollegen, der mal wieder vergessen hat die Alert-Einstellungen auf die neuen Anforderungen abzustimmen.

Oft hört man Aussagen wie "Ach, der Alert ist nicht so relevant, der kommt jeden zweiten Sonntag - einfach ignorieren". Nahe liegt dann das Erstellen eines separaten Ordners im eigenen Postfach, in welchen sämtliche Alerts automatisch per Outlook-Regel verschoben werden und somit im Nirwana verschwinden.

Zugegebenermaßen: das hier geschilderte Szenario ist schon recht nahe am Worst-Case einer Alerting-Implementierung. Dennoch findet es so oder ähnlich in vielen Unternehmen statt.

Diese Art des Alerting ist bei den steigenden Anforderung an die Reaktionszeit einer Operations-Abteilung und der rasanten Dynamik einer Infrastruktur nicht mehr zeitgemäß. Alleine der Fakt, dass die Kommunikation über den Alert zwischen den Admins in der Regel nicht über Mail, sondern mittlerweile meist per Teams (oder einem anderen Messenger) stattfindet, lässt daran zweifeln, dass Mails das richtige Medium zur Benachrichtigung darstellen.

Was sind Webhooks?

Sogenannte Webhooks bieten die Möglichkeit Alerts oder andere Benachrichtigungen an einen Microsoft Teams-Kanal zu senden. Hier kann man dann für jeden Abteilungsbereich einen eigenen Teams-Kanal für Monitoring anlegen. Der Abteilungsleiter hat sämtliche Meldung im Überblick ohne, dass dessen Postfach vollläuft.

Man selbst kann entscheiden, welche Bereiche für einen selbst relevant sind und kann diese so konfigurieren, dass man bei einem Vorfall eine Benachrichtigung erhält. Alerts und Benachrichtigungen können direkt kommentiert werden, sodass kein Medienbruch bei der Absprache zwischen den Admins mehr notwendig ist. In diesem Artikel erfährst du wie du mit wenig PowerShell-Code Teams-Alerts wie diesen erstellen kannst:

Beispiel einer Alerting-Nachricht die über einen Webhook in MS Teams gepostet wurde

Hinweis: Webhooks werden natürlich auch außerhalb von Teams verwendet. Sämtliche Messenger unterstützen mittlerweile WebHooks und können (womöglich mit kleinen Abweichungen in der Konfiguration) ähnlich bedient werden.

Bevor wir uns in die Konfiguration eines solchen Webhooks begeben, ein paar Worte zu Webhooks selbst: Eine Anwendung kann sogenannte incoming (oder auch outgoing) Webhooks anbieten. Dazu stellt sie eine eindeutige URL bereit, welche darauf wartet, Web Requests in einer definierten Aufbereitung zu erhalten - vergleichbar mit einer API. Applikationen und Server können somit mit sehr kleinem Konfigurationsaufwand Nachrichten austauschen, was erstmal riesige Möglichkeiten bietet. Wir fokussieren uns in diesem Artikel auf die Möglichkeit eines Monitoring-Alertings.

Teams-Webhooks mit PowerShell erstellen

Wir wollen uns nun also ein konkretes Beispiel für PowerShell-initiierte Webhooks ansehen. Die Auswahl ist dabei groß:

• Wenn Festplatte eines Servers nur noch 10 % Kapazität hat
• Wenn ein Server nicht mehr erreichbar ist
• Wenn die Kapazität eines OneDrive-Accounts fast erschöpft ist und dieses erweitert werden muss
• Wenn die Lizenzen für M365 im Unternehmen in naher Zeit ausgeschöpft sind
• uvm.

Wir wollen uns anschauen wie man Teams-Webhooks dazu nutzen kann Benachrichtigungen zu senden, sobald ein Benutzer-Account im Active Directory gesperrt ist. Somit kann man rechtzeitig reagieren und bemerkt die Sperrung des Users schon, bevor die Programme des Anwenders eine neue Anmeldung fordern.

Das Konzept ist dabei in zwei Teile getrennt: die Konfiguration in Teams und in das PowerShell-Script. PowerShell dient in den meisten Szenarien als "Kleber", welcher die verschiedenen Anwendungen verbindet.

Zur Erklärung: das Active Directory bietet von sich aus keine Möglichkeit, Webhooks zu versenden, sobald ein Nutzer gesperrt wird – diesen Job wird die PowerShell übernehmen.

Konfiguration von Teams

Zur Einrichtung von Webhooks muss ein Kanal eines Teams definiert werden, an den diese gesendet werden sollen. Anschließend kann man die Connectors des Kanals über einen Rechtsklick auf diesen öffnen:

Die Connectors-Einstellungen eines Team-Kanals finden Sie im Kontextmenü

Anschließen lässt sich über "Konfigurieren" bei "incoming Webhook" die Einrichtung der Schnittstelle starten:

Abb. 3: Übersicht der verfügbaren Connectors im Team "Learning IT" 

Nachdem man einen aussagekräftigen Namen vergeben und evtl. ein Icon hochgeladen hat, klickt man "Erstellen" und erhält im Anschluss die URL, über welche wir die Web Requests im PowerShell-Script senden können:

Konfigurieren der Connector-Eigenschaften für den neuen Webhook

Diese URL sollte sicher aufbewahrt werden, da diese natürlich öffentlich ist. Ein Angreifer könnte mit dieser URL Nachrichten in deinen Teams-Channel senden - und das solltest du logischerweise vermeiden!
Nachdem wir die URL kopiert haben, können wir uns im folgendem dem PowerShell-Script widmen.

PowerShell-Script

Für das Senden von Webhooks an Teams wird das sogenannte JSON-Format verwendet. Wer nicht regelmäßig mit JSON arbeitet, wird die Gestaltung eines JSON-Files vermutlich etwas fummelig finden.

ScriptRunner stellt für das Senden von Webhooks an Teams eine Funktion bereit, welche einem das Erstellen von JSON erspart. Diese Funktion werden wir uns im nächsten Artikel dieser Reihe genauer ansehen. In dieser Einführung möchte ich trotz der möglichen Alternativen die Grundlagen aufzeigen. Dazu nutzen wir folgendes Schema für JSON:

[String]$var = "Text, welcher im Nachrichteninhalt erscheint"

$JSONBody = [PSCustomObject][Ordered]@{

    "@type" = "MessageCard"

    "@context" = "<http://schema.org/extensions>"

    "summary" = "Meine erste Alert-Summary!"

    "themeColor" = '0078D7'

    "title" = "Mein erster Alert."

    "text" = "Hier steht die genaue Alertbeschreibung! Variablen kann man natuerlich auch anfuegen: $var"

}



$TeamMessageBody = ConvertTo-Json $JSONBody



$parameters = @{

    "URI" = ''

    "Method" = 'POST'

    "Body" = $TeamMessageBody

    "ContentType" = 'application/json'

}



Invoke-RestMethod @parameters

Wir nutzen hierbei einen Hashtable, den wir mit den Nachrichteninhalten befüllen und anschließend in JSON konvertieren. PowerShell macht uns diesen Task recht einfach.

Anschließend wird mit der Splatting-Technik eine Parameter-Liste erstellt, welche dann um die entsprechende URL der Webhook-Konfiguration ergänzt wird. Wir können somit direkt testen, ob die prinzipielle Kommunikation funktioniert. Bei erfolgreicher Durchführung erhalten wir seitens der PowerShell eine "1" als Rückgabe zurück und die Nachricht erscheint in unserem Teams Channel:

Test-Nachricht

Prima! Du hast nun deinen ersten Webhook an Teams gesendet. Nun habe ich dir aber versprochen ein Script bereitzustellen, das dich per Teams informiert, sobald ein Benutzer im AD gesperrt ist. Hierzu brauchen wir natürlich ein Vorgehen, das erkennt, wenn ein User gesperrt wurde.

Glücklicherweise erzeugt das Windows EventLog einen Eintrag mit EventID 4740 sobald, ein User angelegt wird. Ein solches Event können wir als Trigger verwenden, um unser Script zu starten. Das funktioniert über den Windows Task Scheduler, aber viel praktischer über die ScriptRunner-Oberfläche.

Wir haben nun also erreicht, dass die Nachricht "Mein erster Alert" gesendet wird, sobald ein Benutzer gesperrt wird – sonderlich zielführend ist das noch nicht. Wir müssen daraufhin natürlich noch unser Script anpassen. Dazu benötigen wir eine Funktionalität den gesperrten Benutzer auszulesen und diese Informationen der Nachricht hinzuzufügen:

# Gets locked AD user, that was locked latest

$LockedUser = Search-ADAccount -LockedOut | 
    Get-ADUser -Properties badpwdcount, lockoutTime, lockedout, emailaddress | 
    Select-Object badpwdcount, lockedout, Name, EmailAddress, SamAccountName, @{ Name = "LockoutTime"; Expression = { ([datetime]::FromFileTime($_.lockoutTime).ToLocalTime()) } } | 
    Sort-Object LockoutTime -Descending | 
    Select-Object -first 1



$JSONBody = [PSCustomObject][Ordered]@{

    "@type" = "MessageCard"

    "@context" = "<http://schema.org/extensions>"

    "summary" = "Locked: $($LockedUser.SamAccountName)"

    "themeColor" = '0078D7'

    "title" = "User locked"

    "text" = "`nSamAccountName: $($LockedUser.SamAccountName)" +

        "`nName: $($LockedUser.Name)" +

        "`nMail: $($LockedUser.EmailAddress)" +

        "`nBad Password Count: $($LockedUser.badpwdcount)" +

        "`nTimestamp: $($LockedUser.LockoutTime.ToString())" 


}



$TeamMessageBody = ConvertTo-Json $JSONBody



$parameters = @{

    "URI" = ""

    "Method" = 'POST'

    "Body" = $TeamMessageBody

    "ContentType" = 'application/json'

}



Invoke-RestMethod @parameters

Wir erhalten damit nun folgende Nachricht in Teams:

Das PowerShell-Script hat die gewünschten Informationen erfolgreich über den Webhook in den Teams Channel gepostet

Fazit

Webhooks sind eine moderne Herangehensweise an Alert-Management. Die Vorteile lassen Mail-Alerts klar im Regen stehen, auch wenn diese natürlich ihre Vorteile haben können.

Die PowerShell übernimmt dabei die Funktion des Vermittlers bei Anwendungen, die keine direkte Funktion haben, um Webhooks zu versenden. Ich kann dir die Verwendung von Webhooks nur ans Herz legen und wünsche dir viel Spaß bei der Umsetzung!

Im nächsten Teil dieser Reihe erfährst du, wie du mit einer Funktion, die von ScriptRunner frei auf GitHub bereitgestellt wird, noch einfacher Webhooks-Scripte schreiben kannst. (Hier geht es zu Teil 2 und Teil 3)

Weiterführende Links

• Teams-Webhooks per PowerShell - modernes Alerting (Teil 2/3) | ScriptRunner Blog 
• Teams-Webhooks per PowerShell - modernes Alerting (Teil 3/3) | ScriptRunner Blog
• Web Service Connector: Automation via REST API | ScriptRunner
• Monitoring Event Automation mit Scripten | ScriptRunner Use Case
• So richten Sie eine einfache Serverüberwachung über PowerShell ein | ScriptRunner Blog
• Ereignisbehandlung mit PowerShell und .NET - Teil 1