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

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 müssen Sie über eine globaler Administrator Rolle in Ihrem Microsoft Entra Mandanten verfügen.

Schritt 1: Create einer App in Microsoft Entra ID

1. Melden Sie sich mit Ihrem globaler Administrator Benutzer bei Azure an.

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

   

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

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

   • Klicken Sie auf der Anwendungsseite auf API-Berechtigungen> Berechtigungs-APIs >hinzufügen,die mein organization verwendet,> geben Sie WindowsDefenderATP ein, und klicken Sie auf WindowsDefenderATP.

     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> Klicken Sie auf Berechtigungen hinzufügen.

     

     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.
     • Um zu ermitteln, welche Berechtigung Sie benötigen, sehen Sie sich den Abschnitt Berechtigungen in der API an, die Sie aufrufen möchten.

5. Klicken Sie auf Zustimmung erteilen.

   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.

   Klicken Sie auf Zertifikate & Geheimnisse, fügen Sie dem Geheimnis eine Beschreibung hinzu, und klicken Sie auf Hinzufügen.

   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 erfolgreich eine Bewerbung 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 die Warnungen der 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 gerade erfolgreich:

• 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

Verwandtes Thema

• 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.