Partilhar via

Investigação avançada com o PowerShell

  • Artigo

Aplica-se a:

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:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com

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.

Before you begin

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

Sugestão

Quer saber mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.