Microsoft Defender för Endpoint API – Hello World

Obs!

Om du är en amerikansk myndighetskund använder du de URI:er som anges i Microsoft Defender för Endpoint för amerikanska myndighetskunder.

Tips

För bättre prestanda, i stället för att använda api.security.microsoft.com, använder du en server som är närmare 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
• aea.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

Tips

Vissa Microsoft Defender för Endpoint API:er kräver fortfarande åtkomsttoken som utfärdats för den äldre resursen https://api.securitycenter.microsoft.com. Om token-målgruppen inte matchar den resurs som förväntas av API:et misslyckas begäranden med 403 Forbidden, även om API-slutpunkten använder https://api.security.microsoft.com. Använd https://api.securitycenter.microsoft.com som resurs eller omfång när du hämtar token.

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.

# This code gets the application context token and saves it to a file named "Latest-token.txt" in the current directory.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application (client) ID here
$appSecret = '' ### Paste your Application secret (App key) here to test, and then store it in a safe place!

$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

Verifiera token

1. Kör skriptet för att generera Latest-token.txt filen.
2. Öppna i en webbläsare https://jwt.ms/och kopiera sedan token (innehållet i Latest-token.txt) i rutan Ange token nedan .
3. På fliken Avkodad token letar du upp avsnittet roller och kontrollerar att det innehåller Behörigheterna Alert.Read.All enligt följande bild:

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 created previously.
# Learn more about other query options and filters: https://learn.microsoft.com/defender-endpoint/api/get-alerts.
$url = "https://api.security.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 web request 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.
• Behörighet för programmet att läsa aviseringar har beviljats.
• 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.