Criar ligações diretas para consultas de grafo do Microsoft Sentinel

Podes criar um link profundo que abre a página do grafo Microsoft Sentinel com uma consulta específica já no editor e, opcionalmente, executa a consulta automaticamente quando a página carrega. Incorpore estes links em runbooks, relatórios de incidentes ou outra documentação para que um respondedor possa selecionar um link e saltar diretamente para uma consulta de investigação pré-configurada no gráfico correto.

As consultas de ligação profunda estão embutidas na URL como texto Base64 (base64url) para que possam ser transmitidas de forma fiável como um único parâmetro URL. A consulta não está encriptada, assinada ou comprimida.

Prerequisites

Para criar uma ligação profunda, precisa dos seguintes pré-requisitos:

• Uma instância de grafo existente no seu locatário. Passa o respetivo nome no parâmetro graphInstance. Para encontrar nomes válidos, veja Encontrar valores válidos de instância de grafo.
• O texto da consulta que queres abrir no editor.

Para abrir uma consulta ligada, precisa de permissão para visualizar o gráfico e executar consultas. Os links profundos não contornam os controlos de acesso, por isso um utilizador sem essas permissões não pode aceder à consulta ligada. Para obter mais informações, veja Introdução aos gráficos personalizados no Microsoft Sentinel.

Crie o URL da hiperligação profunda

Uma URL de ligação profunda consiste em vários componentes. Segue-se uma descrição da estrutura básica e de cada elemento:

https://security.microsoft.com/graphs?tid=<tenant-id>&graphInstance=<graph-name>&query=<encoded-query>&autoRun=<true|false>&addQuery=<true|false>

Componentes de URL

Exemplo de desagregação

O link profundo seguinte abre a página do grafo Microsoft Sentinel com uma consulta específica preenchida no editor, mas não a executa automaticamente:

https://security.microsoft.com/graphs
  ?tid=12345678-1234-1234-1234-123456789012
  &graphInstance=IdentityAttackScenarioGraph
  &query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw
  &autoRun=false

O query parâmetro decodifica-se para a seguinte consulta GQL:

// Visualize any graph
MATCH (x)-[y]->(z)
RETURN *
LIMIT 100

Resumo:

• Base: https://security.microsoft.com/graphs
• Inquilino: tid=12345678-1234-1234-1234-123456789012
• Gráfico: graphInstance=IdentityAttackScenarioGraph
• Consulta: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (codifica para o GQL mostrado acima)
• Execução automática: autoRun=false (a consulta não corre automaticamente)

Codificar a consulta com base64url

Codifica o query valor com os seguintes passos. Estes passos correspondem à função encodeQueryBase64 em QueryUtils.ts.

1. O UTF-8 codifica o texto bruto da consulta em bytes.
2. O Base64 codifica esses bytes.
3. Substitua + por - e / por _ para tornar o valor URL seguro.
4. Remova quaisquer caracteres de preenchimento = finais.
5. Coloque o resultado na URL como parâmetro query . A codificação padrão de URL é segura para aplicar por cima.

Gerar o link

O JavaScript seguinte corresponde exatamente ao codificador da aplicação e constrói uma ligação profunda completa:

function encodeQueryBase64(query) {
  const bytes = new TextEncoder().encode(query);
  const binary = String.fromCharCode(...bytes);
  return btoa(binary)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/g, '');
}

const base = 'https://security.microsoft.com/graphs';
const params = new URLSearchParams({
  graphInstance: 'IdentityAttackScenarioGraph',
  query: encodeQueryBase64('MATCH (x)-[y]->(z)\nRETURN *\nLIMIT 100'),
  autoRun: 'true',
});
const deeplink = `${base}?${params.toString()}`;

Condições para autorun

Para que a consulta seja executada automaticamente, todas as seguintes condições devem ser verdadeiras:

• autoRun não está definido como a cadeia literal false.
• A consulta decodificada não está vazia.
• O graphInstance existe para o tenant.

Encontrar valores válidos de GraphInstance

Podes usar qualquer instância de grafo que exista no teu tenant pelo nome da instância. Para encontrar os nomes disponíveis, navegue pela interface gráfica do Microsoft Sentinel ou ligue para a API do Microsoft Sentinel Graph ServiceGET /graph-instances. Esta API devolve as instâncias do Graph disponíveis para o seu locatário. Pode, opcionalmente, filtrar os resultados com ?graphTypes=. Use o nome de qualquer instância devolvida.

GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom

Casos comuns de utilização

• Abra o grafo e preencha a consulta sem a executar: Defina autoRun=false, como mostrado no exemplo. Os utilizadores podem rever e editar a consulta antes da sua execução, o que evita custos desnecessários da consulta.
• Abra o grafo sem consulta: Omita o query parâmetro, ou defina addQuery=false. Use esta opção para direcionar os utilizadores para um gráfico para exploração manual sem impor uma consulta pré-definida.
• Direcionar um inquilino específico: Incluir tid=<tenant-id>. O deep link abre então no tenant correto sem que o utilizador mude manualmente de tenants.

Conteúdo relacionado

• Visão geral do grafo Microsoft Sentinel
• Gráficos personalizados no Microsoft Sentinel
• Criar gráficos personalizados no Microsoft Sentinel
• Referência de GQL para o grafo do Microsoft Sentinel