Executar consultas KQL no Microsoft Sentinel data lake com APIs

Microsoft Sentinel data lake suporta a execução de consultas Linguagem de Consulta Kusto (KQL) programaticamente através de APIs REST. Isto permite que as equipas de segurança e os sistemas de automatização obtenham resultados analíticos sem utilizar os editores de consultas portal do Azure ou interativos. Este artigo explica quando utilizar a API, as permissões necessárias e como submeter um pedido de consulta básico.

Quando utilizar a API de consulta KQL

A API de consulta KQL foi concebida para cenários de acesso sistema a sistema, incluindo:

  • Fluxos de trabalho de automatização e orquestração
  • Serviços em segundo plano e tarefas agendadas
  • Ferramentas de agente e segurança que requerem resultados de consulta como entrada
  • Integração com sistemas ou agentes externos

Para investigação interativa e análise ad hoc, execute consultas KQL a partir do portal do Defender.

Autenticação e permissões

Pode autenticar-se na API do data lake Sentinel com:

  • Um principal de serviço
  • Um token de acesso de utilizador

Observação

Atualmente, a utilização de um principal de serviço Entra funções de ID e Microsoft Defender XDR funções RBAC unificadas não são suportadas para consultar o Sentinel data lake através desta API.

Como chamar a API

Ponto de extremidade de API

Todas as consultas KQL são submetidas com o seguinte ponto final REST:

POST https://api.securityplatform.microsoft.com/lake/kql/v2/rest/query

Formato do corpo do pedido

Um pedido de consulta consiste em:

  • A consulta KQL
  • A área de trabalho de destino, especificada como workspaceName-workspaceId

Parâmetros de payload

Campo Descrição
csl A consulta KQL a executar
bd O nome da área de trabalho Sentinel e o ID da área de trabalho

Payload de exemplo:

{
"csl": "SigninLogs | take 10",
"db": "workspace1-12345678-abcd-abcd-1234-1234567890ab"
}

Submeter o pedido

O pedido tem de incluir um token de portador OAuth 2.0 no cabeçalho Autorização.

Authorization: Bearer <access_token>
Content-Type: application/json

A API devolve resultados de consulta num formato JSON estruturado que pode ser processado por fluxos de trabalho ou aplicações de automatização.

Definições de consulta opcionais

Pode incluir opções de execução adicionais no payload do pedido, tais como:

  • Tempo limite do servidor
  • Consistência de consultas
  • Imposição só de leitura

Estas opções são úteis ao executar consultas em ambientes automatizados ou de grande escala.

payload de exemplo:

{
    "csl": "SigninLogs | take 10",
    "db": "workspace1-12345678-abcd-abcd-1234-1234567890ab",
    "properties": {
        "Options": {
            "servertimeout": "00:04:00",
            "queryconsistency": "strongconsistency",
            "query_language": "kql",
            "request_readonly": False,
            "request_readonly_hardline": False
        }
    }

Limites e considerações do serviço

A execução de consultas está sujeita a limites de tempo e tamanho dos resultados. Para obter os limites atuais, veja: Microsoft Sentinel limites do serviço Data Lake

Conteúdo relacionado

  • Last updated on