Hello World per Microsoft Defender XDR API REST
Si applica a:
- Microsoft Defender XDR
Importante
Alcune informazioni fanno riferimento alle caratteristiche del prodotto prima del rilascio, e possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.
Il completamento del progetto deve richiedere da 5 a 10 minuti. Questa stima temporale include la registrazione dell'applicazione e l'applicazione del codice dallo script di esempio di PowerShell.
Accedere ad Azure.
Passare a Microsoft Entra ID>Registrazioni app>Nuova registrazione.
Nel modulo di registrazione scegliere un nome per l'applicazione e quindi selezionare Registra. La selezione di un URI di reindirizzamento è facoltativa. Non sarà necessario per completare questo esempio.
Nella pagina dell'applicazione selezionare Autorizzazioni> APIAggiungi API di autorizzazione>usate dall'organizzazione>, digitare Microsoft Threat Protection e selezionare Microsoft Threat Protection. L'app può ora accedere a Microsoft Defender XDR.
Selezionare Concedi consenso amministratore. Ogni volta che si aggiunge un'autorizzazione, è necessario selezionare Concedi consenso amministratore per renderla effettiva.
Aggiungere un segreto all'applicazione. Selezionare Certificati & segreti, aggiungere una descrizione al segreto e quindi selezionare Aggiungi.
Suggerimento
Dopo aver selezionato Aggiungi, selezionare copiare il valore del segreto generato. Non sarà possibile recuperare il valore del segreto dopo l'uscita.
Registrare l'ID applicazione e l'ID tenant in un punto sicuro. Sono elencati in Panoramica nella pagina dell'applicazione.
Per altre informazioni sui token Microsoft Entra, vedere l'esercitazione Microsoft Entra.
Importante
Anche se l'esempio in questa app demo incoraggia a incollare il valore del segreto a scopo di test, non è mai consigliabile codificare i segreti in un'applicazione in esecuzione nell'ambiente di produzione. Una terza parte potrebbe usare il segreto per accedere alle risorse. È possibile proteggere i segreti dell'app usando Azure Key Vault. Per un esempio pratico di come proteggere l'app, vedere Gestire i segreti nelle app server con Azure Key Vault.
Copiare lo script seguente e incollarlo nell'editor di testo preferito. Salvare come Get-Token.ps1. È anche possibile eseguire il codice così come è in PowerShell ISE, ma è necessario salvarlo, perché sarà necessario eseguirlo di nuovo quando si usa lo script di recupero degli eventi imprevisti nella sezione successiva.
Questo script genererà un token e lo salverà nella cartella di lavoro sotto il nome 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
Copiare e incollare il token ricevuto in JWT per decodificarlo.
JWT è l'acronimo di token Web JSON. Il token decodificato conterrà una serie di attestazioni o elementi in formato JSON. Assicurarsi che l'attestazione dei ruoli all'interno del token decodificato contenga le autorizzazioni desiderate.
Nell'immagine seguente è possibile visualizzare un token decodificato acquisito da un'app, con
Incidents.Read.All
autorizzazioni ,Incidents.ReadWrite.All
eAdvancedHunting.Read.All
:
Lo script seguente userà Get-Token.ps1 per accedere all'API. Recupera quindi un elenco di eventi imprevisti che sono stati aggiornati per l'ultima volta nelle ultime 48 ore e salva l'elenco come file JSON.
Importante
Salvare questo script nella stessa cartella salvata 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
Avete finito! L'operazione è stata completata:
- Creazione e registrazione di un'applicazione.
- Autorizzazione concessa all'applicazione per la lettura degli avvisi.
- Connesso all'API.
- È stato usato uno script di PowerShell per restituire gli eventi imprevisti aggiornati nelle ultime 48 ore.
- Panoramica delle API Microsoft Defender XDR
- Accedere alle API Microsoft Defender XDR
- Creare un'app per accedere a Microsoft Defender XDR senza un utente
- Creare un'app per accedere alle API Microsoft Defender XDR per conto di un utente
- Creare un'app con accesso partner multi-tenant alle API Microsoft Defender XDR
- Gestire i segreti nelle app server con Azure Key Vault
- Autorizzazione OAuth 2.0 per l'accesso utente e l'accesso alle API
Suggerimento
Per saperne di più, Visitare la community di Microsoft Security nella Tech Community: Tech Community di Microsoft Defender XDR.