Hello World för Microsoft Defender XDR REST API

Gäller för:

• Microsoft Defender XDR

Viktigt

En del information gäller förinstallerad produkt som kan ha ändrats mycket innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som anges här.

Hämta incidenter med ett enkelt PowerShell-skript

Det bör ta 5 till 10 minuter att slutföra projektet. Den här tidsuppskattningen omfattar registrering av programmet och tillämpning av koden från PowerShell-exempelskriptet.

Registrera en app i Microsoft Entra ID

1. Logga in på Azure som en användare med rollen Global administratör.

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. Det är valfritt att välja en omdirigerings-URI. Du behöver ingen för att slutföra det här exemplet.

4. På programsidan väljer du API-behörigheter>Lägg till behörighets-API>:er som min organisation använder>, skriver Microsoft Threat Protection och väljer Microsoft Threat Protection. Din app kan nu komma åt Microsoft Defender XDR.

   Tips

   Microsoft Threat Protection är ett tidigare namn för Microsoft Defender XDR och 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>Incident.Read.All och välj Lägg till behörigheter.

     

5. Välj Bevilja administratörsmedgivande. Varje gång du lägger till en behörighet måste du välja Bevilja administratörsmedgivande för att den 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 sedan Lägg till.

   Tips

   När du har valt Lägg till väljer du kopiera det genererade hemlighetsvärdet. Du kommer inte att kunna hämta det hemliga värdet när du har lämnat.

   

7. Registrera ditt program-ID och ditt klientorganisations-ID på en säker plats. De visas under Översikt på programsidan.

   

Hämta en token med hjälp av appen och använd token för att komma åt API:et

Mer information om Microsoft Entra-token finns i självstudien om Microsoft Entra.

Viktigt

Även om exemplet i den här demoappen uppmuntrar dig att klistra in ditt hemliga värde i testsyfte bör du aldrig hårdkoda hemligheter i ett program som körs i produktion. En tredje part kan använda din hemlighet för att komma åt resurser. Du kan skydda appens hemligheter med hjälp av Azure Key Vault. Ett praktiskt exempel på hur du kan skydda din app finns i Hantera hemligheter i dina serverappar med Azure Key Vault.

1. Kopiera skriptet nedan och klistra in det i din favorittextredigerare. Spara som Get-Token.ps1. Du kan också köra koden som den är i PowerShell ISE, men du bör spara den eftersom vi måste köra den igen när vi använder skriptet för incidenthämtning i nästa avsnitt.

   Det här skriptet genererar en token och sparar den i arbetsmappen under namnet Latest-token.txt.

   # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
   # Paste in your tenant ID, client ID and app secret (App key).
   
   $tenantId = '' # Paste your directory (tenant) ID here
   $clientId = '' # Paste your application (client) ID here
   $appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!
   
   $resourceAppIdUri = 'https://api.security.microsoft.com'
   $oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
   $authBody = [Ordered] @{
     resource = $resourceAppIdUri
     client_id = $clientId
     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. Kopiera och klistra in token som du fick i JWT för att avkoda den.

2. JWT står för JSON Web Token. Den avkodade token innehåller ett antal JSON-formaterade objekt eller anspråk. Kontrollera att rollanspråket i den avkodade token innehåller önskade behörigheter.

   I följande bild kan du se en avkodad token som hämtats från en app med Incidents.Read.Allbehörigheterna , Incidents.ReadWrite.Alloch AdvancedHunting.Read.All :

   

Hämta en lista över de senaste incidenterna

Skriptet nedan använder Get-Token.ps1 för att komma åt API:et. Den hämtar sedan en lista över incidenter som senast uppdaterades under de senaste 48 timmarna och sparar listan som en JSON-fil.

Viktigt

Spara skriptet i samma mapp som du sparade Get-Token.ps1.

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

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

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

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

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

Du är klar! Du har:

• Skapat och registrerat ett program.
• Behörighet för programmet att läsa aviseringar har beviljats.
• Ansluten till API:et.
• Använde ett PowerShell-skript för att returnera incidenter som uppdaterats under de senaste 48 timmarna.

Relaterade artiklar

• översikt över Microsoft Defender XDR API:er
• Få åtkomst till Microsoft Defender XDR-API:er
• Skapa en app för att få åtkomst till Microsoft Defender XDR utan en användare
• Skapa en app för att få åtkomst till Microsoft Defender XDR-API:er för en användares räkning
• Skapa en app med partneråtkomst för flera innehavare till Microsoft Defender XDR-API:er
• Hantera hemligheter i dina serverappar med Azure Key Vault
• OAuth 2.0-auktorisering för användarinloggning och API-åtkomst

Tips

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