Deeplinks maken voor Microsoft Sentinel-grafiekquery’s

U kunt een dieptekoppeling maken waarmee de Microsoft Sentinel grafiekpagina wordt geopend met een specifieke query die al in de editor aanwezig is. Desgewenst wordt de query automatisch uitgevoerd wanneer de pagina wordt geladen. Sluit deze koppelingen in in runbooks, incidentrapporten of andere documentatie, zodat een responder een koppeling kan selecteren en rechtstreeks naar een vooraf geconfigureerde onderzoeksquery in de juiste grafiek kan gaan.

Deep Link-query's worden ingesloten in de URL als Base64-tekst (base64url), zodat ze betrouwbaar kunnen worden doorgegeven als één URL-parameter. De query is niet versleuteld, ondertekend of gecomprimeerd.

Voorwaarden

Als u een dieptekoppeling wilt maken, hebt u de volgende vereisten nodig:

• Een graafexemplaar dat in uw tenant bestaat. U geeft de naam door in de graphInstance parameter. Zie Geldige graphInstance-waarden zoeken om geldige namen te vinden.
• De querytekst die u in de editor wilt openen.

Als u een gekoppelde query wilt openen, hebt u toestemming nodig om de grafiek weer te geven en query's uit te voeren. Dieptekoppelingen omzeilen geen toegangsbeheer, zodat een gebruiker zonder deze machtigingen geen toegang heeft tot de gekoppelde query. Zie Aan de slag met aangepaste grafieken in Microsoft Sentinel voor meer informatie.

De URL van de dieptekoppeling maken

Een DEEP Link-URL bestaat uit verschillende onderdelen. Hieronder worden de basisstructuur en elk stuk onderverdeeld:

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

URL-onderdelen

Voorbeeld van uitsplitsing

Met de volgende dieptekoppeling wordt de Microsoft Sentinel grafiekpagina geopend met een specifieke query die vooraf is ingevuld in de editor, maar wordt deze niet automatisch uitgevoerd:

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

De query parameter ontsleutelt de volgende GQL-query:

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

Verdeling:

• Basis: https://security.microsoft.com/graphs
• Tenant: tid=12345678-1234-1234-1234-123456789012
• Grafiek: graphInstance=IdentityAttackScenarioGraph
• Query: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (codeert naar de hierboven weergegeven GQL)
• Automatisch uitvoeren: autoRun=false (query wordt niet automatisch uitgevoerd)

De query coderen met base64url

Codeer de query waarde met de volgende stappen. Deze stappen komen overeen met de encodeQueryBase64 functie in QueryUtils.ts.

1. UTF-8 codeer de onbewerkte querytekst in bytes.
2. Base64 codeer deze bytes.
3. Vervang + door - en / door _ om de waarde-URL-veilig te maken.
4. Verwijder alle afsluitende opvultekens =.
5. Plaats het resultaat in de URL als de query parameter. Standaard-URL-codering is veilig om bovenaan toe te passen.

De koppeling genereren

De volgende JavaScript komt precies overeen met de encoder van de applicatie en stelt een volledige deep link op:

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

Voorwaarden voor autorun

Alle volgende voorwaarden moeten waar zijn om de query automatisch uit te voeren:

• autoRun is niet ingesteld op de letterlijke tekenreeks false.
• De gedecodeerde query is niet leeg.
• De graphInstance bestaat voor de tenant.

Geldige graphInstance-waarden zoeken

U kunt elk grafiekexemplaren gebruiken die in uw tenant aanwezig zijn op basis van de naam van het exemplaar. Als u de beschikbare namen wilt zoeken, bladert u door de gebruikersinterface van Microsoft Sentinel grafieken of roept u de Microsoft Sentinel Graph Service-API GET /graph-instances aan. Deze API retourneert de graafexemplaren die beschikbaar zijn voor uw tenant. U kunt desgewenst de resultaten filteren met ?graphTypes=. Gebruik de naam van een geretourneerd exemplaar.

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

Veelvoorkomende gebruiksvoorbeelden

• Open de grafiek en vul de query vooraf in zonder deze uit te voeren: Instellen autoRun=false, zoals wordt weergegeven in het voorbeeld. Gebruikers kunnen de query controleren en bewerken voordat deze wordt uitgevoerd, waardoor onnodige querykosten worden voorkomen.
• Open de grafiek zonder query: laat de query parameter weg of stel deze in addQuery=false. Gebruik deze optie om gebruikers naar een grafiek te leiden voor handmatig verkennen zonder een vooraf gedefinieerde query op te leggen.
• Richt u op een specifieke tenant: Neem tid=<tenant-id> op. De dieptekoppeling wordt vervolgens geopend in de juiste tenant zonder dat de gebruiker handmatig van tenant wisselt.

Verwante onderwerpen

• Overzicht van Microsoft Sentinel-grafieken
• Aangepaste grafieken in Microsoft Sentinel
• Aangepaste grafieken maken in Microsoft Sentinel
• GQL-verwijzing voor Microsoft Sentinel-grafiek