Del via

Hello World for REST-API for Microsoft Defender XDR

  • Artikkel

Gjelder for:

  • Microsoft Defender XDR

Viktig

Noe informasjon er knyttet til forhåndsutgitt produkt som kan endres vesentlig før det utgis kommersielt. Microsoft gir ingen garantier, uttrykkelige eller underforståtte, med hensyn til informasjonen som er oppgitt her.

Få hendelser ved hjelp av et enkelt PowerShell-skript

Det bør ta 5 til 10 minutter å fullføre dette prosjektet. Dette tidsestimatet omfatter registrering av programmet og bruk av koden fra PowerShell-eksempelskriptet.

Registrere en app i Microsoft Entra ID

  1. Logg deg på Azure som en bruker med global administrator rollen.

  2. Gå til Microsoft Entra ID>App-registreringer>Ny registrering.

    Inndelingen Ny registrering i Microsoft Defender-portalen

  3. Velg et navn for programmet i registreringsskjemaet, og velg deretter Registrer. Valg av omadresserings-URI er valgfritt. Du trenger ikke en for å fullføre dette eksemplet.

  4. Velg API-tillatelserLegg til tillatelses-API-er>>organisasjonen bruker> på programsiden, skriv inn Microsoft Trusselbeskyttelse og velg Microsoft Trusselbeskyttelse. Appen kan nå få tilgang til Microsoft Defender XDR.

    Tips

    Microsoft Threat Protection er et tidligere navn for Microsoft Defender XDR, og vises ikke i den opprinnelige listen. Du må begynne å skrive navnet i tekstboksen for å se det. Delen av API-er i Microsoft Defender-portalen

    • Velg Programtillatelser>Incident.Read.All , og velg Legg til tillatelser.

      Tillatelsesruten for et program i Microsoft Defender-portalen

  5. Velg Gi administratorsamtykke. Hver gang du legger til en tillatelse, må du velge Gi administratorsamtykke for at den skal tre i kraft.

    Delen Gi administratorsamtykke i Microsoft Defender-portalen

  6. Legg til en hemmelighet i programmet. Velg Sertifikater & hemmeligheter, legg til en beskrivelse i hemmeligheten, og velg deretter Legg til.

    Tips

    Når du har valgt Legg til, velger du kopier den genererte hemmelige verdien. Du kan ikke hente den hemmelige verdien etter at du har forlatt den.

    Delen Legg til hemmelig i Microsoft Defender-portalen

  7. Registrer program-ID-en og leier-ID-en din et trygt sted. De er oppført under Oversikt på programsiden.

    Oversikt-delen i Microsoft Defender-portalen

Få et token ved hjelp av appen, og bruk tokenet til å få tilgang til API-en

Hvis du vil ha mer informasjon om Microsoft Entra tokener, kan du se Microsoft Entra opplæringen.

Viktig

Selv om eksemplet i denne demoappen oppfordrer deg til å lime inn den hemmelige verdien for testformål, bør du aldri hardkode hemmeligheter i et program som kjører i produksjon. En tredjepart kan bruke hemmeligheten din til å få tilgang til ressurser. Du kan bidra til å holde appens hemmeligheter sikre ved hjelp av Azure Key Vault. Hvis du vil ha et praktisk eksempel på hvordan du kan beskytte appen, kan du se Administrere hemmeligheter i serverappene med Azure Key Vault.

  1. Kopier skriptet nedenfor, og lim det inn i redigeringsprogrammet for favoritttekst. Lagre som Get-Token.ps1. Du kan også kjøre koden som den er i PowerShell ISE, men du bør lagre den, fordi vi må kjøre den på nytt når vi bruker det hendelseshentingsskriptet i neste del.

    Dette skriptet genererer et token og lagrer det i arbeidsmappen 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

Validere tokenet

  1. Kopier og lim inn tokenet du mottok i JWT for å dekode det.

  2. JWT står for JSON Web Token. Det dekodede tokenet inneholder en rekke JSON-formaterte elementer eller krav. Kontroller at rollekravet i det dekodede tokenet inneholder de ønskede tillatelsene.

    I illustrasjonen nedenfor kan du se et dekodet token hentet fra en app, med Incidents.Read.All, Incidents.ReadWrite.Allog AdvancedHunting.Read.All tillatelser:

    Inndelingen Dekoded token i Microsoft Defender-portalen

Få en liste over nylige hendelser

Skriptet nedenfor bruker Get-Token.ps1 til å få tilgang til API-en. Den henter deretter en liste over hendelser som sist ble oppdatert i løpet av de siste 48 timene, og lagrer listen som en JSON-fil.

Viktig

Lagre skriptet i samme mappe som du lagret 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

Alt er klart! Du har fullført:

  • Opprettet og registrerte et program.
  • Gitt tillatelse for dette programmet til å lese varsler.
  • Koblet til API-en.
  • Brukte et PowerShell-skript til å returnere hendelser oppdatert i løpet av de siste 48 timene.

Tips

Vil du lære mer? Kommuniser med Microsoft Sikkerhet-fellesskapet i det tekniske fellesskapet vårt: Microsoft Defender XDR Tech Community.