Utilizar as APIs do Microsoft Defender para Endpoint

Artigo
06/25/2024

Aplica-se a:

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
ina.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.

Nota

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.

Sugestão

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

Criar uma aplicação

Inicie sessão no portal do Azure.
Navegue paraRegistos> da Aplicação Microsoft Entra ID>Novo registo.

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 seja 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 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 esta opção se quiser direcionar todos os clientes empresariais e educativos. 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 Microsoft pessoais	Selecione esta opção para direcionar o conjunto mais vasto 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, 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 ID do Microsoft Entra 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.

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.
  
  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.
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

Consulte também

Sugestão

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

Partilhar via

Utilizar as APIs do Microsoft Defender para Endpoint

Criar uma aplicação

Obter um token de acesso

Utilizar C#

Validar o token

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

Consulte também

Comentários

Recursos adicionais