Condividi tramite

Hello World per Microsoft Defender XDR API REST

  • Articolo

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

  1. Accedere ad Azure come utente con il ruolo amministratore globale.

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

    Sezione Nuova registrazione nel portale di Microsoft Defender

  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. Sezione dell'utilizzo delle API nel portale di Microsoft Defender

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

      Riquadro delle autorizzazioni di un'applicazione nel portale di Microsoft Defender

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

    Sezione Concedi consenso amministratore nel portale di Microsoft Defender

  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.

    Sezione aggiungi segreto nel portale di Microsoft Defender

  7. Registrare l'ID applicazione e l'ID tenant in un punto sicuro. Sono elencati in Panoramica nella pagina dell'applicazione.

    La sezione Panoramica nel portale di Microsoft Defender

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.

  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 :

    Sezione Token decodificato nel portale di Microsoft Defender

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.

Consiglio

Per saperne di più, Engage con la community Microsoft Security nella community tech: Microsoft Defender XDR Tech Community.