Partilhar via

Hello World para Microsoft Defender XDR API REST

  • Artigo

Aplica-se a:

  • Microsoft Defender XDR

Importante

Algumas informações estão relacionadas com o produto pré-lançado que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações aqui fornecidas.

Obter incidentes com um script simples do PowerShell

A conclusão deste projeto deve demorar entre 5 a 10 minutos. Esta estimativa de tempo inclui registar a aplicação e aplicar o código a partir do script de exemplo do PowerShell.

Registar uma aplicação no Microsoft Entra ID

  1. Inicie sessão no Azure como um utilizador com a função Administrador global.

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

    A secção Novo registo no portal do Microsoft Defender

  3. No formulário de registo, selecione um nome para a sua aplicação e, em seguida, selecione Registar. Selecionar um URI de redirecionamento é opcional. Não precisará de um para concluir este exemplo.

  4. Na página da sua aplicação, selecione Permissões> da API Adicionar APIs depermissão> quea minha organização utiliza>, escreva Proteção Contra Ameaças da Microsoft e selecione Proteção Contra Ameaças da Microsoft. A sua aplicação pode agora aceder a Microsoft Defender XDR.

    Sugestão

    O Microsoft Threat Protection é um nome antigo para Microsoft Defender XDR e não será apresentado na lista original. Tem de começar a escrever o respetivo nome na caixa de texto para vê-lo aparecer. A secção de utilização de APIs no portal do Microsoft Defender

    • Selecione Permissões> da aplicaçãoIncident.Read.All e selecione Adicionar permissões.

      Painel de permissões de uma aplicação no portal do Microsoft Defender

  5. Selecione Conceder consentimento do administrador. Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento do administrador para que esta entre em vigor.

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

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

    Sugestão

    Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter o valor do segredo depois de sair.

    A secção Adicionar segredo no portal do Microsoft Defender

  7. Registe o ID da aplicação e o ID do inquilino num local seguro. Estão listados em Descrição geral na página da sua aplicação.

    A secção Descrição geral no portal do Microsoft Defender

Obter um token com a aplicação e utilizar o token para aceder à API

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

Importante

Embora o exemplo nesta aplicação de demonstração o incentive a colar o seu valor secreto para fins de teste, nunca deve codificar segredos para uma aplicação em execução na produção. Um terceiro pode utilizar o segredo para aceder aos recursos. Pode ajudar a manter os segredos da sua aplicação seguros com o Azure Key Vault. Para obter um exemplo prático de como pode proteger a sua aplicação, veja Gerir segredos nas suas aplicações de servidor com o Azure Key Vault.

  1. Copie o script abaixo e cole-o no seu editor de texto favorito. Guarde como Get-Token.ps1. Também pode executar o código tal como está no ISE do PowerShell, mas deve guardá-lo, porque teremos de executá-lo novamente quando utilizarmos o script de obtenção de incidentes na próxima secção.

    Este script irá gerar um token e guardá-lo 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 recebeu no JWT para o descodificar.

  2. JWT significa JSON Web Token. O token descodificado irá conter vários itens ou afirmações formatados em JSON. Confirme que a afirmação de funções no token descodificado contém as permissões pretendidas.

    Na imagem seguinte, pode ver um token descodificado adquirido a partir de uma aplicação, com Incidents.Read.All, Incidents.ReadWrite.Alle AdvancedHunting.Read.All permissões:

    A secção Token Descodificado no portal do Microsoft Defender

Obter uma lista de incidentes recentes

O script abaixo utilizará Get-Token.ps1 para aceder à API. Em seguida, obtém uma lista de incidentes que foram atualizados pela última vez nas últimas 48 horas e guarda a lista como um ficheiro JSON.

Importante

Guarde este script na mesma pasta que guardou 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

Está tudo pronto! Conseguiu:

  • Criou e registou uma aplicação.
  • Foi concedida permissão para essa aplicação ler alertas.
  • Ligado à API.
  • Utilizou um script do PowerShell para devolver incidentes atualizados nas últimas 48 horas.

Sugestão

Quer saber mais? Interaja com a comunidade do Microsoft Security na nossa Tech Community: Microsoft Defender XDR Tech Community.