Utilizar as APIs do Microsoft Defender para Endpoint

Aplica-se a:

• Plano 1 do Microsoft Defender para Ponto de Extremidade
• Plano 2 do Microsoft Defender para Ponto de Extremidade
• Microsoft Defender para Empresas

Importante

As capacidades avançadas de investigação não estão incluídas no Defender para Empresas.

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

Se for um cliente do Us Government, utilize os URIs listados no Microsoft Defender para Endpoint para clientes do Us Government.

Dica

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

• 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

Esta página descreve como criar uma aplicação para obter acesso programático ao Defender para Endpoint em nome de um utilizador.

Se precisar de acesso programático ao Microsoft Defender para Endpoint sem um utilizador, veja Aceder ao Microsoft Defender para Endpoint com o contexto da aplicação.

Se não tiver a certeza de qual o acesso de que precisa, leia a página Introdução.

O Microsoft Defender para Endpoint expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Essas APIs permitem-lhe automatizar fluxos de trabalho e inovar com base nas capacidades do Microsoft Defender para Endpoint. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, veja OAuth 2.0 Authorization Code Flow (Fluxo de Código de Autorização do OAuth 2.0).

Em geral, tem de seguir os seguintes passos para utilizar as APIs:

• Criar uma aplicação Microsoft Entra
• Obter um token de acesso com esta aplicação
• Utilizar o token para aceder à API do Defender para Endpoint

Esta página explica como criar uma aplicação Microsoft Entra, obter um token de acesso para o Microsoft Defender para Endpoint e validar o token.

Observação

Ao aceder à API do Microsoft Defender para Endpoint em nome de um utilizador, precisará da permissão de aplicação e da permissão de utilizador corretas. Se não estiver familiarizado com as permissões de utilizador no Microsoft Defender para Endpoint, veja Gerir o acesso ao portal através do controlo de acesso baseado em funções.

Dica

Se tiver permissão para efetuar uma ação no portal, tem a permissão para executar a ação na API.

Criar um aplicativo

1. Entre no portal do Azure.

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

   

3. Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:

   • Nome – introduza um nome de aplicação relevante que seja apresentado aos utilizadores da aplicação.

   • Tipos de conta com suporte: selecione as contas às quais você gostaria que seu aplicativo desse suporte.

     
     

     Tipos de conta com suporte	Descrição
     Contas apenas neste diretório organizacional	Selecione esta opção se você está criando um aplicativo de linha de negócios (LOB). Esta opção não está disponível se não estiver a registar a aplicação num diretório. Esta opção mapeia para o inquilino único do Microsoft Entra-only. Esta opção é a opção predefinida, a menos que esteja a registar a aplicação fora de um diretório. Nos casos em que a aplicação está registada fora de um diretório, a predefinição é contas Microsoft Entra multi-inquilino e pessoais.
     Contas em qualquer diretório organizacional	Selecione essa opção se você deseja direcionar para todos os clientes corporativos e educacionais. Esta opção mapeia para um multi-inquilino do Microsoft Entra-only. Se registou a aplicação como inquilino único do Microsoft Entra-only, pode atualizá-la para ser multi-inquilino do Microsoft Entra e regressar ao inquilino único através do painel Autenticação .
     Contas em qualquer diretório organizacional e contas pessoais da Microsoft	Selecione essa opção para direcionar ao conjunto mais amplo de clientes. Esta opção mapeia para contas Microsoft multi-inquilino e pessoais do Microsoft Entra. Se registou a aplicação como contas Microsoft multi-inquilino e pessoais do Microsoft Entra, não pode alterá-la na IU. Em vez disso, use o editor de manifesto do aplicativo para alterar os tipos de conta com suporte.

   • URI de redirecionamento (opcional): selecione o tipo de aplicativo que você está desenvolvendo, Web ou Cliente público (dispositivos móvel e desktop)e insira o URI de redirecionamento (ou a URL de resposta) para o aplicativo.

     • Para aplicativos Web, informe a URL base do aplicativo. Por exemplo, http://localhost:31544 pode ser uma URL para um aplicativo Web em execução no seu computador local. Os usuários usariam essa URL para entrar em um aplicativo cliente Web.

     • Para aplicações cliente públicas, forneça o URI utilizado pelo ID do Microsoft Entra para devolver respostas de tokens. Insira um valor específico para o aplicativo, por exemplo, myapp://auth.

     Para ver exemplos específicos de aplicativos Web ou aplicativos nativos, confira os inícios rápidos.

     Ao terminar, selecione Registrar.

4. Permita que a aplicação aceda ao Microsoft Defender para Endpoint e atribua-lhe a permissão "Alertas de leitura":

   • 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 no WindowsDefenderATP.

     Observação

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

     

   • Selecione Alerta de permissões>delegadas.Ler> selecione Adicionar permissões.

     

   Importante

   Selecione as permissões relevantes. Os alertas de leitura são apenas um exemplo.

   Por exemplo:

   • Para executar consultas avançadas, selecione Executar permissão de consultas avançadas .

   • Para isolar um dispositivo, selecione Isolar permissão do computador .

   • Para determinar de que permissão precisa, veja a secção Permissões na API que está interessado em chamar.

   • Selecione Conceder consentimento.

     Observação

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

     

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

   Na página da aplicação, aceda a Descrição geral e copie as seguintes informações:

   

Obter um token de acesso

Para obter mais informações sobre os tokens do Microsoft Entra, consulte o tutorial do Microsoft Entra.

Utilizar C#

• Copie/Cole a classe abaixo na sua aplicação.

• Utilize o método AcquireUserTokenAsync com o ID da aplicação, o ID do inquilino, o nome de utilizador e a palavra-passe para adquirir um token.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

Validar o token

Verifique se tem um token correto:

• Copie/cole no JWT o token que obteve no passo anterior para o descodificar.

• Confirme que obtém uma afirmação "scp" com as permissões de aplicação pretendidas.

• Na captura de ecrã abaixo, pode ver um token descodificado adquirido na aplicação no tutorial:

  

Utilizar o token para aceder à API do Microsoft Defender para Endpoint

• Escolha a API que pretende utilizar – APIs suportadas do Microsoft Defender para Endpoint.

• Defina o cabeçalho Autorização no pedido HTTP que envia para "Portador {token}" (Portador é o esquema de Autorização).

• A Hora de expiração do token é de 1 hora (pode enviar mais do que um pedido com o mesmo token).

• Exemplo de envio de um pedido para obter uma lista de alertas com C#:

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

Confira também

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

Dica

Você deseja aprender mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.