Twórz linki głębokie do zapytań grafowych w Microsoft Sentinel

Możesz utworzyć link bezpośredni, który otwiera stronę wykresu Microsoft Sentinel z określonym zapytaniem już w edytorze, a opcjonalnie uruchamia zapytanie automatycznie po załadowaniu strony. Osadź te linki w runbookach, raportach incydentów lub innej dokumentacji, aby osoba reagująca mogła kliknąć link i przejść bezpośrednio do wstępnie skonfigurowanego zapytania dochodzeniowego na właściwym grafie.

Zapytania linku głębokiego są osadzone w adresie URL jako tekst base64 (base64url), dzięki czemu można je niezawodnie przekazać jako pojedynczy parametr adresu URL. Zapytanie nie jest szyfrowane, podpisane ani skompresowane.

Wymagania wstępne

Aby utworzyć link bezpośredni, potrzebne są następujące wymagania wstępne:

  • Instancja grafu istniejąca w dzierżawcy. Należy przekazać jego nazwę w parametrze graphInstance . Aby znaleźć prawidłowe nazwy, zobacz Znajdowanie prawidłowych wartości graphInstance.
  • Tekst zapytania, który chcesz otworzyć w edytorze.

Aby otworzyć połączone zapytanie, musisz mieć uprawnienia do wyświetlania grafu i uruchamiania zapytań. Linki głębokie nie pomijają kontroli dostępu, więc użytkownik bez tych uprawnień nie może uzyskać dostępu do połączonego zapytania. Aby uzyskać więcej informacji, zobacz Wprowadzenie do grafów niestandardowych w Microsoft Sentinel.

Adres URL linku głębokiego składa się z kilku składników. Poniżej przedstawiono podział podstawowej struktury i każdego elementu:

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

Składniki adresu URL

Component Required Description
https://security.microsoft.com/graphs — Podstawowy adres URL dla wykresów Microsoft Sentinel.
tid=<tenant-id> No Twój identyfikator dzierżawy platformy Azure (GUID). Jeśli pominięto tę wartość, zostanie użyty bieżący dzierżawca.
graphInstance=<graph-name> Yes Nazwa instancji grafu do otwarcia, na przykład IdentityAttackScenarioGraph. Jeśli wartość jest niedostępna lub nieznana, nic nie zostanie wstępnie uzupełnione.
query=<encoded-query> No Zapytanie języka GQL (Graph Query Language) zakodowane w formacie base64url. Wstępnie wypełnia edytor za pomocą zdekodowanego zapytania.
language=<language> No Język zapytań. Jedyną obsługiwaną wartością jest gql. Bez uwzględniania wielkości liter; każda nieznana wartość spada z powrotem do gql.
autoRun=<true\|false> No Czy uruchamiać zapytanie automatycznie po otwarciu karty. Wartość domyślna to true. Tylko ciąg false literału (bez uwzględniania wielkości liter) wyłącza autorun; każda inna wartość uruchamia zapytanie.
addQuery=<true\|false> No Czy wstępnie wypełnić edytor zapytaniem. Wartość domyślna to true. Ustaw na false, aby pozostawić edytor pusty nawet wtedy, gdy występuje query.

Przykładowy podział

Poniższy link bezpośredni otwiera stronę wykresu Microsoft Sentinel z określonym zapytaniem wstępnie wypełnionym w edytorze, ale nie uruchamia go automatycznie:

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

Parametr query dekoduje następujące zapytanie GQL:

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

Podział:

  • Podstawa: https://security.microsoft.com/graphs
  • Dzierżawa: tid=12345678-1234-1234-1234-123456789012
  • Wykres: graphInstance=IdentityAttackScenarioGraph
  • Zapytanie: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (koduje się do postaci GQL pokazanej powyżej)
  • Automatyczne uruchamianie: autoRun=false (zapytanie nie zostanie uruchomione automatycznie)

Kodowanie zapytania przy użyciu biblioteki base64url

Zakoduj query wartość, wykonując następujące kroki. Te kroki są zgodne z funkcją encodeQueryBase64 w pliku QueryUtils.ts.

  1. Zakoduj surowy tekst zapytania w formacie UTF-8 do postaci bajtów.
  2. Base64 koduje te bajty.
  3. Zastąp + ciągiem - oraz / ciągiem _, aby wartość była bezpieczna dla adresów URL.
  4. Usuń końcowe znaki wypełnienia =.
  5. Umieść wynik w adresie URL jako parametr .query Standardowe kodowanie adresów URL jest bezpieczne do zastosowania na górze.

Note

Maksymalna długość wygenerowanego łącza wynosi 7168 znaków. Bardzo duże zapytania mogą nie tworzyć działającego linku głębokiego.

Poniższy kod JavaScript jest dokładnie zgodny z koderem aplikacji i tworzy pełny link bezpośredni:

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

Warunki automatycznego uruchamiania

Aby zapytanie było uruchamiane automatycznie, wszystkie następujące warunki muszą mieć wartość true:

  • autoRun nie ma wartości literału tekstowego false.
  • Zdekodowane zapytanie nie jest puste.
  • Istnieje graphInstance dla dzierżawy.

Znajdowanie prawidłowych wartości grafinstance

Możesz użyć dowolnej instancji grafu istniejącej w dzierżawcy, używając jej nazwy instancji. Aby znaleźć dostępne nazwy, przejrzyj interfejs użytkownika wykresów Microsoft Sentinel lub wywołaj interfejs API usługi GET /graph-instances Microsoft Sentinel Graph. Ten interfejs API zwraca instancje grafu dostępne w Twojej dzierżawie. Opcjonalnie możesz filtrować wyniki za pomocą polecenia ?graphTypes=. Użyj nazwy dowolnej zwróconej instancji.

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

Typowe przypadki użycia

  • Otwórz wykres i wstępnie wypełnij zapytanie bez uruchamiania go: ustaw autoRun=false, jak pokazano w przykładzie. Użytkownicy mogą przeglądać i edytować zapytanie przed jego uruchomieniem, co pozwala uniknąć niepotrzebnych kosztów zapytań.
  • Otwórz graf bez zapytania: pomiń query parametr lub ustaw wartość addQuery=false. Użyj tej opcji, aby skierować użytkowników do grafu na potrzeby ręcznej eksploracji bez nakładania wstępnie zdefiniowanego zapytania.
  • Określanie elementu docelowego dla określonej dzierżawy: uwzględnij element tid=<tenant-id>. Link głęboki otworzy się następnie w odpowiednim tenantcie bez konieczności ręcznego przełączania tenantów przez użytkownika.