Créer des liens profonds vers des requêtes de graphiques Microsoft Sentinel

Vous pouvez créer un lien profond qui ouvre la page de graphique Microsoft Sentinel avec une requête spécifique déjà dans l’éditeur et, si vous le souhaitez, exécute automatiquement la requête lorsque la page se charge. Incorporez ces liens dans des runbooks, des rapports d’incident ou d’autres documents afin qu’un répondeur puisse sélectionner un lien et accéder directement à une requête d’investigation préconfigurée sur le graphique approprié.

Les requêtes de lien profond sont incorporées dans l’URL sous forme de texte Base64 (base64url) afin qu’elles puissent être transmises de manière fiable en tant que paramètre d’URL unique. La requête n’est pas chiffrée, signée ou compressée.

Prerequisites

Pour créer un lien profond, vous avez besoin des conditions préalables suivantes :

• Une instance de graphe qui existe dans votre locataire. Vous passez son nom dans le graphInstance paramètre. Pour rechercher des noms valides, consultez Rechercher des valeurs graphInstance valides.
• Texte de requête que vous souhaitez ouvrir dans l’éditeur.

Pour ouvrir une requête liée, vous devez disposer de l’autorisation d’afficher le graphique et d’exécuter des requêtes. Les liens profonds ne contournent pas les contrôles d’accès. Par conséquent, un utilisateur sans ces autorisations ne peut pas accéder à la requête liée. Pour plus d’informations, consultez Prise en main des graphiques personnalisés dans Microsoft Sentinel.

Construire l’URL de lien profond

Une URL de lien profond se compose de plusieurs composants. Les éléments suivants décomposent la structure de base et chaque pièce :

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

Composants d’URL

Exemple de répartition

Le lien profond suivant ouvre la page graphique Microsoft Sentinel avec une requête spécifique préremplie dans l'éditeur, mais ne l'exécute pas automatiquement :

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

Le query paramètre décode vers la requête GQL suivante :

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

Répartition :

• Base : https://security.microsoft.com/graphs
• Tenant : tid=12345678-1234-1234-1234-123456789012
• Graphique : graphInstance=IdentityAttackScenarioGraph
• Requête : query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (encode le GQL indiqué ci-dessus)
• Exécution automatique : autoRun=false (la requête ne s’exécutera pas automatiquement)

Encoder la requête avec base64url

Encodez la query valeur en procédant comme suit. Ces étapes correspondent à la encodeQueryBase64 fonction dans QueryUtils.ts.

1. Encodez le texte de la requête brute en octets en UTF-8.
2. Encodez ces octets en base64.
3. Remplacez + par - et / par _ pour rendre la valeur compatible avec les URL.
4. Supprimez tous les caractères de remplissage = en fin de chaîne.
5. Placez le résultat dans l’URL en tant que paramètre query. L’encodage d’URL standard est sécurisé pour s’appliquer en haut.

Générer le lien

Le code JavaScript suivant correspond exactement à l’encodeur d’application et assemble un lien profond complet :

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()}`;

Conditions d’exécution automatique

Pour que la requête s’exécute automatiquement, toutes les conditions suivantes doivent être remplies :

• autoRun n’est pas défini sur la chaîne littérale false.
• La requête décodée n’est pas vide.
• graphInstance existe pour le locataire.

Rechercher des valeurs graphInstance valides

Vous pouvez utiliser n’importe quelle instance de graphe existant dans votre environnement à l’aide de son nom d’instance. Pour rechercher les noms disponibles, parcourez l’interface utilisateur des graphiques Microsoft Sentinel ou appelez l’API du service GET /graph-instances Graph Microsoft Sentinel. Cette API retourne les instances de graphe disponibles pour votre locataire. Vous pouvez éventuellement filtrer les résultats avec ?graphTypes=. Utilisez le nom de n’importe quelle instance retournée.

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

Cas d’utilisation courants

• Ouvrez le graphique et remplissez la requête sans l’exécuter : Définir autoRun=false, comme illustré dans l’exemple. Les utilisateurs peuvent passer en revue et modifier la requête avant son exécution, ce qui évite les coûts de requête inutiles.
• Ouvrez le graphique sans requête : omettez le query paramètre ou définissez addQuery=false. Utilisez cette option pour diriger les utilisateurs vers un graphique pour l’exploration manuelle sans imposer de requête prédéfinie.
• Cibler un locataire spécifique : Inclure tid=<tenant-id>. Le lien profond s’ouvre ensuite dans le locataire approprié sans que l’utilisateur change de locataire manuellement.

Contenu connexe

• Vue d’ensemble du graphe Microsoft Sentinel
• Graphiques personnalisés dans Microsoft Sentinel
• Créer des graphiques personnalisés dans Microsoft Sentinel
• Référence GQL de Microsoft Sentinel Graph