Criar links diretos para consultas de grafo do Microsoft Sentinel

Você pode criar um link direto que abre a página de grafo do Microsoft Sentinel com uma consulta específica já inserida no editor e, opcionalmente, executar a consulta automaticamente quando a página for carregada. Insira esses links em runbooks, relatórios de incidentes ou outra documentação para que um respondente possa selecionar um link e ir direto para uma consulta de investigação pré-configurada no grafo correto.

Consultas de link profundo são inseridas na URL como texto Base64 (base64url) para que possam ser passadas de forma confiável como um único parâmetro de URL. A consulta não é criptografada, assinada ou compactada.

Prerequisites

Para criar um link profundo, você precisa dos seguintes pré-requisitos:

  • Uma instância de grafo existente no seu locatário. Você passa o nome dele no graphInstance parâmetro. Para localizar nomes válidos, consulte Localizar valores de graphInstance válidos.
  • O texto de consulta que você deseja abrir no editor.

Para abrir uma consulta vinculada, você precisa de permissão para exibir o grafo e executar consultas. Links profundos não ignoram controles de acesso, portanto, um usuário sem essas permissões não pode acessar a consulta vinculada. Para obter mais informações, veja Introdução aos gráficos personalizados no Microsoft Sentinel.

Uma URL de link profundo consiste em vários componentes. A seguir, detalhamos a estrutura básica e cada parte:

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

Componentes de URL

Componente Obrigatório Description
https://security.microsoft.com/graphs — URL base para grafos de Microsoft Sentinel.
tid=<tenant-id> No Sua ID de locatário Azure (GUID). Se ela for omitida, o banco de dados atual será usado.
graphInstance=<graph-name> Yes Nome da instância do grafo a ser aberta, por exemplo IdentityAttackScenarioGraph. Se o valor estiver ausente ou desconhecido, nada será preenchido previamente.
query=<encoded-query> No Sua consulta GQL (Linguagem de Consulta de Grafo) codificada em base64url. Preenche o editor com a consulta decodificada.
language=<language> No Linguagem de consulta. O único valor com suporte é gql. Não diferencia entre maiúsculas e minúsculas; qualquer valor desconhecido recorre a gql.
autoRun=<true\|false> No Se a consulta será executada automaticamente quando a guia for aberta. Usa true como padrão. Somente a cadeia de caracteres false literal (que não diferencia maiúsculas de minúsculas) desabilita autorun; qualquer outro valor executa a consulta.
addQuery=<true\|false> No Se o editor deve ser preenchido previamente com a consulta. Usa true como padrão. Defina como false para deixar o editor vazio mesmo quando query estiver presente.

Exemplo de detalhamento

O deep link a seguir abre a página de grafo do Microsoft Sentinel com uma consulta específica pré-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 para a seguinte consulta GQL:

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

Colapso:

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

Codificar a consulta com base64url

Codifique o valor query seguindo as etapas abaixo. Essas etapas correspondem à função encodeQueryBase64 em QueryUtils.ts.

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

Note

O comprimento máximo do link gerado é de 7.168 caracteres. Consultas muito grandes podem não gerar um link direto funcional.

O JavaScript a seguir corresponde exatamente ao codificador de aplicativos e monta um link profundo completo:

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 de caracteres false literal.
  • A consulta decodificada não está vazia.
  • O graphInstance existe para o locatário.

Localizar valores de graphInstance válidos

Você pode usar qualquer instância do grafo existente no seu locatário usando o nome da instância. Para encontrar os nomes disponíveis, navegue pela interface de usuário de grafos do Microsoft Sentinel ou faça uma chamada à API do Microsoft Sentinel Graph Service GET /graph-instances. Essa API retorna as instâncias de grafo disponíveis para seu locatário. Opcionalmente, você pode filtrar os resultados com ?graphTypes=. Use o nome de qualquer instância retornada.

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

Casos de uso comuns

  • Abra o grafo e preenchi a consulta sem executá-la: Definir autoRun=false, conforme mostrado no exemplo. Os usuários podem examinar e editar a consulta antes de ela ser executada, o que evita custos desnecessários de consulta.
  • Abra o grafo sem consulta: omita o query parâmetro ou defina addQuery=false. Use essa opção para direcionar os usuários a um grafo para exploração manual sem impor uma consulta predefinida.
  • Direcione para um locatário específico: Inclua tid=<tenant-id>. O link profundo é aberto em seguida no locatário correto, sem que o usuário precise mudar de locatário manualmente.

Conteúdo relacionado

  • Last updated on