Creare collegamenti diretti alle query del grafo di Microsoft Sentinel

È possibile creare un collegamento diretto che apre la pagina del grafico Microsoft Sentinel con una query specifica già nell'editor e, facoltativamente, esegue automaticamente la query quando la pagina viene caricata. Incorporare questi collegamenti in runbook, report sugli eventi imprevisti o altra documentazione in modo che un risponditore possa selezionare un collegamento e passare direttamente a una query di indagine preconfigurata nel grafico corretto.

Le query di collegamento diretto sono incorporate nell'URL come testo Base64 (base64url) in modo che possano essere passate in modo affidabile come singolo parametro URL. La query non è crittografata, firmata o compressa.

Prerequisites

Per creare un collegamento diretto, sono necessari i prerequisiti seguenti:

• Un'istanza del grafo che esiste nel tenant. Si passa il relativo nome nel parametro graphInstance. Per trovare nomi validi, vedere Trovare valori graphInstance validi.
• Testo della query che si desidera aprire nell'editor.

Per aprire una query collegata, è necessaria l'autorizzazione per visualizzare il grafico ed eseguire query. I collegamenti diretti non ignorano i controlli di accesso, quindi un utente senza tali autorizzazioni non può accedere alla query collegata. Per altre informazioni, vedere Introduzione ai grafici personalizzati in Microsoft Sentinel.

Costruisci l'URL del deep link

Un URL di collegamento diretto è costituito da diversi componenti. Di seguito viene suddiviso la struttura di base e ogni pezzo:

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

Componenti URL

Scomposizione di esempio

Il collegamento diretto seguente apre la pagina del grafico Microsoft Sentinel con una query specifica precompilata nell'editor, ma non viene eseguita automaticamente:

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

Il query parametro decodifica la query GQL seguente:

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

Dettagli:

• Base: https://security.microsoft.com/graphs
• Tenant: tid=12345678-1234-1234-1234-123456789012
• Grafico: graphInstance=IdentityAttackScenarioGraph
• Query: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (codifica nel GQL illustrato sopra)
• Esecuzione automatica: autoRun=false (la query non verrà eseguita automaticamente)

Codificare la query con base64url

Codificare il query valore con i passaggi seguenti. Questi passaggi corrispondono alla funzione encodeQueryBase64 in QueryUtils.ts.

1. UTF-8 codifica il testo della query non elaborato in byte.
2. Codifica base64 per tali byte.
3. Sostituire + con - e / con _ per rendere sicuro l'URL del valore.
4. Rimuovere tutti i caratteri finali di riempimento =.
5. Posizionare il risultato nell'URL come query parametro. La codifica URL standard può essere applicata in sicurezza in aggiunta.

Generare il collegamento

Il codice JavaScript seguente corrisponde esattamente al codificatore di applicazioni e assembla un collegamento diretto 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()}`;

Condizioni per l'esecuzione automatica

Affinché la query venga eseguita automaticamente, tutte le condizioni seguenti devono essere vere:

• autoRun non è impostato sul valore della stringa letterale false.
• La query decodificata non è vuota.
• L'oggetto graphInstance esiste per il tenant.

Trovare valori graphInstance validi

È possibile usare qualsiasi istanza di Graph esistente nel tuo tenant usando il nome dell'istanza. Per trovare i nomi disponibili, sfogliare l'interfaccia utente dei grafici di Microsoft Sentinel oppure richiamare l'API GET /graph-instances del servizio Microsoft Sentinel Graph. Questa API restituisce le istanze del grafo disponibili per il tenant. Facoltativamente, è possibile filtrare i risultati con ?graphTypes=. Usare il nome di qualsiasi istanza restituita.

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

Casi d'uso comuni

• Aprire il grafo e precompilare la query senza eseguirla: impostare autoRun=false, come illustrato nell'esempio. Gli utenti possono esaminare e modificare la query prima dell'esecuzione, evitando così costi di query non necessari.
• Aprire il grafo senza query: omettere il query parametro o impostare addQuery=false. Usare questa opzione per indirizzare gli utenti a un grafico per l'esplorazione manuale senza imporre una query predefinita.
• Specificare come destinazione un tenant specifico: includere tid=<tenant-id>. Il deep link si apre quindi nel tenant corretto senza che l'utente debba passare manualmente da un tenant all'altro.

Contenuti correlati

• Panoramica del grafico di Microsoft Sentinel
• Grafici personalizzati in Microsoft Sentinel
• Creare grafici personalizzati in Microsoft Sentinel
• Riferimento GQL per il grafo di Microsoft Sentinel