Compartilhar via

Olá, Mundo para Microsoft Defender XDR API REST

  • Artigo

Aplica-se a:

  • Microsoft Defender XDR

Importante

Algumas informações estão relacionadas a produtos pré-lançados que podem ser substancialmente modificados antes de seu lançamento comercial. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

Obter incidentes usando um script simples do PowerShell

Deve levar de 5 a 10 minutos para concluir este projeto. Essa estimativa de tempo inclui o registro do aplicativo e a aplicação do código do script de exemplo do PowerShell.

Registrar um aplicativo no Microsoft Entra ID

  1. Entre no Azure como usuário com a função Administrador global.

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

    A seção Novo registro no portal Microsoft Defender

  3. No formulário de registro, escolha um nome para seu aplicativo e selecione Registrar. Selecionar um URI de redirecionamento é opcional. Você não precisará de um para concluir este exemplo.

  4. Em sua página de aplicativo, selecione Permissões >de APIAdicionar APIs depermissão>que minha organização usa>, digite Proteção contra Ameaças da Microsoft e selecione Proteção contra Ameaças da Microsoft. Seu aplicativo agora pode acessar Microsoft Defender XDR.

    Dica

    A Proteção contra Ameaças da Microsoft é um nome antigo para Microsoft Defender XDR e não aparecerá na lista original. Você precisa começar a escrever seu nome na caixa de texto para vê-lo aparecer. A seção de uso de APIs no portal Microsoft Defender

    • Escolha Permissões> de aplicativoIncident.Read.All e selecione Adicionar permissões.

      Painel de permissões de um aplicativo no portal Microsoft Defender

  5. Selecione Conceder consentimento do administrador. Sempre que você adicionar uma permissão, você deve selecionar Conceder consentimento do administrador para que ela entre em vigor.

    A seção Conceder consentimento do administrador no portal do Microsoft Defender

  6. Adicione um segredo ao aplicativo. Selecione Certificados & segredos, adicione uma descrição ao segredo e selecione Adicionar.

    Dica

    Depois de selecionar Adicionar, selecione copiar o valor secreto gerado. Você não poderá recuperar o valor secreto depois de sair.

    A seção adicionar segredo no portal Microsoft Defender

  7. Registre sua ID do aplicativo e sua ID de locatário em algum lugar seguro. Eles estão listados em Visão geral em sua página de aplicativo.

    A seção Visão geral no portal Microsoft Defender

Obter um token usando o aplicativo e usar o token para acessar a API

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

Importante

Embora o exemplo neste aplicativo de demonstração incentive você a colar em seu valor secreto para fins de teste, você nunca deve codificar segredos em um aplicativo em execução em produção. Um terceiro pode usar seu segredo para acessar recursos. Você pode ajudar a manter os segredos do aplicativo seguros usando o Azure Key Vault. Para obter um exemplo prático de como você pode proteger seu aplicativo, consulte Gerenciar segredos em seus aplicativos de servidor com o Azure Key Vault.

  1. Copie o script abaixo e cole-o no editor de texto favorito. Salve como Get-Token.ps1. Você também pode executar o código como está no ISE do PowerShell, mas deve salvá-lo, pois precisaremos executá-lo novamente quando usarmos o script de busca de incidentes na próxima seção.

    Esse script gerará um token e o salvará na pasta de trabalho sob o nome ,Latest-token.txt.

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  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

Validar o token

  1. Copie e cole o token que você recebeu no JWT para decodificá-lo.

  2. JWT significa JSON Web Token. O token decodificado conterá uma série de itens ou declarações formatadas por JSON. Verifique se a declaração de funções dentro do token decodificado contém as permissões desejadas.

    Na imagem a seguir, você pode ver um token decodificado adquirido de um aplicativo, com Incidents.Read.All, Incidents.ReadWrite.Alle AdvancedHunting.Read.All permissões:

    A seção Token Decodificado no portal Microsoft Defender

Obter uma lista de incidentes recentes

O script a seguir usará Get-Token.ps1 para acessar a API. Em seguida, ele recupera uma lista de incidentes que foram atualizados pela última vez nas últimas 48 horas e salva a lista como um arquivo JSON.

Importante

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

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

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

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

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

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

Vocês terminaram! Você conseguiu:

  • Criou e registrou um aplicativo.
  • Permissão concedida para que o aplicativo leia alertas.
  • Conectado à API.
  • Usou um script do PowerShell para retornar incidentes atualizados 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 XDR Tech Community.