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.
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.
Logga in på Azure.
Gå till Microsoft Entra ID>Appregistreringar>Ny registrering.
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.
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.
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.
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.
Registrera ditt program-ID och ditt klientorganisations-ID på en säker plats. De visas under Översikt på programsidan.
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.
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
Kopiera och klistra in token som du fick i JWT för att avkoda den.
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.All
behörigheterna ,Incidents.ReadWrite.All
ochAdvancedHunting.Read.All
:
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.
- översikt över Microsoft Defender XDR API:er
- Få åtkomst till Microsoft Defender XDR-API:er
- Skapa en app för att få åtkomst till Microsoft Defender XDR utan en användare
- Skapa en app för att få åtkomst till Microsoft Defender XDR-API:er för en användares räkning
- Skapa en app med partneråtkomst för flera innehavare till Microsoft Defender XDR API:er
- Hantera hemligheter i dina serverappar med Azure Key Vault
- OAuth 2.0-auktorisering för användarinloggning och API-åtkomst
Tips
Vill du veta mer? Interagera med Microsofts säkerhetscommunity i vår Tech Community: Microsoft Defender XDR Tech Community.