API do Microsoft Defender para Endpoint - Hello World

Aplica-se a:

• API do Microsoft Defender para Endpoint 1
• Microsoft Defender para Endpoint Plano 2

Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Obter Alertas com um script simples do PowerShell

Quanto tempo demora a percorrer este exemplo?

Demora apenas 5 minutos efetuada em dois passos:

• Registo de aplicações
• Utilizar exemplos: só requer a cópia/colagem de um script curto do PowerShell

Preciso de uma permissão para ligar?

Para a fase de Registo de aplicações, tem de ter a função de Administrador global atribuída no seu inquilino do Microsoft Entra.

Passo 1 – Criar uma Aplicação no Microsoft Entra ID

1. Inicie sessão no portal do Azure.

2. Navegue paraRegistos> da Aplicação Microsoft Entra ID>Novo registo.

   

3. No formulário de registo, selecione um nome para a sua aplicação e, em seguida, selecione Registar.

4. Permita que a aplicação aceda ao Defender para Endpoint e atribua-lhe a permissão "Ler todos os alertas" :

   • Na página da sua aplicação, selecione Permissões> da API Adicionar APIs depermissão> quea minha organização utiliza>, escreva WindowsDefenderATP e selecione WindowsDefenderATP.

     Nota

     WindowsDefenderATP não aparece na lista original. Tem de começar a escrever o respetivo nome na caixa de texto para vê-lo aparecer.

     

   • Selecione Alerta de permissões> daaplicação.Read.All e, em seguida, selecione Adicionar permissões.

     

     Importante

     Tem de selecionar as permissões relevantes. Ler Todos os Alertas é apenas um exemplo.

     Por exemplo:

     • Para executar consultas avançadas, selecione a permissão "Executar consultas avançadas".
     • Para isolar uma máquina, selecione a permissão "Isolar máquina".
     • Para determinar de que permissão precisa, veja a secção Permissões na API que está interessado em chamar.

5. Selecione Conceder consentimento.

   Nota

   Sempre que adicionar permissão, tem de clicar em Conceder consentimento para que a nova permissão entre em vigor.

   

6. Adicione um segredo à aplicação.

   Selecione Certificados & segredos, adicione a descrição ao segredo e selecione Adicionar.

   Importante

   Depois de clicar em Adicionar, copie o valor do segredo gerado. Não poderá obter depois de sair!

   

7. Anote o ID da aplicação e o ID do inquilino.

   Na página da aplicação, aceda a Descrição geral e copie o seguinte:

   

Feito! Registou uma aplicação com êxito!

Passo 2 – obter um token com a Aplicação e utilizar este token para aceder à API.

• Copie o seguinte script para o ISE do PowerShell ou para um editor de texto e guarde-o como Get-Token.ps1.

• A execução deste script gera um token e guarda-o na pasta de trabalho com o 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
  

• Verificação de Sanidade:

  • Execute o script.
  • No browser, aceda a: https://jwt.ms/.
  • Copie o token (o conteúdo do ficheiro Latest-token.txt).
  • Cole na caixa superior.
  • Procure a secção "funções". Localize a função Alert.Read.All .

  

Vamos obter os Alertas!

• O seguinte script utiliza Get-Token.ps1 para aceder à API e recebe alertas nas últimas 48 horas.

• Guarde este script na mesma pasta que guardou o script Get-Token.ps1anterior.

• O script cria dois ficheiros (json e csv) com os dados na mesma pasta que os scripts.

  # 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
  

Está tudo pronto! Conseguiu:

• Criado e registado e aplicação
• Foi concedida permissão para essa aplicação ler alertas
• Ligar a API
• Utilizou um script do PowerShell para devolver alertas criados nas últimas 48 horas

Artigos relacionados

• APIs do Microsoft Defender para Endpoint
• Aceder ao Microsoft Defender para Endpoint com o contexto da aplicação
• Aceder ao Microsoft Defender para Endpoint com contexto de utilizador