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.
Ottenere eventi imprevisti usando un semplice script di PowerShell
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.
Registrare un'app in Microsoft Entra ID
Accedere ad Azure come utente con il ruolo amministratore globale.
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.
Consiglio
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.
Ottenere un token usando l'app e usare il token per accedere all'API
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
Convalidare il 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
:
Ottenere un elenco degli eventi imprevisti recenti
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.
Articoli correlati
- Panoramica delle API Microsoft Defender XDR
- Accedere alle API Microsoft Defender XDR
- Create un'app per accedere a Microsoft Defender XDR senza un utente
- Create un'app per accedere alle API Microsoft Defender XDR per conto di un utente
- Create 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
Consiglio
Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender XDR Tech Community.