microsoft/azure-kusto-irql-graph

IRQLグラフ関数 -- クエリ結果を可視化へ

IRQLグラフ関数ファミリーを表形式の結果に適用します。KQLまたはIRQLクエリとユーザーのグラフ記述が与えられた場合、Lift_To_Graphマッピングを生成し、Kusto Explorerでグラフを可視化、フォールド、抽出、またはエンリッチするために必要なストアドグラフ関数のみを構成します。ソースクエリはIRQLを使用する必要はありません。

スコープとルーティング

リクエスト	使用先
指定されたKQL/IRQLの行をアイコンデコレーション付きのビジュアルグラフに変換	このスキル: Lift_To_Graph + Graph_Render_View
ノードのフォールド、またはExtract_Node_*、Enrich_Node_*、Enrich_Graph_*の適用	このスキル
make-graph、graph-match、最短経路、連結成分、グラフモデル、スナップショットの使用	azure-kusto-graph
自然言語から非自明なKQL/IRQL調査クエリの作成	KustoまたはIRQLクエリ生成スキル、次にこのスキル

リクエストが可視化とネイティブグラフ分析を混合している場合は、リフト/レンダリング部分にこのスキルを使用し、演算子のセマンティクスにはazure-kusto-graphを使用してください。ユーザーがネイティブグラフ演算子を要求しない限り、グラフリフト関数を手動で構築されたエッジ優先グラフに置き換えないでください。

入力契約

• 推奨される入力: 表形式の結果を生成する動作するKQL/IRQLクエリと、目的のノード、エッジ、ラベル、アイコン、抽出、エンリッチメント、またはフォールドの自然言語による説明。
• このスキルは自然言語からKQLまたはIRQLへの変換ツールではありません。既存のクエリ結果をグラフ可視化に変換します。一般的なNL-to-KQLまたはNL-to-IRQL変換には、専用のクエリ生成スキル（別途利用可能）を使用してください。
• 指定されたクエリの取得、結合、フィルター、集計を保持します。グラフマッピングに必要な射影または合成IDのみを追加します。
• 基本的な自然言語ソースリクエストは、既知の1つのテーブルまたはIRQL Get_*セレクターに直接マッピングされ、明白な列と単純なフィルターを持つ場合にのみサポートされます。想定されるソースを明記し、結合、スキーマ、または調査ロジックを発明しないでください。
• 非自明なクエリ構築には、最初に別のKusto/IRQLクエリ生成スキルを使用し、次にその出力にこのスキルを適用してください。
• クエリも出力スキーマも利用できず、ソースが自明でない場合は、マッピングを生成する前にKQLクエリまたはその結果列を要求してください。

アクティベーショントリガー

ユーザーが次のことを行った場合にこのスキルを使用します。

• KQL/IRQLの結果を提供し、IRQLグラフの可視化またはマッピングを要求する
• Lift_To_Graph、Graph_Render_View、またはGraph_Fold_By_Propertyに言及する
• Kusto Explorerでのアイコンデコレーション付きノード/エッジマッピングを要求する
• 共有プロパティによるノードのフォールド/折りたたみを希望する
• Extract_Node_*、Enrich_Node_*、またはEnrich_Graph_*を通じたグラフ抽出またはエンリッチメントを要求する

graph-match、グラフパス/コンポーネント、永続グラフ、または一般的なmake-graph構築のみのためにこのスキルをアクティベートしないでください。これらはazure-kusto-graphに属します。

自然言語からKQL/IRQLへの変換ツールではありません。 入力は通常、結果をグラフ可視化する必要がある動作するKQLまたはIRQLクエリである必要があります。基本的なNLソースリクエストは、自明な単一テーブル/セレクターの場合にのみ機能します。一般的なNL-to-KQLまたはNL-to-IRQLには、専用のクエリ生成スキル（別途利用可能）を使用してください。

環境

• クラスター: https://kc7001.eastus.kusto.windows.net
• データベース: ValdyTimes、JoJosHospital（グラフ関数が事前デプロイ済み）
• レンダリング: Kusto Explorerデスクトップアプリ（make-graph可視化ウィンドウ）
• ツール: kusto_query（Azure MCP Server経由）

関数プリフライト

Lift_To_GraphおよびGraph_Render_Viewはストアド関数であり、組み込みのKusto演算子ではありません。ターゲットデータベースに対してリフトパイプラインを生成または実行する前に、デプロイされているものを確認してください。

.show functions
| where Name in~ ("Lift_To_Graph", "Graph_Render_View", "Graph_Fold_By_Property")
| project Name

• Lift_To_GraphとGraph_Render_Viewは必須です。
• Graph_Fold_By_Propertyは、フォールドが要求された場合にのみ必須です。
• 使用する前にExtract_Node_*、Enrich_Node_*、またはEnrich_Graph_*関数を確認してください。利用できない場合はオプションのエンリッチメントを省略します。ただし、ユーザーがそのデプロイを希望する場合は除きます。
• 必須関数が欠落しており、データベースを変更する権限がある場合は、デプロイ前にユーザーに確認を求めてください。次に、references/DEPLOY_IRQL_FUNCTIONS.mdの.create-or-alter function定義を使用します。関連する.create-or-alterブロックを実行し、プリフライトチェックを再実行して確認します。
• 変更権限がない場合は、欠落している関数をユーザーに伝え、手動デプロイのためにreferences/DEPLOY_IRQL_FUNCTIONS.mdを参照するように指示してください。

IRQLグラフ関数ファミリー

Lift_To_Graph(T, mappingJson)

任意の表形式KQL結果を、統一されたノード＋エッジテーブルに変換します。

入力: 任意のテーブルT + JSONマッピング文字列。 出力: EntityType = "node"または"edge"の行。make-graphの準備ができています。

Graph_Render_View(T)

Lift_To_Graphの出力を受け取り、ノード/エッジを分割し、make-graphを呼び出してKusto Explorerのグラフウィンドウを開きます。

Graph_Fold_By_Property(T, NodeType, PropertyName)

指定されたプロパティ値を共有する特定のタイプのノードを単一のノードに折りたたみます。エッジを自動的に再配線します。

グラフ抽出およびエンリッチメント関数

これらは追加のストアド関数であり、ターゲットデータベースに既にデプロイされている必要があります。references/DEPLOY_IRQL_FUNCTIONS.mdにはバンドルされていません。パイプラインに含める前に、.show functionsを使用して可用性を確認してください。

関数	操作	キープロパティ
Extract_Node_Email_Sender_Domain(T, displayName)	ノードプロップにDomainを追加	EmailSender
Extract_Node_Employee_Firstname(T, displayName)	ノードプロップにFirstnameを追加	Name
Extract_Node_Event_Network_Domain(T, displayName)	ノードプロップにDomainNameを追加	Url
Enrich_Node_Ip_Employee(T, displayName)	従業員情報をIPノードに追加	ClientIp
Enrich_Node_Username_Employee(T, displayName)	従業員情報をユーザーノードに追加	Username
Enrich_Node_Event_Authentication_Username(T, displayName)	認証コンテキストを追加	Username
Enrich_Node_Ip_Domain(T, displayName)	DNSドメインを追加	ClientIp
Enrich_Node_Ip_Event_NetworkOutbound(T, displayName)	送信イベントを追加	ClientIp
Enrich_Graph_Ip_Employee(T, mappingJson)	従業員ノードでグラフを拡張	ClientIp
Enrich_Graph_Username_Employee(T, mappingJson)	従業員ノードでグラフを拡張	Username
Enrich_Graph_Event_Authentication_Username(T, mappingJson)	認証ノードで拡張	Username

マッピングJSONスキーマ

JSONマッピングには、node_typesとedgesの2つの配列があります。

node_types[]

フィールド	必須	説明
type	はい	ノードタイプラベル（例："User"、"Host"、"IP"）
id	はい	ノードIDのプレフィックス。通常はtypeと同じ
key	はい	ノードのIDとなる列名
props	はい	ノードプロパティとして保持する列の配列
defaults	いいえ	null/空のプロパティのフォールバック値のオブジェクト
defIcon	いいえ	このノードタイプのデフォルトアイコンURL
displayName	いいえ	表示ラベルに使用する列（デフォルトはid）
color	いいえ	色を取得する列
size	いいえ	サイズを取得する列

edges[]

フィールド	必須	説明
type	はい	エッジタイプラベル（例："AuthenticatesTo"、"SentEmail"）
source	はい	{"id": "<prefix>", "type": "<NodeType>"}
target	はい	{"id": "<prefix>", "type": "<NodeType>"}
props	いいえ	エッジプロパティとして保持する列の配列
displayName	いいえ	エッジラベル用の列
color	いいえ	エッジカラー用の列

アイコンリポジトリ

https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/のアイコンを使用します。

• IP: Public-IP-Addresses-(Classic).svg
• ホスト/VM: Virtual-Machine.svg
• ユーザー: Users.svg
• メール: Mailbox.svg（またはazure-cds/command-1070-Mail.svg）
• プロセス: App-Services.svg
• ファイル: Storage-Accounts.svg
• アラート: Activity-Log.svg
• ドメイン: DNS-Zones.svg

マッピング生成ルール

指定されたクエリ列とユーザーのグラフ記述に基づいて、次のようにマッピングJSONを生成します。

1. エンティティを特定 -> 個別の名詞ごとにnode_typeになる
2. 関係を特定 -> 動詞/前置詞ごとにedgeになる
3. 列にマッピング -> 指定されたクエリが生成する実際の列を使用します。利用できない列を想定しないでください。
4. 方向を設定 -> sourceはアクター、targetは作用される側
5. プロパティを追加 -> 調査に関連する列（タイムスタンプ、結果、ハッシュ）を含めます
6. アイコンを割り当て -> 上記のアイコンセットからエンティティタイプに基づいて選択します

列リファレンス（IRQL統一スキーマ）

エンティティ	キー列	利用可能なプロップ
ユーザー	Username	Username、Name、Role、Email
ホスト	Hostname	Hostname
IP	ClientIp	ClientIp
メールメッセージ	Subject	EnvTime、Subject、Verdict、Url
送信者	EmailSender	EmailSender、Domain
受信者	EmailRecipient	EmailRecipient
プロセス	ProcessName	EnvTime、ProcessName、ProcessCommandLine、ProcessHash
ファイル	Filename	EnvTime、Filename、Path、Sha256
ドメイン	DomainName	DomainName
認証イベント	（合成ID）	EnvTime、UserAgent、Result、Description

関数選択

1. 指定されたKQL/IRQL表形式パイプラインから開始します。
2. Lift_To_Graph(mapping)を使用してグラフエンティティを作成します。
3. 要求され、マップされたキーと互換性がある場合にのみ、Extract_Node_*、Enrich_Node_*、またはEnrich_Graph_*を追加します。
4. グループ化/折りたたみが要求された場合にのみGraph_Fold_By_Property()を追加します。
5. 視覚出力はGraph_Render_View()で終了します。
6. パイプライン用に選択された正確なストアド関数をプリフライトします。

パイプラインパターン

// 1. 指定されたKQLまたはIRQLクエリを保持
<input query>
// 2. グラフにリフト
| invoke Lift_To_Graph(<mapping_json>)
// 3. オプションでグラフエンティティを抽出またはエンリッチ
| invoke <Extract_Node_* | Enrich_Node_* | Enrich_Graph_*>()
// 4. 要求された場合、オプションでノードをフォールド
| invoke Graph_Fold_By_Property("<NodeType>", "<PropertyName>")
// 5. レンダリング
| invoke Graph_Render_View()

例

追加のプロンプトと実際の例については、references/EXAMPLES.mdを参照してください。

認証グラフ：IP -> AuthEvent -> User -> Host

入力クエリ: Get_Event_Authentication_All | where Result == "Failed Login" | take 200

グラフリクエスト: "IP、認証イベント、ユーザー、ホストを表示し、結果でイベントをフォールドします。"

let auth_mapping = '{"node_types":[{"type":"SrcIp","id":"SrcIp","key":"ClientIp","props":["ClientIp"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/Public-IP-Addresses-(Classic).svg"},{"type":"Host","id":"Host","key":"Hostname","props":["Hostname"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/Virtual-Machine.svg"},{"type":"User","id":"User","key":"Username","props":["Username"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/Users.svg"},{"type":"AuthEvent","id":"AuthEvent","key":"AuthEventId","props":["AuthEventId","EnvTime","UserAgent","Result","Description"],"defaults":{"Result":"unknown"},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/Activity-Log.svg"}],"edges":[{"type":"RequestsAuth","source":{"id":"SrcIp","type":"SrcIp"},"target":{"id":"AuthEvent","type":"AuthEvent"},"props":["EnvTime"]},{"type":"TargetsUser","source":{"id":"AuthEvent","type":"AuthEvent"},"target":{"id":"User","type":"User"},"props":["EnvTime"]},{"type":"AgainstHost","source":{"id":"AuthEvent","type":"AuthEvent"},"target":{"id":"Host","type":"Host"},"props":["EnvTime"]}]}';
Get_Event_Authentication_All
| extend AuthEventId = strcat(Username, "_", Hostname, "_", EnvTime)
| where Result == "Failed Login"
| take 200
| invoke Lift_To_Graph(auth_mapping)
| invoke Graph_Fold_By_Property("AuthEvent", "Result")
| invoke Graph_Render_View()

メールグラフ：送信者 -> メッセージ -> 受信者

入力クエリ: Get_Email_All | take 400

グラフリクエスト: "送信者からメッセージ、受信者へのフローを可視化し、判定でメッセージをフォールドします。"

let mail_mapping = '{"node_types":[{"type":"EmailMessage","id":"Message","key":"Subject","props":["EnvTime","Subject","Verdict"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/Media-File.svg"},{"type":"Sender","id":"Email","key":"EmailSender","props":["EmailSender"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-cds/command-1070-Mail.svg"},{"type":"Recipient","id":"Email","key":"EmailRecipient","props":["EmailRecipient"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-cds/command-1070-Mail.svg"}],"edges":[{"type":"SentBy","source":{"id":"Message","type":"EmailMessage"},"target":{"id":"Email","type":"Sender"},"props":["EnvTime","Verdict"]},{"type":"DeliveredTo","source":{"id":"Message","type":"EmailMessage"},"target":{"id":"Email","type":"Recipient"},"props":["EnvTime","Verdict"]}]}';
Get_Email_All
| take 400
| invoke Lift_To_Graph(mail_mapping)
| invoke Graph_Fold_By_Property("EmailMessage", "Verdict")
| invoke Graph_Render_View()

不審なドメイン調査（エンドツーエンド）

基本的なソースリクエスト: "これらの不審なドメインに対して送信ネットワークイベントを使用し、従業員名でエンリッチされたIP-to-ドメイン接続をグラフ化します。"

これは制限されたフォールバックです：1つの既知のセレクター、1つの抽出器、および1つの直接フィルター。

let suspicious_domain_mapping = '{"node_types":[{"type":"IP","id":"IP","key":"ClientIp","props":["ClientIp"],"defaults":{},"defIcon":"https://raw.

…

[翻訳のため省略]