Microsoft Defender for Endpoint-API – Hallo Welt

Gilt für:

• Microsoft Defender für Endpunkt Plan 1
• Microsoft Defender für Endpunkt Plan 2

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 bitte die URIs, die in Microsoft Defender for Endpoint 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 In Ihrem Microsoft Entra Mandanten eine entsprechende Rolle zugewiesen sein. Weitere Informationen zu Rollen finden Sie unter Berechtigungsoptionen.

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.

   

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 ihrer Anwendungsseite API-Berechtigungen> Berechtigungs-APIs >hinzufügenaus,die mein organization 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.

     

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

     

     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.

   

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!

   

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

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

   

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 .

  

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

Verwandte Artikel

• Microsoft Defender for Endpoint-APIs
• Zugreifen auf Microsoft Defender for Endpoint mit Anwendungskontext
• Zugreifen auf Microsoft Defender for Endpoint mit Benutzerkontext

Tipp

Möchten Sie mehr erfahren? Engage mit der Microsoft-Sicherheitscommunity in unserer Tech Community: Microsoft Defender for Endpoint Tech Community.