Freigeben über

Microsoft Defender für Endpunkt-API – Hello World

  • Artikel

Gilt für:

Möchten Sie Microsoft Defender für Endpunkt ausprobieren? Registrieren Sie sich für eine kostenlose Testversion.

Hinweis

Wenn Sie ein US Government-Kunde sind, verwenden Sie die URIs, die unter Microsoft Defender für Endpunkt für US Government-Kunden aufgeführt sind.

Tipp

Um die Leistung zu verbessern, können Sie den Server näher an Ihrem geografischen Standort verwenden:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com
  • ina.api.security.microsoft.com

Abrufen von Warnungen mithilfe eines einfachen PowerShell-Skripts

Wie lange dauert es, um dieses Beispiel zu durchlaufen?

Es dauert nur 5 Minuten in zwei Schritten:

  • Anwendungsregistrierung
  • Beispiele verwenden: Erfordert nur das Kopieren/Einfügen eines kurzen PowerShell-Skripts.

Benötige ich eine Berechtigung zum Herstellen einer Verbindung?

Für die Anwendungsregistrierungsphase muss Ihnen die Rolle globaler Administrator in Ihrem Microsoft Entra-Mandanten zugewiesen sein.

Schritt 1: Erstellen einer App in Microsoft Entra ID

  1. Melden Sie sich beim Azure-Portal an.

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

    Die Option

  3. Wählen Sie im Registrierungsformular einen Namen für Ihre Anwendung und dann Registrieren aus.

  4. Gewähren Sie Ihrer Anwendung den Zugriff auf Defender für Endpunkt, und weisen Sie ihr die Berechtigung "Alle Warnungen lesen" zu:

    • Wählen Sie auf der Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus, diemeine Organisation verwendet>, geben Sie WindowsDefenderATP ein, und wählen Sie WindowsDefenderATP aus.

      Hinweis

      WindowsDefenderATP wird nicht in der ursprünglichen Liste angezeigt. Sie müssen damit beginnen, seinen Namen in das Textfeld zu schreiben, damit er angezeigt wird.

      Option

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

      Der Berechtigungstyp und die Einstellungsbereiche auf der Seite API-Berechtigungen anfordern

      Wichtig

      Sie müssen die entsprechenden Berechtigungen auswählen. Alle Warnungen lesen ist nur ein Beispiel.

      Zum Beispiel:

      • Wählen Sie zum Ausführen erweiterter Abfragen die Berechtigung "Erweiterte Abfragen ausführen" aus.
      • Um einen Computer zu isolieren, wählen Sie die Berechtigung "Computer isolieren" aus.
      • Informationen dazu, welche Berechtigung Sie benötigen, finden Sie im Abschnitt Berechtigungen der API, die Sie aufrufen möchten.

  5. Wählen Sie Zustimmung erteilen aus.

    Hinweis

    Jedes Mal, wenn Sie die Berechtigung hinzufügen, müssen Sie auf Zustimmung erteilen klicken, damit die neue Berechtigung wirksam wird.

    Die Berechtigungseinwilligungsoption im Microsoft Entra Admin Center

  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 Hinzufügen aus.

    Wichtig

    Nachdem Sie auf Hinzufügen geklickt haben, kopieren Sie den generierten Geheimniswert. Sie können nicht mehr abrufen, nachdem Sie das Unternehmen verlassen haben!

    Das Menüelement Zertifikate & Geheimnisse im Bereich Verwalten im Microsoft Entra Admin Center

  7. Notieren Sie sich Ihre Anwendungs-ID und Ihre Mandanten-ID.

    Navigieren Sie auf der Anwendungsseite zu Übersicht , und kopieren Sie Folgendes:

    Bereich

Fertig. Sie haben eine Anwendung erfolgreich registriert!

Schritt 2: Abrufen eines Tokens mithilfe der App und Verwenden dieses Tokens für den Zugriff auf die API.

  • Kopieren Sie das folgende Skript in PowerShell ISE oder in einen Text-Editor, und speichern Sie es als Get-Token.ps1.

  • Wenn Sie dieses Skript ausführen, wird ein Token generiert und im Arbeitsordner unter dem Namen Latest-token.txtgespeichert.

    # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application secret here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
     resource = "$resourceAppIdUri"
     client_id = "$appId"
     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

  • Integritätsprüfung:

    • Führen Sie das Skript aus.
    • Navigieren Sie in Ihrem Browser zu: https://jwt.ms/.
    • Kopieren Sie das Token (den Inhalt der Latest-token.txt-Datei).
    • Fügen Sie in das obere Feld ein.
    • Suchen Sie nach dem Abschnitt "Rollen". Suchen Sie die Rolle Alert.Read.All .

    Der Bereich

Lassen Sie uns die Warnungen abrufen!

  • Das folgende Skript verwendet Get-Token.ps1 für den Zugriff auf die API und ruft Warnungen für die letzten 48 Stunden ab.

  • Speichern Sie dieses Skript in dem Ordner, in dem Sie das vorherige Skript Get-Token.ps1gespeichert haben.

  • Das Skript erstellt zwei Dateien (JSON und CSV) mit den Daten im selben Ordner wie die Skripts.

    # Returns Alerts created in the past 48 hours.

$token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1

# Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# The URL contains the type of query and the time filter we create above
# Read more about [other query options and filters](get-alerts.md).
$url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"

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

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

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

# Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json and as csv
$outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
$outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"

Out-File -FilePath $outputJsonPath -InputObject $alerts
($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation

Fertig! Sie haben folgendes erfolgreich ausgeführt:

  • Erstellt und registriert und Anwendung
  • Dieser Anwendung wurde die Berechtigung zum Lesen von Warnungen erteilt.
  • Herstellen einer Verbindung mit der API
  • Verwenden eines PowerShell-Skripts zum Zurückgeben von Warnungen, die in den letzten 48 Stunden erstellt wurden

Tipp

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