Läs på engelska

Dela via


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.

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

    Avsnittet Ny registrering i Microsoft Defender-portalen

  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. Avsnittet om API:er i Microsoft Defender-portalen

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

      Behörighetsfönstret för ett program i Microsoft Defender-portalen

  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.

    Avsnittet Bevilja administratörsmedgivande i Microsoft Defender-portalen

  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.

    Avsnittet Lägg till hemlighet i Microsoft Defender-portalen

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

    Avsnittet Översikt i Microsoft Defender-portalen

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 :

    Avsnittet Avkodad token i Microsoft Defender-portalen

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.

Tips

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