Hallo wereld voor Microsoft Defender XDR REST API
Van toepassing op:
- Microsoft Defender XDR
Belangrijk
Sommige informatie is gerelateerd aan voorlopige productversies die mogelijk aanzienlijk gewijzigd worden voordat ze commercieel gepubliceerd worden. Microsoft geeft geen garantie, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt beschreven.
Het duurt 5 tot 10 minuten om dit project te voltooien. Deze tijdsraming omvat het registreren van de toepassing en het toepassen van de code uit het PowerShell-voorbeeldscript.
Meld u aan bij Azure.
Navigeer naar Microsoft Entra ID>App-registraties>Nieuwe registratie.
Kies in het registratieformulier een naam voor uw toepassing en selecteer vervolgens Registreren. Het selecteren van een omleidings-URI is optioneel. U hebt er geen nodig om dit voorbeeld te voltooien.
Selecteer op uw toepassingspagina API-machtigingenToevoegenmachtigings-API's >> diemijn organisatie gebruikt>, typ Microsoft Threat Protection en selecteer Microsoft Threat Protection. Uw app heeft nu toegang tot Microsoft Defender XDR.
Selecteer Beheerderstoestemming verlenen. Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om deze van kracht te laten worden.
Voeg een geheim toe aan de toepassing. Selecteer Certificaten & geheimen, voeg een beschrijving toe aan het geheim en selecteer vervolgens Toevoegen.
Tip
Nadat u Toevoegen hebt geselecteerd, selecteert u de gegenereerde geheime waarde kopiëren. U kunt de geheime waarde niet meer ophalen nadat u bent weg gelaten.
Noteer uw toepassings-id en uw tenant-id ergens veilig. Ze worden weergegeven onder Overzicht op de pagina van uw toepassing.
Zie de zelfstudie Microsoft Entra voor meer informatie over Microsoft Entra tokens.
Belangrijk
Hoewel het voorbeeld in deze demo-app u aanmoedigt om uw geheime waarde te plakken voor testdoeleinden, moet u geheimen nooit hardcoderen in een toepassing die in productie wordt uitgevoerd. Een derde partij kan uw geheim gebruiken om toegang te krijgen tot resources. U kunt de geheimen van uw app beveiligen met behulp van Azure Key Vault. Zie Geheimen in uw server-apps beheren met Azure Key Vault voor een praktisch voorbeeld van hoe u uw app kunt beveiligen.
Kopieer het onderstaande script en plak het in uw favoriete teksteditor. Opslaan als Get-Token.ps1. U kunt de code ook as-is uitvoeren in PowerShell ISE, maar u moet deze opslaan, omdat we deze opnieuw moeten uitvoeren wanneer we het script voor het ophalen van incidenten in de volgende sectie gebruiken.
Met dit script wordt een token gegenereerd en opgeslagen in de werkmap onder de naam 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
Kopieer en plak het token dat u hebt ontvangen in JWT om het te decoderen.
JWT staat voor JSON-webtoken. Het gedecodeerde token bevat een aantal items of claims in JSON-indeling. Zorg ervoor dat de rollenclaim binnen het gedecodeerde token de gewenste machtigingen bevat.
In de volgende afbeelding ziet u een gedecodeerd token dat is verkregen uit een app, met
Incidents.Read.All
machtigingen ,Incidents.ReadWrite.All
enAdvancedHunting.Read.All
:
In het onderstaande script wordt Get-Token.ps1 gebruikt om toegang te krijgen tot de API. Vervolgens wordt een lijst met incidenten opgehaald die de afgelopen 48 uur voor het laatst zijn bijgewerkt en wordt de lijst opgeslagen als een JSON-bestand.
Belangrijk
Sla dit script op in dezelfde map die u hebt opgeslagenGet-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
Jullie zijn klaar. U hebt het volgende gedaan:
- Een toepassing gemaakt en geregistreerd.
- Toestemming verleend voor die toepassing om waarschuwingen te lezen.
- Verbonden met de API.
- Een PowerShell-script gebruikt om incidenten te retourneren die in de afgelopen 48 uur zijn bijgewerkt.
- Overzicht van Microsoft Defender XDR API's
- Toegang tot de Microsoft Defender XDR API's
- Een app maken voor toegang tot Microsoft Defender XDR zonder een gebruiker
- Een app maken voor toegang tot Microsoft Defender XDR API's namens een gebruiker
- Een app maken met partnertoegang met meerdere tenants tot Microsoft Defender XDR API's
- Geheimen in uw server-apps beheren met Azure Key Vault
- OAuth 2.0-autorisatie voor gebruikersaanmelding en API-toegang
Tip
Wil je meer weten? Neem contact op met de Microsoft Beveiliging-community in onze Tech Community: Microsoft Defender XDR Tech Community.