Utilizar Microsoft Defender para Endpoint APIs

Aplica-se a:

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

Importante

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

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

Nota

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

Sugestão

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 Microsoft Defender para Endpoint sem um utilizador, veja Access Microsoft Defender para Endpoint com o contexto da aplicação.

Se não tiver a certeza de que acesso precisa, leia a página Introduçã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 permitir-lhe-ão automatizar fluxos de trabalho e inovar com base nas capacidades 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, terá de seguir os seguintes passos para utilizar as APIs:

• Create 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 Microsoft Defender para Endpoint e validar o token.

Nota

Ao aceder à API 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 com o controlo de acesso baseado em funções.

Sugestão

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

Create uma aplicação

1. Inicie sessão no Azure com uma conta de utilizador que tenha a função de Administrador Global .

2. Navegue para Microsoft Entra ID>Registos de aplicações>Novo registo.

   

3. Quando for apresentada a página Registar uma aplicação , introduza as informações de registo da sua aplicação:

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

   • Tipos de conta suportados – selecione as contas que pretende que a sua aplicação suporte.

     
     

     Tipos de conta suportados	Descrição
     Contas apenas neste diretório organizacional	Selecione esta opção se estiver a criar uma aplicação de linha de negócio (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 Microsoft Entra inquilino único. Esta é 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 é Microsoft Entra contas Microsoft multi-inquilino e pessoais.
     Contas em qualquer diretório organizacional	Selecione esta opção se quiser direcionar todos os clientes empresariais e educativos. Esta opção mapeia para um multi-inquilino Microsoft Entra. Se registou a aplicação como Microsoft Entra inquilino único, pode atualizá-la para ser Microsoft Entra multi-inquilino e voltar ao inquilino único através do painel Autenticação.
     Contas em qualquer diretório organizacional e contas Microsoft pessoais	Selecione esta opção para direcionar o conjunto mais vasto de clientes. Esta opção mapeia para Microsoft Entra contas Microsoft multi-inquilino e pessoais. Se registou a aplicação como Microsoft Entra contas Microsoft multi-inquilino e pessoais, não pode alterá-la na IU. Em vez disso, tem de utilizar o editor de manifestos da aplicação para alterar os tipos de conta suportados.

   • URI de Redirecionamento (opcional) – selecione o tipo de aplicação que está a criar, Cliente Web ou Público (móvel & ambiente de trabalho) e, em seguida, introduza o URI de redirecionamento (ou URL de resposta) para a sua aplicação.

     • Para aplicações Web, forneça o URL base da sua aplicação. Por exemplo, http://localhost:31544 pode ser o URL de uma aplicação Web em execução no seu computador local. Os utilizadores utilizariam este URL para iniciar sessão numa aplicação cliente Web.

     • Para aplicações cliente públicas, forneça o URI utilizado pelo Microsoft Entra ID para devolver respostas de tokens. Introduza um valor específico para a sua aplicação, como myapp://auth.

     Para ver exemplos específicos de aplicações Web ou aplicações nativas, veja os nossos inícios rápidos.

     Quando terminar, selecione Registar.

4. Permita que a aplicação aceda a 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.

     Nota

     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.

     Nota

     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 tokens de Microsoft Entra, veja Microsoft Entra tutorial.

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 Microsoft Defender para Endpoint

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

• 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
  

Consulte também

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

Sugestão

Quer saber mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.