Olá, Mundo para Microsoft Defender XDR API REST

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.

   

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.

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

     

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.

   

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.

   

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.

   

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:

   

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.

Artigos relacionados

• visão geral das APIs Microsoft Defender XDR
• Acessar as APIs Microsoft Defender XDR
• Create um aplicativo para acessar Microsoft Defender XDR sem um usuário
• Create um aplicativo para acessar APIs Microsoft Defender XDR em nome de um usuário
• Create um aplicativo com acesso de parceiro multilocatário às APIs Microsoft Defender XDR
• Gerenciar segredos em seus aplicativos de servidor com o Azure Key Vault
• Autorização do OAuth 2.0 para entrada do usuário e acesso à API

Dica

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