Usar APIs Microsoft Defender para Ponto de Extremidade

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

Recursos avançados de caça não estão incluídos no Defender para Empresas.

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

Observação

Se você for um cliente do governo dos EUA, use as URIs listadas em Microsoft Defender para Ponto de Extremidade para clientes do governo dos EUA.

Dica

Para obter um melhor desempenho, você pode usar 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 um aplicativo para obter acesso programático ao Defender para Ponto de Extremidade em nome de um usuário.

Se você precisar de acesso programático Microsoft Defender para Ponto de Extremidade sem um usuário, consulte Access Microsoft Defender para Ponto de Extremidade com o contexto do aplicativo.

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

Microsoft Defender para Ponto de Extremidade expõe grande parte de seus dados e ações por meio de um conjunto de APIs programáticas. Essas APIs permitirão automatizar fluxos de trabalho e inovar com base em recursos Microsoft Defender para Ponto de Extremidade. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, consulte Fluxo de código de autorização do OAuth 2.0.

Em geral, você precisará tomar as seguintes etapas para usar as APIs:

• Create um aplicativo de Microsoft Entra
• Obter um token de acesso usando este aplicativo
• Usar o token para acessar a API do Defender para Ponto de Extremidade

Esta página explica como criar um aplicativo Microsoft Entra, obter um token de acesso para Microsoft Defender para Ponto de Extremidade e validar o token.

Observação

Ao acessar Microsoft Defender para Ponto de Extremidade API em nome de um usuário, você precisará da permissão correta do aplicativo e da permissão do usuário. Se você não estiver familiarizado com as permissões do usuário no Microsoft Defender para Ponto de Extremidade, consulte Gerenciar acesso ao portal usando o controle de acesso baseado em função.

Dica

Se você tiver a permissão para executar uma ação no portal, terá a permissão para executar a ação na API.

Criar um aplicativo

1. Faça logon no Azure com uma conta de usuário que tenha a função de Administrador Global .

2. Navegue até Microsoft Entra ID>Registros de aplicativo>Novo registro.

   

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

   • Nome: insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo.

   • 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). Essa opção não estará disponível se você não estiver registrando o aplicativo em um diretório. Essa opção é mapeada para Microsoft Entra único locatário. Essa é a opção padrão, a menos que você esteja registrando o aplicativo fora de um diretório. Nos casos em que o aplicativo é registrado fora de um diretório, o padrão é Microsoft Entra contas microsoft multilocatários e pessoais.
     Contas em qualquer diretório organizacional	Selecione essa opção se você deseja direcionar para todos os clientes corporativos e educacionais. Essa opção é mapeada para um multilocatário somente Microsoft Entra. Se você registrou o aplicativo como Microsoft Entra único locatário, poderá atualizá-lo para ser Microsoft Entra multilocatário e voltar para locatário único por meio da folha 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. Essa opção mapeia para Microsoft Entra contas microsoft multilocatários e pessoais. Se você registrou o aplicativo como Microsoft Entra contas da Microsoft multilocatários e pessoais, não poderá alterá-lo na interface do usuário. 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 aplicativos cliente públicos, forneça o URI usado por Microsoft Entra ID para retornar respostas de token. 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. Permitir que seu aplicativo acesse Microsoft Defender para Ponto de Extremidade e atribua a ele permissão "Ler alertas":

   • Em sua página de aplicativo, selecione Permissões >de APIAdicionar APIs depermissão>minha organização usa> o tipo WindowsDefenderATP e selecione no WindowsDefenderATP.

     Observação

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

     

   • Escolha Permissões> delegadasAlerta.Leitura> selecione Adicionar permissões.

     

   Importante

   Selecione as permissões relevantes. Ler alertas é 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 qual permissão você precisa, exiba a seção Permissões na API que você está interessado em chamar.

   • Selecione Conceder consentimento.

     Observação

     Toda vez que você adicionar permissão, você deve selecionar no Consentimento de Concessão para que a nova permissão entre em vigor.

     

5. Anote sua ID do aplicativo e sua ID do locatário.

   Na página do aplicativo, acesse Visão geral e copie as seguintes informações:

   

Obter um token de acesso

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

Usando C#

• Copie/cole a classe abaixo em seu aplicativo.

• Use o método AcquireUserTokenAsync com sua ID do aplicativo, ID do locatário, nome de usuário e senha 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 você tem um token correto:

• Copie/cole no JWT o token que você recebeu na etapa anterior para decodificá-lo.

• Valide você obter uma declaração 'scp' com as permissões de aplicativo desejadas.

• Na captura de tela abaixo, você pode ver um token decodificado adquirido do aplicativo no tutorial:

  

Use o token para acessar Microsoft Defender para Ponto de Extremidade API

• Escolha a API que você deseja usar – APIs de Microsoft Defender para Ponto de Extremidade com suporte.

• Defina o cabeçalho Autorização na solicitação HTTP enviada para "Portador {token}" (Portador é o esquema de autorização).

• O tempo de validade do token é de 1 hora (você pode enviar mais de uma solicitação com o mesmo token).

• Exemplo de envio de uma solicitação para obter uma lista de alertas usando 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 Microsoft Defender para Ponto de Extremidade
• Acessar Microsoft Defender para Ponto de Extremidade com o contexto do aplicativo

Dica

Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender para Ponto de Extremidade Tech Community.