API Microsoft Defender per endpoint - Hello World

Si applica a:

• Microsoft Defender per endpoint Piano 1
• Microsoft Defender per endpoint Piano 2

Se si desidera provare Microsoft Defender per endpoint, iscriversi a una versione di valutazione gratuita.

Nota

Se si è un cliente del governo degli Stati Uniti, usare gli URI elencati in Microsoft Defender per endpoint per i clienti del governo degli Stati Uniti.

Consiglio

Per ottenere prestazioni migliori, è possibile usare il server più vicino alla posizione geografica:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

Ottenere avvisi usando un semplice script di PowerShell

Quanto tempo è necessario per esaminare questo esempio?

Sono necessari solo 5 minuti in due passaggi:

• Registrazione dell'applicazione
• Esempi d'uso: richiede solo la copia/incolla di un breve script di PowerShell

È necessaria un'autorizzazione per la connessione?

Per la fase di registrazione dell'applicazione, è necessario disporre di un ruolo appropriato assegnato nel tenant Microsoft Entra. Per altre informazioni sui ruoli, vedere Opzioni di autorizzazione.

Passaggio 1: Creare un'app in Microsoft Entra ID

1. Accedere al portale di 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.

4. Consentire all'applicazione di accedere a Defender per endpoint e assegnarle l'autorizzazione "Leggi tutti gli avvisi" :

   • Nella pagina dell'applicazione selezionare Autorizzazioni> APIAggiungi API di autorizzazione>che l'organizzazione usa> di tipo WindowsDefenderATP e selezionare WindowsDefenderATP.

     Nota

     WindowsDefenderATP non viene visualizzato nell'elenco originale. È necessario iniziare a scrivere il nome nella casella di testo per visualizzarlo.

     

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

     

     Importante

     È necessario selezionare le autorizzazioni pertinenti. Read All Alerts è solo un esempio.

     Ad esempio:

     • Per eseguire query avanzate, selezionare l'autorizzazione "Esegui query avanzate".
     • Per isolare un computer, selezionare l'autorizzazione "Isola computer".
     • Per determinare l'autorizzazione necessaria, vedere la sezione Autorizzazioni nell'API che si vuole chiamare.

5. Selezionare Concedi consenso.

   Nota

   Ogni volta che si aggiunge l'autorizzazione, è necessario fare clic su Concedi consenso per rendere effettiva la nuova autorizzazione.

   

6. Aggiungere un segreto all'applicazione.

   Selezionare Certificati & segreti, aggiungere una descrizione al segreto e selezionare Aggiungi.

   Importante

   Dopo aver fatto clic su Aggiungi, copiare il valore del segreto generato. Non sarà possibile recuperare dopo aver lasciato l'attività.

   

7. Annotare l'ID applicazione e l'ID tenant.

   Nella pagina dell'applicazione passare a Panoramica e copiare quanto segue:

   

Fatto! È stata registrata correttamente un'applicazione.

Passaggio 2: Ottenere un token usando l'app e usare questo token per accedere all'API.

• Copiare lo script seguente in PowerShell ISE o in un editor di testo e salvarlo come Get-Token.ps1.

• L'esecuzione di questo script genera un token e lo salva nella cartella di lavoro con il nome Latest-token.txt.

  # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
  # Paste below your Tenant ID, App ID and App Secret (App key).
  
  $tenantId = '' ### Paste your tenant ID here
  $appId = '' ### Paste your Application ID here
  $appSecret = '' ### Paste your Application secret here
  
  $resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
  $oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
  $authBody = [Ordered] @{
       resource = "$resourceAppIdUri"
       client_id = "$appId"
       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
  

• Controllo di integrità:

  • Eseguire lo script.
  • Nel browser passare a: https://jwt.ms/.
  • Copiare il token (il contenuto del file Latest-token.txt).
  • Incollare nella casella superiore.
  • Cercare la sezione "ruoli". Trovare il ruolo Alert.Read.All .

  

Si ottengono gli avvisi.

• Lo script seguente usa Get-Token.ps1 per accedere all'API e ottiene avvisi per le ultime 48 ore.

• Salvare questo script nella stessa cartella in cui è stato salvato lo script Get-Token.ps1precedente.

• Lo script crea due file (json e csv) con i dati nella stessa cartella degli script.

  # Returns Alerts created in the past 48 hours.
  
  $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
  
  # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
  $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
  
  # The URL contains the type of query and the time filter we create above
  # Read more about [other query options and filters](get-alerts.md).
  $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
  
  # Set the WebRequest headers
  $headers = @{
      'Content-Type' = 'application/json'
      Accept = 'application/json'
      Authorization = "Bearer $token"
  }
  
  # Send the webrequest and get the results.
  $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
  
  # Extract the alerts from the results.
  $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
  
  # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
  $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
  
  # Save the result as json and as csv
  $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
  $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
  
  Out-File -FilePath $outputJsonPath -InputObject $alerts
  ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
  

Avete finito! L'operazione è stata completata:

• Creato e registrato e applicazione
• Autorizzazione concessa all'applicazione per la lettura degli avvisi
• Connessione dell'API
• È stato usato uno script di PowerShell per restituire gli avvisi creati nelle ultime 48 ore

Articoli correlati

• API Microsoft Defender per endpoint
• Accedere Microsoft Defender per endpoint con il contesto dell'applicazione
• Accedere Microsoft Defender per endpoint con il contesto utente

Consiglio

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