Hello World til REST-API'en til Microsoft Defender XDR
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.
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.
Log på Azure.
Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.
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.
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.
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.
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.
Registrer dit program-id og dit lejer-id et sikkert sted. De vises under Oversigt på din programside.
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.
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
Kopiér og indsæt det token, du modtog, i JWT for at afkode det.
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.All
tilladelserne ,Incidents.ReadWrite.All
ogAdvancedHunting.Read.All
:
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.
- Oversigt over API'er Microsoft Defender XDR
- Få adgang til de Microsoft Defender XDR API'er
- Opret en app for at få adgang til Microsoft Defender XDR uden en bruger
- Opret en app for at få adgang til Microsoft Defender XDR API'er på vegne af en bruger
- Opret en app med partneradgang med flere lejere til Microsoft Defender XDR API'er
- Administrer hemmeligheder i dine serverapps med Azure Key Vault
- OAuth 2.0 Autorisation til brugerlogon og API-adgang
Tip
Vil du vide mere? Kontakt Microsoft Security-community'et i vores Tech Community: Microsoft Defender XDR Tech Community.