Create um aplicativo para acessar Microsoft Defender para Ponto de Extremidade sem um usuário

Artigo
05/03/2024

Aplica-se a:

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 sem um usuário. Se você precisar de acesso programático ao Defender para Ponto de Extremidade em nome de um usuário, consulte Obter acesso com o contexto do usuário. Se você não tiver certeza de qual acesso precisa, consulte 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 ajudarão você a automatizar fluxos de trabalho e inovar com base nos recursos do 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.
Obtenha um token de acesso usando este aplicativo.
Use o token para acessar a API do Defender para Ponto de Extremidade.

Este artigo explica como criar um aplicativo Microsoft Entra, obter um token de acesso para Microsoft Defender para Ponto de Extremidade e validar o token.

Criar um aplicativo

Faça logon no Azure com um usuário que tenha a função de Administrador Global .
Navegue até Microsoft Entra ID>Registros de aplicativo>Novo registro.
No formulário de registro, escolha um nome para seu aplicativo e selecione Registrar.
Para permitir que seu aplicativo acesse o Defender para Ponto de Extremidade e atribua a ele a permissão "Ler todos os alertas", em sua página de aplicativo, selecione Permissões> de API Adicionar APIsde permissão>que minha organização usa>, digite WindowsDefenderATP e selecione WindowsDefenderATP.

Observação

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

Selecione Permissões> de aplicativoAlert.Read.All e selecione Adicionar permissões.

Você precisa 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 um dispositivo, selecione a permissão "Isolar máquina".
- Para determinar qual permissão você precisa, examine a seção Permissões na API que você está interessado em chamar.
Selecione Conceder consentimento.

Observação

Sempre que você adicionar uma permissão, você deve selecionar Conceder consentimento para que a nova permissão entre em vigor.
Para adicionar um segredo ao aplicativo, selecione Certificados & segredos, adicione uma descrição ao segredo e selecione Adicionar.

Observação

Depois de selecionar Adicionar, selecione copiar o valor secreto gerado. Você não poderá recuperar esse valor depois de sair.
Anote sua ID do aplicativo e sua ID do locatário. Na página do aplicativo, acesse Visão geral e copie o seguinte.
Somente para parceiros Microsoft Defender para Ponto de Extremidade. Defina seu aplicativo como multilocatário (disponível em todos os locatários após o consentimento). Isso é necessário para aplicativos de terceiros (por exemplo, se você criar um aplicativo destinado a ser executado no locatário de vários clientes). Isso não será necessário se você criar um serviço que deseja executar somente em seu locatário (por exemplo, se você criar um aplicativo para seu próprio uso que interaja apenas com seus próprios dados). Para definir seu aplicativo como multilocatário:
- Vá para Autenticação e adicione https://portal.azure.com como o URI de redirecionamento.
- Na parte inferior da página, em Tipos de conta com suporte, selecione as Contas em qualquer consentimento do aplicativo de diretório organizacional para seu aplicativo multilocatário.
Você precisa que seu aplicativo seja aprovado em cada locatário em que pretende usá-lo. Isso ocorre porque seu aplicativo interage com o Defender para Ponto de Extremidade em nome do cliente.

Você (ou seu cliente, se estiver escrevendo um aplicativo de terceiros) precisa selecionar o link de consentimento e aprovar seu aplicativo. O consentimento deve ser feito com um usuário que tenha privilégios administrativos no Active Directory.

O link de consentimento é formado da seguinte maneira:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Onde 0000000-0000-0000-0000-000000000000 é substituído pela ID do aplicativo.

Concluído! Você registrou com êxito um aplicativo! Confira exemplos abaixo para aquisição e validação de token.

Obter um token de acesso

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

Usar o Windows PowerShell!

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    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
$token

Use C#:

O código a seguir foi testado com NuGet Microsoft.Identity.Client 3.19.8.

Importante

O pacote NuGet Microsoft.IdentityModel.Clients.ActiveDirectory e Azure AD Authentication Library (ADAL) foram preteridos. Nenhum novo recurso foi adicionado desde 30 de junho de 2020. Recomendamos que você atualize, consulte o guia de migração para obter mais detalhes.

Create um novo aplicativo de console.
Instale o NuGet Microsoft.Identity.Client.
Adicione o seguinte:
```
using Microsoft.Identity.Client;
```

Copie e cole o seguinte código em seu aplicativo (não se esqueça de atualizar as três variáveis: tenantId, appId, appSecret):

string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
const string authority = "https://login.microsoftonline.com";
const string audience = "https://api.securitycenter.microsoft.com";

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List<string> scopes = new List<string>() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Usar Python

Consulte Obter token usando Python.

Usar Curl

Observação

O procedimento a seguir pressupõe que o Curl para Windows já está instalado em seu computador.

Abra um prompt de comando e defina CLIENT_ID para sua ID do aplicativo do Azure.
Defina CLIENT_SECRET para o segredo do aplicativo do Azure.
Defina TENANT_ID para a ID do locatário do Azure do cliente que deseja usar seu aplicativo para acessar o Defender para Ponto de Extremidade.

Execute o seguinte comando:

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Você receberá uma resposta no seguinte formulário:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validar o token

Verifique se você tem o token correto:

Copie e cole o token que você recebeu na etapa anterior no JWT para decodificá-lo.
Valide se você obtém uma declaração de 'funções' com as permissões desejadas.

Na imagem a seguir, você pode ver um token decodificado adquirido de um aplicativo com permissões para todas as funções do Microsoft Defender para Ponto de Extremidade:

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

Escolha a API que você deseja usar. Para obter mais informações, consulte APIs com suporte do Defender para Ponto de Extremidade.
Defina o cabeçalho de autorização na solicitação http enviada para "Portador {token}" (Portador é o esquema de autorização).
O tempo de validade do token é de uma hora. Você pode enviar mais de uma solicitação com o mesmo token.

Veja a seguir um 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