Share via

Microsoft Defender para Ponto de Extremidade API – Olá, Mundo

  • Artigo

Aplica-se a:

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

Obter alertas usando um script simples do PowerShell

Quanto tempo leva para passar por este exemplo?

Leva apenas 5 minutos em duas etapas:

  • Registro de aplicativo
  • Usar exemplos: só requer cópia/colagem de um script curto do PowerShell

Preciso de uma permissão para me conectar?

Para a fase de registro de aplicativo, você deve ter uma função Administrador global no locatário Microsoft Entra.

Etapa 1 – Create um aplicativo no Microsoft Entra ID

  1. Faça logon no Azure com seu usuário Administrador global.

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

    A opção Registros de aplicativo no painel Gerenciar no centro de administração do Microsoft Entra

  3. No formulário de registro, escolha um nome para seu aplicativo e clique em Registrar.

  4. 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, clique em Permissões >de APIAdicionar APIs depermissão>minha organização usa> o tipo WindowsDefenderATP e clique em WindowsDefenderATP.

      Observação

      O WindowsDefenderATP não aparece na lista original. Você precisa começar a escrever seu nome na caixa de texto para vê-lo aparecer.

      A opção permissões de API no painel Gerenciar no centro de administração do Microsoft Entra

    • Escolha Permissões> de aplicativoAlert.Read.All> Clique em Adicionar permissões.

      O tipo de permissão e os painéis de configurações na página Solicitar permissões de API

      Importante

      Você precisa selecionar as permissões relevantes. 'Ler Todos os Alertas' é apenas um exemplo!

      Por exemplo:

  5. Clique em Conceder consentimento.

    Observação

    Toda vez que você adicionar permissão, você deve clicar em Conceder consentimento para que a nova permissão entre em vigor.

    A opção de consentimento da permissão de concessão no centro de administração do Microsoft Entra

  6. Adicione um segredo ao aplicativo.

    Clique em Certificados & segredos, adicione descrição ao segredo e clique em Adicionar.

    Importante

    Depois de clicar em Adicionar, copie o valor secreto gerado. Você não será capaz de recuperar depois de sair!

    O item de menu Certificados & segredos no painel Gerenciar no centro de administração do Microsoft Entra

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

    Na página do aplicativo, acesse Visão geral e copie o seguinte:

    O painel detalhes do aplicativo no item de menu Visão geral no centro de administração do Microsoft Entra

Concluído! Você registrou com êxito um aplicativo!

Etapa 2 – Obtenha um token usando o Aplicativo e use esse token para acessar a API.

  • Copie o script abaixo para o ISE do PowerShell ou para um editor de texto e salve-o como Get-Token.ps1.

  • Executar esse script gerará um token e o salvará na pasta de trabalho sob o nome Latest-token.txt.

    # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

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

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
     resource = "$resourceAppIdUri"
     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
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

  • Verificação de sanidade:

    • Execute o script.
    • No navegador, acesse: https://jwt.ms/.
    • Copie o token (o conteúdo do arquivo Latest-token.txt).
    • Cole na caixa superior.
    • Procure a seção "funções". Localize a função Alert.Read.All .

    O painel Token Decodificado para jwt.ms

Vamos receber os alertas!

  • O script a seguir usará Get-Token.ps1 para acessar a API e receberá os alertas das últimas 48 horas.

  • Salve esse script na mesma pasta que você salvou o script anterior Get-Token.ps1.

  • O script cria dois arquivos (json e csv) com os dados na mesma pasta que os scripts.

    # Returns Alerts created in the past 48 hours.

$token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1

# Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# The URL contains the type of query and the time filter we create above
# Read more about [other query options and filters](get-alerts.md).
$url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"

# Set the WebRequest headers
$headers = @{
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $token"
}

# Send the webrequest and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the alerts from the results.
$alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json

# Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json and as csv
$outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
$outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"

Out-File -FilePath $outputJsonPath -InputObject $alerts
($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation

Vocês terminaram! Você acabou de obter êxito:

  • Criado e registrado e aplicativo
  • Permissão concedida para que o aplicativo leia alertas
  • Conectou a API
  • Usou um script do PowerShell para retornar alertas criados nas últimas 48 horas

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.