Microsoft Sentinel グラフ クエリへのディープ リンクを作成する

エディターに既に特定のクエリがあるMicrosoft Sentinel グラフ ページを開くディープ リンクを作成し、必要に応じて、ページの読み込み時にクエリを自動的に実行できます。 これらのリンクを Runbook、インシデント レポート、またはその他のドキュメントに埋め込んで、レスポンダーがリンクを選択し、正しいグラフで構成済みの調査クエリに直接移動できるようにします。

ディープ リンク クエリは Base64 (base64url) テキストとして URL に埋め込まれているため、単一の URL パラメーターとして確実に渡すことができます。 クエリは暗号化、署名、または圧縮されていません。

Prerequisites

ディープ リンクを作成するには、次の前提条件が必要です。

• テナント内に存在するグラフ インスタンス。 graphInstance パラメーターにその名前を渡します。 有効な名前を検索するには、「 有効な graphInstance 値を検索する」を参照してください。
• エディターで開くクエリ テキスト。

リンクされたクエリを開くには、グラフを表示してクエリを実行するためのアクセス許可が必要です。 ディープ リンクはアクセス制御をバイパスしないため、これらのアクセス許可を持たないユーザーはリンクされたクエリにアクセスできません。 詳細については、「Microsoft Sentinel でカスタム グラフを使い始める」を参照してください。

ディープ リンク URL を構築する

ディープ リンク URL は、複数のコンポーネントで構成されます。 次に、基本的な構造と各部分を分解します。

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

URL コンポーネント

具体的な例

次のディープ リンクでは、エディターで特定のクエリが事前入力されたMicrosoft Sentinel グラフ ページが開きますが、自動的には実行されません。

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

query パラメーターは、次の GQL クエリにデコードします。

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

内訳：

• ベース: https://security.microsoft.com/graphs
• テナント: tid=12345678-1234-1234-1234-123456789012
• グラフ: graphInstance=IdentityAttackScenarioGraph
• クエリ: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (上記の GQL にエンコード)
• 自動実行: autoRun=false (クエリは自動的に実行されません)

base64url を使用してクエリをエンコードする

次の手順で query 値をエンコードします。 これらの手順は、encodeQueryBase64のQueryUtils.ts関数と一致します。

1. UTF-8 では、生のクエリ テキストをバイトにエンコードします。
2. Base64 はこれらのバイトをエンコードします。
3. +を-に置き換え、/を_に置き換えて、値の URL を安全にします。
4. 末尾の = 埋め込み文字を削除します。
5. 結果を URL に query パラメーターとして配置します。 標準 URL エンコードは、上位に適用しても安全です。

リンクを生成する

次の JavaScript は、アプリケーション エンコーダーと正確に一致し、完全なディープ リンクをアセンブルします。

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

自動実行の条件

クエリを自動的に実行するには、次の条件がすべて満たされている必要があります。

• autoRun がリテラル文字列 falseに設定されていません。
• デコードされたクエリは空ではありません。
• テナントに graphInstance が存在します。

有効な graphInstance 値を検索する

テナント内に存在する任意のグラフ インスタンスは、そのインスタンス名で使用できます。 使用可能な名前を見つけるには、Microsoft Sentinelグラフ UI を参照するか、Microsoft Sentinel Graph Service GET /graph-instances API を呼び出します。 この API は、テナントで使用できるグラフ インスタンスを返します。 必要に応じて、 ?graphTypes=を使用して結果をフィルター処理できます。 返されるインスタンスの名前を使用します。

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

一般的なユース ケース

• グラフを開き、実行せずにクエリを事前入力します。例に示すように、 autoRun=false設定します。 ユーザーはクエリを実行する前に確認および編集できるため、不要なクエリ コストを回避できます。
• クエリなしでグラフを開きます。 query パラメーターを省略するか、 addQuery=false設定します。 このオプションを使用すると、定義済みのクエリを適用せずに手動で探索するためにユーザーをグラフに誘導できます。
• 特定のテナントを対象とする: tid=<tenant-id>を含めます。 その後、ユーザーがテナントを手動で切り替えることなく、正しいテナントでディープ リンクが開きます。

関連するコンテンツ

• Microsoft Sentinel のグラフの概要
• Microsoft Sentinel のカスタム グラフ
• Microsoft Sentinel でカスタム グラフを作成する
• Microsoft Sentinel グラフの GQL リファレンス