Titelbild Briefe fliegen aus Monitor

Richtig alarmieren mit PowerShell und Teams-WebHooks

Teil eins: Ein Leitfaden zur Optimierung deiner Alert-Strategie

Vielleicht ist dir diese Situation bekannt: Aus der Historie der IT-Infrastruktur ist das Monitoring und das zugehörige Alerting stetig gewachsen, wobei verschiedene Tools für unterschiedliche Bereiche eingesetzt werden. Gerade beim Alerting haben diese Tools aber oft eines gemeinsam: Die Alarme werden per Mail versendet. Das führt nicht selten dazu, dass sich neben Einladungen zu Terminen, Abstimmungen und Fotos von der letzten Teamveranstaltung eine Menge Alert-Nachrichten aus verschiedenen Monitoring-Systemen und Skripten ansammeln.

Da die Infrastruktur stetig verändert wird und der manuelle Wartungsaufwand für diese Alerts in den Monitoring-Systemen gleichzeitig steigt, werden Anpassungen oftmals vernachlässigt. Schnell stellt sich ein Credo nach dem Motto “Oh, dieser Alert ist nicht so wichtig, er kommt jeden zweiten Sonntag – einfach ignorieren” ein. Es liegt nahe, einen separaten Ordner im eigenen Postfach zu erstellen, in den alle Alerts automatisch per Outlook-Regel verschoben werden und somit in Vergessenheit geraten.

Es ist zuzugeben, dass das hier dargestellte Szenario fast das schlimmstmögliche Beispiel für eine Alerting-Implementierung ist. Trotzdem ist es eine Situation, die in vielen Firmen auftritt. Die aktuelle Art des Alertings ist angesichts der wachsenden Anforderungen an die Reaktionsgeschwindigkeit einer Operationsabteilung und der schnelllebigen Natur der Infrastruktur nicht mehr angemessen. Allein die Tatsache, dass die Kommunikation über Alerts zwischen den Administratoren normalerweise nicht mehr per E-Mail, sondern meistens über Teams (oder einen anderen Messenger) erfolgt, lässt Zweifel aufkommen, ob E-Mails das passende Medium für Benachrichtigungen sind. WebHooks bieten die Möglichkeit, Alerts oder andere Benachrichtigungen an einen Teams-Kanal zu senden. Hier kann jeder Abteilungsbereich seinen eigenen Teams-Kanal für das Monitoring einrichten. Der Abteilungsleiter hat alle Meldungen im Blick, ohne dass sein Postfach überquillt. Jeder kann selbst entscheiden, welche Bereiche für ihn relevant sind und diese so einstellen, dass er bei einem Vorfall benachrichtigt wird. Alerts und Benachrichtigungen können direkt kommentiert werden, wodurch die Notwendigkeit eines Medienwechsels bei der Absprache zwischen den Administratoren entfällt. In diesem Artikel lernst du, wie du mit wenig PowerShell-Code solche Teams-Alerts erstellen kannst – folgende Abbildung zeigt, wie eine solche Alerting-Nachricht aussehen kann.

Hinweis:
Wenn in deiner Organisation alle Zertifikate von einer zentralen Zertifizierungsstelle (CA) ausgestellt wurden, ist es effizienter, eine zentrale Abfrage an die CA zu senden, anstatt jeden einzelnen Server auf seine Zertifikate zu überprüfen. Die genannten 100 Tage sind keine persönliche Empfehlung, da ich diesen Zeitraum für zu lang halte. Ich habe die 100 Tage nur zu Demonstrationszwecken gewählt, um sicherzustellen, dass wir einige Treffer erzielen. Meiner Meinung nach ist ein Zeitraum von 15-30 Tagen für die Überwachung angemessen, obwohl dies natürlich je nach Umgebung variieren kann.

WebHooks

Bevor wir uns mit der Einrichtung eines WebHooks beschäftigen, eine kurze Erläuterung zu Webhooks selbst: Eine Anwendung kann sogenannte eingehende (oder auch ausgehende) WebHooks bereitstellen. Dazu bietet sie eine eindeutige URL an, die darauf wartet, Webanfragen in einem bestimmten Format zu erhalten – ähnlich wie eine API. Anwendungen und Server können so mit minimalem Konfigurationsaufwand Nachrichten austauschen. In diesem Artikel konzentrieren wir uns auf die Möglichkeit, WebHooks für Monitoring-Alerts zu nutzen.

Um den Unterschied zwischen einer REST API und einem WebHook zu verdeutlichen, stell die sich vor, dass du in einem Restaurant bist. Eine REST API ist wie ein Kellner, den du rufen kannst, wenn du etwas brauchst – sei es eine neue Bestellung aufgeben oder die Rechnung anfordern. Du initiierst die Interaktion und der Kellner reagiert entsprechend. Ein WebHook hingegen ist wie ein Kellner, der dir automatisch ein neues Glas Wasser bringt, sobald er sieht, dass dein Glas leer ist. Du musst ihn nicht rufen oder ihm sagen, was zu tun ist. Er hat eine vordefinierte Aufgabe (dein Glas auffüllen, wenn es leer ist) und führt diese aus, sobald das definierte Ereignis (leeres Glas) eintritt. In diesem Sinne wartet der WebHook (der Kellner) auf ein bestimmtes Ereignis und reagiert automatisch darauf.

Teams-WebHooks mit PowerShell

Wir wollen uns nun also ein konkretes Beispiel für PowerShell-initiierte WebHooks ansehen. Mögliche Anwendungsszenarien wären dabei unter anderem:

  • Volllaufende Festplatte
  • Benachrichtigung zum Ablauf eines SSL-Zertifikats
  • Sperrung eines AD-Nutzers

In dieser Reihe zeige ich dir praxisnah, wie Teams-WebHooks zum Senden von Benachrichtigungen genutzt werden können, wenn ein Benutzer-Account im ActiveDirectory gesperrt wird. Auf diese Weise kann man proaktiv handeln und die Sperrung des Benutzers bemerken, bevor die Anwendungen des Benutzers eine erneute Anmeldung verlangen und dieser ein Ticket erstellt bzw. die Support-Hotline anruft. Das Konzept ist in zwei Teile unterteilt:

  • die Teams-Konfiguration
  • das PowerShell-Skript

In den meisten Fällen fungiert PowerShell als “Klebstoff”, der die verschiedenen Anwendungen miteinander verbindet. Zur Klarstellung: Das ActiveDirectory bietet keine eingebaute Möglichkeit, WebHooks zu versenden, wenn ein Benutzer gesperrt wird – diese Aufgabe wird von PowerShell übernommen. Natürlich gibt es auch anderweitige Tools, um diesen Anwendungsfall abzubilden. Der Vorteil bei Verwendung der PowerShell liegt meiner Meinung nach in der größtmöglichen Flexibilität bei der Gestaltung des Alertings (und möglichen Folgeoperationen) und der kostenfreien Nutzung. Dennoch sollten gerade bei großen Infrastrukturen ebenfalls dedizierte Monitoring-Lösungen evaluiert werden.

Konfiguration von Teams

Zur Einrichtung von WebHooks muss ein Kanal/Channel festgelegt werden, an den die Alerts gesendet werden sollen. Anschließend kann man die Connectors des Kanals über einen Rechtsklick auf diesen öffnen. Anschließend lässt sich über “Konfigurieren” bei “incoming WebHook” die Einrichtung der Schnittstelle starten.

Nachdem man eine aussagekräftigen Namen vergeben und evtl. ein Icon hochgeladen hat, klickt man “Erstellen” und erhält im Anschluss die URL, über welche wir die WebRequests im PowerShell-Script senden können. Diese URL sollte vertraulich behandelt werden, da diese public angesprochen werden kann. Ein Angreifer könnte mit dieser URL Nachrichten in deinen Teams-Channel senden (beispielsweise mit Links zu Phishing-Scripts, etc.) – und das solltest du logischerweise vermeiden!

PowerShell

Für das Senden von WebHooks an Teams wird das sogenannte JSON-Format verwendet. In unserem PowerShell-Code nutzen wird ein sogenanntes PSCustomObject, das weiter unten zu JSON konvertiert wird – PowerShell macht uns dies recht einfach. Grundsätzlich kannst du den Code aber einfach kopieren und deine individuellen Werte eintragen. Wichtig ist natürlich, dass du die WebHook-URI von Teams in Zeile 1 hinterlegst.

[String]$uri = "Hier die Webhook Uri eintragen"
[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 -Depth 100
 
$parameters = @{
    "URI"         = $uri
    "Method"      = 'POST'
    "Body"        = $TeamMessageBody
    "ContentType" = 'application/json'
}
 
Invoke-RestMethod @parameters

Anschließend können wir durch Ausführen des Scripts direkt testen, ob die Kommunikation zum WebHook-Endpunkt funktioniert. Bei erfolgreicher Durchführung erhalten wir seitens der PowerShell eine “1” als Rückgabe zurück und die Nachricht erscheint in unserem Teams:

Super! Du hast erfolgreich deinen ersten WebHook an Teams gesendet. Wie versprochen, stelle ich dir nun ein Skript zur Verfügung, das dich über Teams benachrichtigt, sobald ein Benutzer im Active Directory gesperrt wird. Dafür benötigen wir natürlich einen Mechanismus, der erkennt, wenn ein Benutzer gesperrt wurde. Glücklicherweise erzeugt das Windows EventLog einen Eintrag mit der EventID 4740, sobald ein Benutzer gesperrt wird. Dieses Ereignis können wir als Auslöser verwenden, um unser Skript zu starten. Dies kann beispielsweise über den Windows Task Scheduler erfolgen. Das Script zum Auslesen des gesperrten AD-Accounts kann wie folgt aussehen:

# 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

Setzen wir dieses nun mit dem Script zum Versenden des WebHooks zusammen und passen die Werte an, erhalten wir folgenden Code:

# 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

[String]$uri = "Hier die Webhook Uri eintragen"
$JSONBody = [PSCustomObject][Ordered]@{
    "@type"      = "MessageCard"
    "@context"   = "http://schema.org/extensions"
    "summary"    = "Locked: $($LockedUser.SamAccountName)"
    "themeColor" = '0078D7'
    "title"      = "User locked"
    "text"       = "`n 
    SamAccountName:     $($LockedUser.SamAccountName)
    Name:               $($LockedUser.Name)
    Mail:               $($LockedUser.EmailAddress)
    Bad Password Count: $($LockedUser.badpwdcount)
    Timestamp:          $($LockedUser.LockoutTime.ToString()) 
    "
}
 
$TeamMessageBody = ConvertTo-Json $JSONBody -Depth 100
 
$parameters = @{
    "URI"         = $uri
    "Method"      = 'POST'
    "Body"        = $TeamMessageBody
    "ContentType" = 'application/json'
}
 
Invoke-RestMethod @parameters

Wir erhalten damit nun folgende Nachricht in Teams, sofern ein Benutzer gesperrt wurde:

Fazit

WebHooks stellen einen modernen Ansatz für das Alert-Management dar. Sie bieten klare Vorteile gegenüber Mail-Alerts, obwohl auch diese ihre Stärken haben können (beispielsweise hinsichtlich der Dokumentation, etc.). Die PowerShell eignet hierbei hervorragend als Vermittler für Anwendungen, die keine eingebaute Funktion zur Versendung von WebHooks besitzen. Im nächsten Teil dieser Reihe zeige ich dir, wie du die Teams-Alert mithilfe von AdaptiveCards noch weiter gestalten kannst, indem du beispielsweise Buttons hinzufügst, mit denen du direkt per Knopfdruck auf ausgelöste Alerts reagieren kannst – das Ganze natürlich wieder an einem Praxisbeispiel demonstriert.

Über den Autor: Philipp Lorenz

Philipp Lorenz ist Fachinformatiker und Autor für Fachverlage. Bei der heise Academy bietet er Trainings rund um die PowerShell an. Seine Kernkompetenz liegt vor allem in der Automatisierung von Prozessen.


Diese Beiträge könnten dich auch interessieren: