Del via

Hello World til REST-API'en til Microsoft Defender XDR

  • Artikel

Gælder for:

  • Microsoft Defender XDR

Vigtigt!

Nogle oplysninger er relateret til et forhåndsudgivet produkt, som kan blive ændret væsentligt, før det udgives kommercielt. Microsoft giver ingen garantier, hverken udtrykkelige eller underforståede, med hensyn til de oplysninger, der gives her.

Hent hændelser ved hjælp af et simpelt PowerShell-script

Det bør tage 5 til 10 minutter at fuldføre dette projekt. Dette tidsestimat omfatter registrering af programmet og anvendelse af koden fra PowerShell-eksempelscriptet.

Registrer en app i Microsoft Entra ID

  1. Log på Azure som bruger med rollen Global administrator.

  2. Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.

    Sektionen Ny registrering på Microsoft Defender-portalen

  3. Vælg et navn til dit program i registreringsformularen, og vælg derefter Registrer. Det er valgfrit at vælge en omdirigerings-URI. Du behøver ikke en for at fuldføre dette eksempel.

  4. På din programside skal du vælge API-tilladelser>TilføjtilladelseS-API'er>, som min organisation bruger>, skriv Microsoft Threat Protection, og vælg Microsoft Threat Protection. Din app kan nu få adgang til Microsoft Defender XDR.

    Tip

    Microsoft Threat Protection er et tidligere navn på Microsoft Defender XDR og vises ikke på den oprindelige liste. Du skal begynde at skrive navnet i tekstfeltet for at se det blive vist. Afsnittet om brug af API'er på Microsoft Defender-portalen

    • Vælg Programtilladelser>Incident.Read.All , og vælg Tilføj tilladelser.

      Ruden med tilladelser for et program på Microsoft Defender portalen

  5. Vælg Giv administratorsamtykke. Hver gang du tilføjer en tilladelse, skal du vælge Giv administratorsamtykke , for at den kan træde i kraft.

    Afsnittet Tildel administratorsamtykke på portalen Microsoft Defender

  6. Føj en hemmelighed til programmet. Vælg Certifikater & hemmeligheder, føj en beskrivelse til hemmeligheden, og vælg derefter Tilføj.

    Tip

    Når du har valgt Tilføj, skal du vælge kopiér den genererede værdi for hemmelighed. Du kan ikke hente værdien for hemmeligheden, når du er gået.

    Afsnittet Tilføj hemmelighed på Microsoft Defender-portalen

  7. Registrer dit program-id og dit lejer-id et sikkert sted. De vises under Oversigt på din programside.

    Afsnittet Oversigt på Microsoft Defender-portalen

Hent et token ved hjælp af appen, og brug tokenet til at få adgang til API'en

Du kan få flere oplysninger om Microsoft Entra-tokens i selvstudiet om Microsoft Entra.

Vigtigt!

Selvom eksemplet i denne demoapp opfordrer dig til at indsætte værdien af din hemmelighed til testformål, bør du aldrig hardcode hemmeligheder i et program, der kører i produktion. En tredjepart kan bruge din hemmelighed til at få adgang til ressourcer. Du kan hjælpe med at beskytte din apps hemmeligheder ved hjælp af Azure Key Vault. Hvis du vil have et praktisk eksempel på, hvordan du kan beskytte din app, skal du se Administrer hemmeligheder i dine serverapps med Azure Key Vault.

  1. Kopiér scriptet nedenfor, og indsæt det i din foretrukne teksteditor. Gem som Get-Token.ps1. Du kan også køre koden, som den er i PowerShell ISE, men du skal gemme den, da vi skal køre den igen, når vi bruger scriptet til hentning af hændelser i næste afsnit.

    Dette script genererer et token og gemmer det i arbejdsmappen under navnet 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

Valider tokenet

  1. Kopiér og indsæt det token, du modtog, i JWT for at afkode det.

  2. JWT står for JSON Web Token. Det afkodede token indeholder et antal JSON-formaterede elementer eller krav. Sørg for, at rollekravet i det afkodede token indeholder de ønskede tilladelser.

    På følgende billede kan du se et afkodet token, der er hentet fra en app, med Incidents.Read.Alltilladelserne , Incidents.ReadWrite.Allog AdvancedHunting.Read.All :

    Afsnittet Afkodet token på Microsoft Defender-portalen

Få en liste over seneste hændelser

Scriptet nedenfor bruger Get-Token.ps1 til at få adgang til API'en. Derefter hentes en liste over hændelser, der senest blev opdateret inden for de seneste 48 timer, og listen gemmes som en JSON-fil.

Vigtigt!

Gem dette script i den samme mappe, som du gemte 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 er færdig! Du har udført:

  • Oprettede og registrerede et program.
  • Tildelt tilladelse til, at programmet kan læse beskeder.
  • Der er oprettet forbindelse til API'en.
  • Brugte et PowerShell-script til at returnere hændelser, der er opdateret inden for de seneste 48 timer.

Tip

Vil du vide mere? Kontakt Microsoft Security-community'et i vores Tech Community: Microsoft Defender XDR Tech Community.