Freigeben über

Hallo Welt für Microsoft Defender XDR REST-API

  • Artikel

Gilt für:

  • Microsoft Defender XDR

Wichtig

Einige Informationen beziehen sich auf Vorabversionen von Produkten, die vor der kommerziellen Veröffentlichung noch erheblich geändert werden können. Microsoft übernimmt mit diesen Informationen keinerlei Gewährleistung, sei sie ausdrücklich oder konkludent.

Abrufen von Incidents mithilfe eines einfachen PowerShell-Skripts

Es sollte 5 bis 10 Minuten dauern, bis dieses Projekt abgeschlossen ist. Diese Zeitschätzung umfasst das Registrieren der Anwendung und das Anwenden des Codes aus dem PowerShell-Beispielskript.

Registrieren einer App in Microsoft Entra ID

  1. Melden Sie sich bei Azure an.

  2. Navigieren Sie zu Microsoft Entra ID>App-Registrierungen>Neue Registrierung.

    Abschnitt

  3. Wählen Sie im Registrierungsformular einen Namen für Ihre Anwendung und dann Registrieren aus. Die Auswahl eines Umleitungs-URI ist optional. Sie benötigen keines, um dieses Beispiel abzuschließen.

  4. Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus,die meine organization verwendet>, geben Sie Microsoft Threat Protection ein, und wählen Sie Microsoft Threat Protection aus. Ihre App kann jetzt auf Microsoft Defender XDR zugreifen.

    Tipp

    Microsoft Threat Protection ist ein früherer Name für Microsoft Defender XDR und wird nicht in der ursprünglichen Liste angezeigt. Sie müssen damit beginnen, seinen Namen in das Textfeld zu schreiben, damit er angezeigt wird. Abschnitt der APIs-Nutzung im Microsoft Defender-Portal

    • Wählen Sie Anwendungsberechtigungen>Incident.Read.All und dann Berechtigungen hinzufügen aus.

      Bereich

  5. Wählen Sie Administratoreinwilligung erteilen aus. Jedes Mal, wenn Sie eine Berechtigung hinzufügen, müssen Sie Administratoreinwilligung erteilen auswählen, damit sie wirksam wird.

    Abschnitt Erteilen der Administratoreinwilligung im Microsoft Defender-Portal

  6. Fügen Sie der Anwendung ein Geheimnis hinzu. Wählen Sie Zertifikate & Geheimnisse aus, fügen Sie dem Geheimnis eine Beschreibung hinzu, und wählen Sie dann Hinzufügen aus.

    Tipp

    Nachdem Sie Hinzufügen ausgewählt haben, wählen Sie den generierten Geheimniswert kopieren aus. Sie können den Geheimniswert nach dem Verlassen nicht mehr abrufen.

    Abschnitt

  7. Notieren Sie ihre Anwendungs-ID und Ihre Mandanten-ID an einem sicheren Ort. Sie werden auf der Anwendungsseite unter Übersicht aufgeführt.

    Abschnitt

Abrufen eines Tokens mithilfe der App und Verwenden des Tokens für den Zugriff auf die API

Weitere Informationen zu Microsoft Entra Token finden Sie im tutorial Microsoft Entra.

Wichtig

Das Beispiel in dieser Demo-App empfiehlt Ihnen zwar, Ihren Geheimniswert zu Testzwecken einzufügen, aber Sie sollten Geheimnisse niemals in eine Anwendung hartcodieren , die in der Produktion ausgeführt wird. Ein Drittanbieter könnte Ihr Geheimnis für den Zugriff auf Ressourcen verwenden. Mithilfe von Azure Key Vault können Sie dazu beitragen, die Geheimnisse Ihrer App zu schützen. Ein praktisches Beispiel für den Schutz Ihrer App finden Sie unter Verwalten von Geheimnissen in Ihren Server-Apps mit Azure Key Vault.

  1. Kopieren Sie das folgende Skript, und fügen Sie es in Ihren bevorzugten Text-Editor ein. Speichern Sie alsGet-Token.ps1. Sie können den Code auch unverändert in PowerShell ISE ausführen, aber Sie sollten ihn speichern, da wir ihn erneut ausführen müssen, wenn wir das Skript zum Abrufen von Vorfällen im nächsten Abschnitt verwenden.

    Dieses Skript generiert ein Token und speichert es im Arbeitsordner unter dem Namen Latest-token.txt.

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  client_secret = $appSecret
  grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Überprüfen des Tokens

  1. Kopieren Sie das Token, das Sie erhalten haben, und fügen Sie es in JWT ein, um es zu decodieren.

  2. JWT steht für JSON Web Token. Das decodierte Token enthält eine Reihe von Elementen oder Ansprüchen im JSON-Format. Stellen Sie sicher, dass der Rollenanspruch innerhalb des decodierten Tokens die gewünschten Berechtigungen enthält.

    In der folgenden Abbildung sehen Sie ein decodiertes Token, das von einer App mit Incidents.Read.Allden Berechtigungen , Incidents.ReadWrite.Allund AdvancedHunting.Read.All abgerufen wurde:

    Der Abschnitt Decoded Token im Microsoft Defender-Portal

Abrufen einer Liste der aktuellen Vorfälle

Das folgende Skript verwendet Get-Token.ps1 für den Zugriff auf die API. Anschließend wird eine Liste der Vorfälle abgerufen, die innerhalb der letzten 48 Stunden zuletzt aktualisiert wurden, und die Liste wird als JSON-Datei gespeichert.

Wichtig

Speichern Sie dieses Skript im gleichen Ordner, den Sie Get-Token.ps1gespeichert haben.

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

Fertig! Sie haben folgendes erfolgreich ausgeführt:

  • Erstellt und registriert eine Anwendung.
  • Dieser Anwendung wurde die Berechtigung zum Lesen von Warnungen erteilt.
  • Mit der API verbunden.
  • Es wurde ein PowerShell-Skript verwendet, um Vorfälle zurückzugeben, die in den letzten 48 Stunden aktualisiert wurden.

Tipp

Möchten Sie mehr erfahren? Wenden Sie sich an die Microsoft Security-Community in unserer Tech Community: Microsoft Defender XDR Tech Community.