Compartilhar via

API de Microsoft Defender para Ponto de Extremidade - 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 for um cliente do Governo norte-americano, utilize os URIs listados no Microsoft Defender para Ponto de Extremidade para clientes do Us Government.

Dica

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

Obter Alertas com um script simples do PowerShell

Quanto tempo demora a percorrer este exemplo?

Demora apenas 5 minutos efetuada em dois passos:

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

Preciso de uma permissão para ligar?

Para a fase de Registo de aplicações, tem de ter uma função adequada atribuída no inquilino do Microsoft Entra. Para obter mais detalhes sobre as funções, veja Opções de permissão.

Passo 1 – Criar uma Aplicação no Microsoft Entra ID

  1. Entre no portal do Azure.

  2. Navegue para Microsoft Entra ID>Registros de aplicativo>Novo registo.

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

  3. No formulário de registo, selecione um nome para a sua aplicação e, em seguida, selecione Registar.

  4. Permita que a aplicação aceda ao Defender para Endpoint e atribua-lhe a permissão "Ler todos os alertas" :

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

      Observação

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

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

    • Selecione Alerta de permissões> daaplicação.Read.All e, em seguida, selecione Adicionar permissões.

      O tipo de permissão e os painéis de definições na página Pedir permissões da API

      Importante

      Tem de selecionar as permissões relevantes. Ler Todos os Alertas é apenas um exemplo.

      Por exemplo:

  5. Selecione Conceder consentimento.

    Observação

    Sempre que adicionar permissão, tem de clicar em Conceder consentimento para que a nova permissão entre em vigor.

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

  6. Adicione um segredo à aplicação.

    Selecione Certificados & segredos, adicione a descrição ao segredo e selecione Adicionar.

    Importante

    Depois de clicar em Adicionar, copie o valor do segredo gerado. Não poderá obter depois de sair!

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

  7. Anote o ID da aplicação e o ID do inquilino.

    Na página da aplicação, aceda a Descrição geral e copie o seguinte:

    O painel de detalhes da aplicação no item de menu Descrição geral no centro de administração do Microsoft Entra

Concluído! Registou uma aplicação com êxito!

Passo 2 – obter um token com a Aplicação e utilizar este token para aceder à API.

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

  • A execução deste script gera um token e guarda-o na pasta de trabalho com 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 browser, aceda a: https://jwt.ms/.
    • Copie o token (o conteúdo do ficheiro Latest-token.txt).
    • Cole na caixa superior.
    • Procure a secção "funções". Localize a função Alert.Read.All .

    O painel Token Descodificado para jwt.ms

Vamos obter os Alertas!

  • O seguinte script utiliza Get-Token.ps1 para aceder à API e recebe alertas nas últimas 48 horas.

  • Guarde este script na mesma pasta que guardou o script Get-Token.ps1anterior.

  • O script cria dois ficheiros (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

Está tudo pronto! Conseguiu:

  • Criado e registado e aplicação
  • Foi concedida permissão para essa aplicação ler alertas
  • Ligar a API
  • Utilizou um script do PowerShell para devolver alertas criados nas últimas 48 horas

Dica

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