Microsoft Defender XDR API avançada de caça

  • Artigo

Aplica-se a:

  • Microsoft Defender XDR

Aviso

Essa API de caça avançada é uma versão mais antiga com recursos limitados. Uma versão mais abrangente da API de caça avançada já está disponível na API de segurança do Microsoft Graph. Consulte Caça avançada usando a API de segurança do Microsoft Graph

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 caça avançada é uma ferramenta de caça a ameaças que usa consultas especialmente construídas para examinar os últimos 30 dias de dados de eventos no Microsoft Defender XDR. Você pode usar consultas de caça avançadas para inspecionar atividades incomuns, detectar possíveis ameaças e até mesmo responder a ataques. A API de caça avançada permite que você consulta programaticamente dados de evento.

Cotas e alocação de recursos

As condições a seguir estão relacionadas a todas as consultas.

  1. As consultas exploram e retornam dados dos últimos 30 dias.
  2. Os resultados podem retornar até 100.000 linhas.
  3. Você pode fazer pelo menos 45 chamadas por minuto por locatário. O número de chamadas varia de acordo com o tamanho do locatário.
  4. Cada locatário é alocado recursos de CPU, com base no tamanho do locatário. As consultas serão bloqueadas se o locatário tiver atingido 100% dos recursos alocados até depois do próximo ciclo de 15 minutos. Para evitar consultas bloqueadas devido ao consumo excessivo, siga as diretrizes em Otimizar suas consultas para evitar atingir cotas de CPU.
  5. Se uma única solicitação for executada por mais de três minutos, ela sairá e retornará um erro.
  6. Um 429 código de resposta HTTP indica que você atingiu os recursos de CPU alocados, seja por número de solicitações enviadas ou pelo tempo de execução alocado. Leia o corpo da resposta para entender o limite atingido.

Permissões

Uma das permissões a seguir é necessária para chamar a API de caça avançada. Para saber mais, incluindo como escolher permissões, consulte Acessar as APIs de Proteção de Microsoft Defender XDR.

Tipo de permissão Permissão Nome da exibição de permissão
Application AdvancedHunting.Read.All Executar consultas avançadas
Delegado (conta corporativa ou de estudante) AdvancedHunting.Read Executar consultas avançadas

Observação

Ao obter um token usando credenciais de usuário:

  • O usuário precisa ter a função 'Exibir Dados'.
  • O usuário precisa ter acesso ao dispositivo, com base nas configurações do grupo de dispositivos.

Solicitação HTTP

POST https://api.security.microsoft.com/api/advancedhunting/run

Cabeçalhos de solicitação

Cabeçalho Valor
Autorização Observação do portador {token} : obrigatório
Content-Type application/json

Corpo da solicitação

No corpo da solicitação, forneça um objeto JSON com os seguintes parâmetros:

Parâmetro Tipo Descrição
Consultar Texto A consulta a ser executada. (necessário)

Resposta

Se for bem-sucedido, esse método retornará 200 OKe um objeto QueryResponse no corpo da resposta.

O objeto de resposta contém três propriedades de nível superior:

  1. Estatísticas – Um dicionário de estatísticas de desempenho de consulta.
  2. Esquema – O esquema da resposta, uma lista de pares Name-Type para cada coluna.
  3. Resultados – Uma lista de eventos avançados de caça.

Exemplo

No exemplo a seguir, um usuário envia a consulta abaixo e recebe um objeto de resposta de API contendo Stats, Schemae Results.

Consultar

{
    "Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

Objeto Response

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

Dica

Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender XDR Tech Community.