Microsoft Defender för Endpoint API – Hello World

Gäller för:

• Microsoft Defender för Endpoint Abonnemang 1
• Microsoft Defender för Endpoint Abonnemang 2
• Microsoft Defender för företag

Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.

Obs!

Om du är en us government-kund använder du de URI:er som anges i Microsoft Defender för Endpoint för amerikanska myndighetskunder.

Tips

För bättre prestanda kan du använda servern närmare din geoplats:

• 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

Hämta aviseringar med ett enkelt PowerShell-skript

Hur lång tid tar det att gå igenom det här exemplet?

Det tar bara 5 minuter i två steg:

• Programregistrering
• Använd exempel: kräver endast kopiering/inklistring av ett kort PowerShell-skript

Behöver jag behörighet att ansluta?

För fasen Programregistrering måste du ha en lämplig roll tilldelad i din Microsoft Entra klientorganisation. Mer information om roller finns i Behörighetsalternativ.

Steg 1 – Skapa en app i Microsoft Entra ID

1. Logga in på Azure-portalen.

2. Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.

   

3. I registreringsformuläret väljer du ett namn för ditt program och väljer sedan Registrera.

4. Ge ditt program åtkomst till Defender för Endpoint och tilldela behörigheten Läs alla aviseringar :

   • På programsidan väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder skriver>WindowsDefenderATP och väljer WindowsDefenderATP.

     Obs!

     WindowsDefenderATP visas inte i den ursprungliga listan. Du måste börja skriva dess namn i textrutan för att se det visas.

     

   • Välj Programbehörigheter>Alert.Read.All och välj sedan Lägg till behörigheter.

     

     Viktigt

     Du måste välja relevanta behörigheter. Läs alla aviseringar är bara ett exempel.

     Till exempel:

     • Om du vill köra avancerade frågor väljer du behörigheten Kör avancerade frågor.
     • Om du vill isolera en dator väljer du behörigheten "Isolera dator".
     • Information om vilken behörighet du behöver finns i avsnittet Behörigheter i api:et som du är intresserad av att anropa.

5. Välj Bevilja medgivande.

   Obs!

   Varje gång du lägger till behörighet måste du klicka på Bevilja medgivande för att den nya behörigheten ska börja gälla.

   

6. Lägg till en hemlighet i programmet.

   Välj Certifikat & hemligheter, lägg till en beskrivning i hemligheten och välj Lägg till.

   Viktigt

   När du har klickat på Lägg till kopierar du det genererade hemlighetsvärdet. Du kommer inte att kunna hämta när du har lämnat!

   

7. Skriv ned ditt program-ID och ditt klientorganisations-ID.

   På programsidan går du till Översikt och kopierar följande:

   

Klart! Du har registrerat ett program!

Steg 2 – Hämta en token med hjälp av appen och använd den här token för att komma åt API:et.

• Kopiera följande skript till PowerShell ISE eller till en textredigerare och spara det som Get-Token.ps1.

• När du kör det här skriptet genereras en token och sparas i arbetsmappen under namnet Latest-token.txt.

  # 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
  

• Sanity Check:

  • Kör skriptet.
  • I webbläsaren går du till: https://jwt.ms/.
  • Kopiera token (innehållet i Latest-token.txt-filen).
  • Klistra in i den övre rutan.
  • Leta efter avsnittet "roller". Leta upp rollen Alert.Read.All .

  

Nu hämtar vi aviseringarna!

• Följande skript använder Get-Token.ps1 för att komma åt API:et och hämtar aviseringar under de senaste 48 timmarna.

• Spara det här skriptet i samma mapp som du sparade föregående skript Get-Token.ps1.

• Skriptet skapar två filer (json och csv) med data i samma mapp som skripten.

  # 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
  

Du är klar! Du har:

• Skapat och registrerat och program
• Beviljad behörighet för programmet att läsa aviseringar
• Api:et har anslutits
• Använde ett PowerShell-skript för att returnera aviseringar som skapats under de senaste 48 timmarna

Relaterade artiklar

• Microsoft Defender för Endpoint API:er
• Åtkomst Microsoft Defender för Endpoint med programkontext
• Åtkomst Microsoft Defender för Endpoint med användarkontext

Tips

Vill du veta mer? Engage med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender för Endpoint Tech Community.