Partilhar via

API de Microsoft Defender para Endpoint - Hello World

  • Artigo

Aplica-se a:

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

Obter Alertas com um script simples do PowerShell

Quanto tempo demora a percorrer este exemplo?

Demora apenas 5 minutos efetuada em dois passos:

  • Registo de aplicações
  • 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. Inicie sessão no portal do Azure.

  2. Navegue para Microsoft Entra ID>Registos de aplicações>Novo registo.

    A opção Registos de aplicações no painel Gerir no centro de administração 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.

      Nota

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

    Nota

    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 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 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 Microsoft Entra

Feito! 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

Sugestão

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