Investigação avançada com o PowerShell

Aplica-se a:

• Microsoft Defender para Endpoint

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

Execute consultas avançadas com o PowerShell. Para obter mais informações, veja API de Investigação Avançada.

Nesta secção, partilhamos exemplos do PowerShell para obter um token e utilizá-lo para executar uma consulta.

Antes de começar

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 seguinte comando:

  Set-ExecutionPolicy -ExecutionPolicy Bypass
  

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

Obter token

• Execute o seguinte:

$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

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$body = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$response = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $body -ErrorAction Stop
$aadToken = $response.access_token

Onde

• $tenantId: ID do inquilino em nome do qual pretende executar a consulta (ou seja, a consulta é executada nos dados deste inquilino)
• $appId: ID da sua aplicação Microsoft Entra (a aplicação tem de ter a permissão "Executar consultas avançadas" no Defender para Endpoint)
• $appSecret: Segredo da sua aplicação Microsoft Entra

Executar consulta

Execute a seguinte consulta:

$token = $aadToken
$query = 'DeviceRegistryEvents | limit 10' # Paste your own query here

$url = "https://api.securitycenter.microsoft.com/api/advancedqueries/run"
$headers = @{ 
    'Content-Type' = 'application/json'
    Accept = 'application/json'
    Authorization = "Bearer $aadToken" 
}
$body = ConvertTo-Json -InputObject @{ 'Query' = $query }
$webResponse = Invoke-WebRequest -Method Post -Uri $url -Headers $headers -Body $body -ErrorAction Stop
$response =  $webResponse | ConvertFrom-Json
$results = $response.Results
$schema = $response.Schema

• $results contêm os resultados da consulta
• $schema contém o esquema dos resultados da consulta

Consultas complexas

Se quiser executar consultas complexas (ou consultas com várias linhas), guarde a consulta num ficheiro e, em vez da primeira linha no exemplo acima, execute o seguinte comando:

$query = [IO.File]::ReadAllText("C:\myQuery.txt"); # Replace with the path to your file

Trabalhar com resultados de consulta

Agora pode utilizar os resultados da consulta.

Para exportar os resultados da consulta no formato CSV no ficheiro file1.csv, execute o seguinte comando:

$results | ConvertTo-Csv -NoTypeInformation | Set-Content C:\file1.csv

Para exportar os resultados da consulta no formato JSON no ficheiro file1.json, execute o seguinte comando:

$results | ConvertTo-Json | Set-Content file1.json

Artigo relacionado

• APIs do Microsoft Defender para Endpoint
• API de Investigação Avançada
• Investigação Avançada com Python