Hello World för Microsoft 365 Defender REST API

Viktigt

Den förbättrade Microsoft 365 Defender-portalen är nu tillgänglig. Med den här nya upplevelsen kommer Defender för Endpoint, Defender för Office 365, 365 Microsoft 365 Defender och annat till Microsoft Defender for Cloud Apps. Läs om de senaste.

Gäller för:

  • Microsoft 365 Defender

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.

Få incidenter med ett enkelt PowerShell-skript

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

Registrera en app i Azure Active Directory

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

  2. Gå till Azure Active Directory > Appregistreringar > Ny registrering.

    Bild av Microsoft Azure navigering till registrering av program.

  3. Välj ett namn på din ansökan i registreringsformuläret och välj 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. Nu kan du komma åt Microsoft 365 Defender.

    Tips

    Microsoft Threat Protection är ett tidigare namn Microsoft 365 Defender namn och visas inte i den ursprungliga listan. Du måste börja skriva namnet i textrutan för att det ska visas. Bild av val av API-behörighet.

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

    Bild av API-åtkomst och API-val.

  5. Välj Bevilja administratörsmedgivande. Varje gång du lägger till en behörighet måste du välja Ge administratörsmedgivande för att den ska gälla.

    Bild av bevilja behörigheter.

  6. Gör programmet hemligt. Välj Certifikat & , lägg till en beskrivning av hemligheten och välj sedan Lägg till.

    Tips

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

    Bild av skapa programnyckel.

  7. Spela in ditt program-ID och ditt klient-ID på ett säkert ställe. De visas under Översikt din programsida.

    Bild av skapat program-ID.

Hämta en token med appen och använd token för att få åtkomst till API:t

Mer information om hur Azure Active Directory token finns i självstudiekursen för Azure AD.

Viktigt

Även om exemplet i den här demoappen uppmuntrar dig att klistra in i ditt hemliga värde för teständamål ska du aldrig hårdkoda hemligheter i ett program som körs i produktion. En tredje part kan använda din hemligt för att komma åt resurser. Du kan skydda dina apphemligheter 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 även 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 hämtning av incidenter i nästa avsnitt.

    Det här skriptet genererar en token och sparar den i arbetsmappen under namnet ochLatest-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 den token du fått 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 rollerna som anges i den avkodade token innehåller de önskade behörigheterna.

    På följande bild kan du se en avkodad token som köpts från en app, med Incidents.Read.All Incidents.ReadWrite.All , och AdvancedHunting.Read.All behörigheter:

    Bild jwt.ms.

Få en lista över de senaste incidenterna

Skriptet nedan använder en Get-Token.ps1 för att få åtkomst till API:et. Sedan hämtas en lista över incidenter som senast uppdaterades inom 48 timmar och listan sparas 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

Nu är allt klart! Du har lyckats:

  • Skapat och registrerat ett program.
  • Har gett det programmet behörighet att läsa aviseringar.
  • Ansluten till API:t.
  • Använde ett PowerShell-skript för att returnera incidenter som uppdaterats de senaste 48 timmarna.