Hello World per Microsoft Defender XDR API REST

Si applica a:

• Microsoft Defender XDR

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

1. Accedere ad Azure.

2. Passare a Microsoft Entra ID>Registrazioni app>Nuova registrazione.

   

3. 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.

4. 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.

   Consiglio

   Microsoft Threat Protection è un nome precedente per Microsoft Defender XDR e non verrà visualizzato nell'elenco originale. È necessario iniziare a scrivere il nome nella casella di testo per visualizzarlo.

   • Scegliere Autorizzazioni applicazione>Incident.Read.All e selezionare Aggiungi autorizzazioni.

     

5. Selezionare Concedi consenso amministratore. Ogni volta che si aggiunge un'autorizzazione, è necessario selezionare Concedi consenso amministratore per renderla effettiva.

   

6. 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.

   

7. 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.

1. 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

1. Copiare e incollare il token ricevuto in JWT per decodificarlo.

2. 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.Allautorizzazioni , Incidents.ReadWrite.Alle AdvancedHunting.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.

# 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
• 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