Creación de vínculos profundos a consultas de grafos de Microsoft Sentinel

Puede crear un vínculo profundo que abra la página del grafo de Microsoft Sentinel con una consulta específica ya en el editor y, opcionalmente, ejecuta la consulta automáticamente cuando se carga la página. Inserte estos vínculos en runbooks, informes de incidentes u otra documentación para que un respondedor pueda seleccionar un vínculo y saltar directamente a una consulta de investigación preconfigurada en el gráfico correcto.

Las consultas de vínculos profundos se insertan en la dirección URL como texto base64 (base64url) para que se puedan pasar de forma confiable como un único parámetro de dirección URL. La consulta no está cifrada, firmada ni comprimida.

Prerequisites

Para crear un vínculo profundo, necesita los siguientes requisitos previos:

• Una instancia de gráfico que existe en su inquilino. Debe pasar su nombre en el parámetro graphInstance. Para buscar nombres válidos, consulte Buscar valores de graphInstance válidos.
• Texto de consulta que desea abrir en el editor.

Para abrir una consulta vinculada, necesita permiso para ver el grafo y ejecutar consultas. Los vínculos profundos no omiten los controles de acceso, por lo que un usuario sin esos permisos no puede acceder a la consulta vinculada. Para obtener más información, consulte Introducción a gráficos personalizados en Microsoft Sentinel.

Construya la URL del enlace profundo

Una dirección URL de vínculo profundo consta de varios componentes. A continuación se desglosa la estructura básica y cada pieza:

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

Componentes de dirección URL

Desglose de ejemplo

El siguiente vínculo profundo abre la página del grafo de Microsoft Sentinel con una consulta específica rellenada previamente en el editor, pero no la ejecuta automáticamente:

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

El parámetro query se decodifica como la siguiente consulta GQL:

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

Desintegración:

• Base: https://security.microsoft.com/graphs
• Inquilino: tid=12345678-1234-1234-1234-123456789012
• Gráfico: graphInstance=IdentityAttackScenarioGraph
• Consulta: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (codifica en el GQL mostrado anteriormente)
• Ejecución automática: autoRun=false (la consulta no se ejecutará automáticamente)

Codificación de la consulta con base64url

Codifique el query valor con los pasos siguientes. Estos pasos corresponden a la función encodeQueryBase64 de QueryUtils.ts.

1. Codifica el texto sin procesar de la consulta en bytes mediante UTF-8.
2. Codifica esos bytes en Base64.
3. Sustituya + por - y / por _ para que el valor sea apto para URL.
4. Elimina cualquier carácter de relleno = al final.
5. Coloque el resultado en la URL como parámetro query. La codificación de direcciones URL estándar es segura para aplicarse en la parte superior.

Generación del vínculo

El código JavaScript siguiente coincide exactamente con el codificador de la aplicación y ensambla un vínculo 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()}`;

Condiciones para la ejecución automática

Para que la consulta se ejecute automáticamente, todas las condiciones siguientes deben ser verdaderas:

• autoRun no está establecido en la cadena literal false.
• La consulta descodificada no está vacía.
• graphInstance existe para el inquilino.

Búsqueda de valores válidos de graphInstance

Puede usar cualquier instancia de gráfico que exista en su tenant usando su nombre de instancia. Para encontrar los nombres disponibles, o bien explore la interfaz de usuario de gráficos de Microsoft Sentinel o llame a la API GET /graph-instances Graph Service de Microsoft Sentinel. Esta API devuelve las instancias de Graph disponibles para tu tenant. Opcionalmente, puede filtrar los resultados con ?graphTypes=. Use el nombre de cualquier instancia devuelta.

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

Casos de uso comunes

• Abra el grafo y rellene previamente la consulta sin ejecutarla: establezca autoRun=false, como se muestra en el ejemplo. Los usuarios pueden revisar y editar la consulta antes de que se ejecute, lo que evita costos de consulta innecesarios.
• Abra el gráfico sin consulta: omita el query parámetro o establezca addQuery=false. Use esta opción para dirigir a los usuarios a un grafo para la exploración manual sin imponer una consulta predefinida.
• Diríjase a un inquilino específico: incluya tid=<tenant-id>. A continuación, el vínculo profundo se abre en el inquilino correcto sin que el usuario cambie los inquilinos manualmente.

Contenido relacionado

• Introducción a Microsoft Sentinel Graph
• Gráficos personalizados en Microsoft Sentinel
• Creación de gráficos personalizados en Microsoft Sentinel
• Referencia de GQL para el grafo de Microsoft Sentinel