Microsoft Defender para Endpoint APIs com o PowerShell

Aplica-se a:

Importante

As capacidades avançadas de investigação não estão incluídas no Defender para Empresas. Consulte Comparar Microsoft Defender para Empresas com Microsoft Defender para Endpoint Planos 1 e 2.

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:

  • api-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.com

Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Cenário completo com várias APIs de Microsoft Defender para Endpoint.

Nesta secção, partilhamos exemplos do PowerShell com

  • Obter um token
  • Utilizar o token para obter os alertas mais recentes no Microsoft Defender para Endpoint
  • Para cada alerta, se o alerta tiver prioridade média ou alta e ainda estiver em curso, verifique quantas vezes o dispositivo se ligou a UM URL suspeito.

Pré-requisito: primeiro tem de criar uma aplicação.

Instruções de preparação

  • Abra uma janela do PowerShell.
  • Se a política não lhe permitir executar os comandos do PowerShell, pode executar o comando abaixo:
    Set-ExecutionPolicy -ExecutionPolicy Bypass
    

Para obter mais informações, veja a documentação do PowerShell

Obter token

Execute o seguinte:

  • $tenantId: ID do inquilino em nome do qual pretende executar a consulta (ou seja, a consulta será executada nos dados deste inquilino)

  • $appId: ID da sua aplicação do AAD (a aplicação tem de ter a permissão "Executar consultas avançadas" no Defender para Endpoint)

  • $appSecret: Segredo da sua aplicação Azure AD

  • $suspiciousUrl: O URL

$tenantId = '00000000-0000-0000-0000-000000000000' # Paste your own tenant ID here
$appId = '11111111-1111-1111-1111-111111111111' # Paste your own app ID here
$appSecret = '22222222-2222-2222-2222-222222222222' # Paste your own app secret here
$suspiciousUrl = 'www.suspiciousUrl.com' # Paste your own URL here

$resourceAppIdUri = 'https://securitycenter.onmicrosoft.com/windowsatpservice'
$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
$aadToken = $authResponse.access_token


#Get latest alert
$alertUrl = "https://api.securitycenter.microsoft.com/api/alerts?`$top=10"
$headers = @{ 
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $aadToken" 
}
$alertResponse = Invoke-WebRequest -Method Get -Uri $alertUrl -Headers $headers -ErrorAction Stop
$alerts =  ($alertResponse | ConvertFrom-Json).value

$machinesToInvestigate = New-Object System.Collections.ArrayList

Foreach($alert in $alerts)
{
    #echo $alert.id $alert.machineId    $alert.severity $alert.status

    $isSevereAlert = $alert.severity -in 'Medium', 'High'
    $isOpenAlert = $alert.status -in 'InProgress', 'New'
    if($isOpenAlert -and $isSevereAlert)
    {
        if (-not $machinesToInvestigate.Contains($alert.machineId))
        {
            $machinesToInvestigate.Add($alert.machineId) > $null
        }
    }
}

$commaSeparatedMachines = '"{0}"' -f ($machinesToInvestigate -join '","')

$query = "NetworkCommunicationEvents
| where MachineId in ($commaSeparatedMachines)
| where RemoteUrl  == `"$suspiciousUrl`"
| summarize ConnectionsCount = count() by MachineId"

$queryUrl = "https://api.securitycenter.microsoft.com/api/advancedqueries/run"

$queryBody = ConvertTo-Json -InputObject @{ 'Query' = $query }
$queryResponse = Invoke-WebRequest -Method Post -Uri $queryUrl -Headers $headers -Body $queryBody -ErrorAction Stop
$response =  ($queryResponse | ConvertFrom-Json).Results
$response

Consulte também