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.
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.
Inicie sessão no Azure.
Navegue para Microsoft Entra ID>Registros de aplicativo>Novo registo.
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.
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.
Selecione Conceder consentimento do administrador. Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento do administrador para que esta entre em vigor.
Adicione um segredo à aplicação. Selecione Certificados & segredos, adicione uma descrição ao segredo e, em seguida, selecione Adicionar.
Dica
Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter o valor do segredo depois de sair.
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.
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.
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
Copie e cole o token que recebeu no JWT para o descodificar.
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.All
eAdvancedHunting.Read.All
permissões:
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.
- descrição geral das APIs Microsoft Defender XDR
- Aceder às APIs Microsoft Defender XDR
- Criar uma aplicação para aceder a Microsoft Defender XDR sem um utilizador
- Criar uma aplicação para aceder Microsoft Defender XDR APIs em nome de um utilizador
- Criar uma aplicação com acesso de parceiro multi-inquilino às APIs Microsoft Defender XDR
- Gerir segredos nas suas aplicações de servidor com o Azure Key Vault
- Autorização do OAuth 2.0 para início de sessão do utilizador e acesso à API
Dica
Você deseja aprender mais? Participe da comunidade de Segurança da Microsoft em nossa Tech Community: Tech Community do Microsoft Defender XDR.