microsoft/azure-kusto-irql-graph

IRQL-Graphenfunktionen – Abfrageergebnisse zur Visualisierung

Wende die IRQL-Graphenfunktionsfamilie auf tabellarische Ergebnisse an. Generiere bei einer gegebenen KQL- oder IRQL-Abfrage und der Benutzerbeschreibung des Graphen eine Lift_To_Graph-Zuordnung und stelle nur die gespeicherten Graphenfunktionen zusammen, die benötigt werden, um den Graph im Kusto Explorer zu visualisieren, zu falten, zu extrahieren oder anzureichern. Die Quellabfrage muss IRQL nicht verwenden.

Umfang und Weiterleitung

Anfrage	Verwendung
Vorhandene KQL/IRQL-Zeilen in einen ikonenverzierten visuellen Graphen umwandeln	Dieses Skill: Lift_To_Graph + Graph_Render_View
Knoten falten oder Extract_Node_*, Enrich_Node_* oder Enrich_Graph_* anwenden	Dieses Skill
make-graph, graph-match, kürzeste Pfade, verbundene Komponenten, Graphenmodelle oder Snapshots verwenden	azure-kusto-graph
Eine nicht-triviale KQL/IRQL-Untersuchung aus natürlicher Sprache verfassen	Ein Kusto- oder IRQL-Abfragegenerierungs-Skill, dann dieses Skill

Wenn eine Anfrage Visualisierung und native Graphenanalyse kombiniert, verwende dieses Skill für den Lift-/Render-Teil und azure-kusto-graph für die Operatorsemantik. Ersetze keine Graph-Lift-Funktionen durch einen manuell erstellten, kantenbasierten Graphen, es sei denn, der Benutzer fragt explizit nach nativen Graphenoperatoren.

Eingabevertrag

• Bevorzugte Eingabe: Eine funktionierende KQL/IRQL-Abfrage, die tabellarische Ergebnisse liefert, plus eine natürlichsprachliche Beschreibung der gewünschten Knoten, Kanten, Bezeichnungen, Icons, Extraktionen, Anreicherungen oder Faltungen.
• Dieses Skill ist kein Konverter von natürlicher Sprache zu KQL oder NL-zu-IRQL. Es wandelt vorhandene Abfrageergebnisse in Graphenvisualisierungen um. Für allgemeine NL-zu-KQL- oder NL-zu-IRQL-Konvertierung verwende ein dediziertes Abfragegenerierungs-Skill (separat erhältlich).
• Bewahre die Abfragen, Joins, Filter und Aggregationen der gelieferten Abfrage. Füge nur die Projektionen oder synthetischen IDs hinzu, die für die Graphenzuordnung erforderlich sind.
• Eine einfache natürlichsprachliche Quellenanfrage wird nur unterstützt, wenn sie direkt auf eine bekannte Tabelle oder einen IRQL Get_*-Selektor mit offensichtlichen Spalten und einfachen Filtern abgebildet werden kann. Gib die angenommene Quelle an und erfinde keine Joins, kein Schema oder keine Untersuchungslogik.
• Für nicht-triviale Abfragekonstruktion verwende zunächst ein separates Kusto-/IRQL-Abfragegenerierungs-Skill und wende dann dieses Skill auf seine Ausgabe an.
• Wenn keine Abfrage oder kein Ausgabeschema verfügbar ist und die Quelle nicht trivial ist, fordere die KQL-Abfrage oder ihre Ergebnisspalten an, bevor du eine Zuordnung generierst.

Aktivierungsauslöser

Verwende dieses Skill, wenn der Benutzer:

• KQL/IRQL-Ergebnisse liefert und nach einer IRQL-Graphenvisualisierung oder -zuordnung fragt
• Lift_To_Graph, Graph_Render_View oder Graph_Fold_By_Property erwähnt
• Nach ikonenverzierten Knoten-/Kantenzuordnungen im Kusto Explorer fragt
• Knoten nach einer gemeinsamen Eigenschaft falten/zusammenklappen möchte
• Graphextraktion oder -anreicherung durch Extract_Node_*, Enrich_Node_* oder Enrich_Graph_* anfordert

Aktiviere dieses Skill nicht ausschließlich für graph-match, Graphenpfade/-komponenten, persistente Graphen oder allgemeine make-graph-Konstruktion; diese gehören zu azure-kusto-graph.

Kein Konverter von natürlicher Sprache zu KQL/IRQL. Die Eingabe sollte im Allgemeinen eine funktionierende KQL- oder IRQL-Abfrage sein, deren Ergebnisse eine Graphenvisualisierung benötigen. Einfache NL-Quellenanfragen funktionieren nur für triviale Einzeltabellen-/Selektor-Fälle. Für allgemeine NL-zu-KQL oder NL-zu-IRQL verwende ein dediziertes Abfragegenerierungs-Skill (separat erhältlich).

Umgebung

• Cluster: https://kc7001.eastus.kusto.windows.net
• Datenbanken: ValdyTimes, JoJosHospital (Graphenfunktionen vorbereitgestellt)
• Rendering: Kusto Explorer Desktop-App (make-graph-Visualisierungsfenster)
• Werkzeug: kusto_query (über Azure MCP Server)

Funktionsvorabprüfung

Lift_To_Graph und Graph_Render_View sind gespeicherte Funktionen, keine integrierten Kusto-Operatoren. Bevor du eine Lift-Pipeline generierst oder gegen eine Zieldatenbank ausführst, überprüfe, was bereitgestellt ist:

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

• Lift_To_Graph und Graph_Render_View sind erforderlich.
• Graph_Fold_By_Property ist nur erforderlich, wenn eine Faltung angefordert wird.
• Überprüfe jede Extract_Node_*-, Enrich_Node_*- oder Enrich_Graph_*-Funktion, bevor du sie verwendest; lasse optionale Anreicherungen weg, wenn sie nicht verfügbar sind, es sei denn, der Benutzer möchte sie bereitgestellt haben.
• Wenn eine erforderliche Funktion fehlt und du Berechtigungen zum Ändern der Datenbank hast, frage den Benutzer vor der Bereitstellung um Bestätigung. Verwende dann die .create-or-alter function-Definitionen in references/DEPLOY_IRQL_FUNCTIONS.md. Führe den entsprechenden .create-or-alter-Block aus und wiederhole dann die Vorabprüfung zur Bestätigung.
• Wenn du keine Änderungsberechtigungen hast, teile dem Benutzer mit, welche Funktionen fehlen, und verweise ihn zur manuellen Bereitstellung auf references/DEPLOY_IRQL_FUNCTIONS.md.

IRQL-Graphenfunktionsfamilie

Lift_To_Graph(T, mappingJson)

Wandelt jedes tabellarische KQL-Ergebnis in eine einheitliche Knoten- + Kantentabelle um.

Eingabe: Beliebiges T + ein JSON-Zuordnungsstring. Ausgabe: Zeilen mit EntityType = "node" oder "edge", bereit für make-graph.

Graph_Render_View(T)

Nimmt die Ausgabe von Lift_To_Graph, teilt sie in Knoten/Kanten und ruft make-graph auf, um das Graph-Fenster des Kusto Explorers zu öffnen.

Graph_Fold_By_Property(T, NodeType, PropertyName)

Faltet Knoten eines bestimmten Typs, die einen Eigenschaftswert teilen, zu einem einzigen Knoten zusammen. Verdrahtet Kanten automatisch neu.

Funktionen zur Graphextraktion und -anreicherung

Dies sind zusätzliche gespeicherte Funktionen, die bereits auf der Zieldatenbank bereitgestellt sein müssen. Sie sind nicht in references/DEPLOY_IRQL_FUNCTIONS.md gebündelt. Verwende .show functions, um die Verfügbarkeit zu überprüfen, bevor du sie in eine Pipeline aufnimmst.

Funktion	Operation	Schlüsseleigenschaft
Extract_Node_Email_Sender_Domain(T, displayName)	Fügt Domain zu Knoten-eigenschaften hinzu	EmailSender
Extract_Node_Employee_Firstname(T, displayName)	Fügt Firstname zu Knoten-eigenschaften hinzu	Name
Extract_Node_Event_Network_Domain(T, displayName)	Fügt DomainName zu Knoten-eigenschaften hinzu	Url
Enrich_Node_Ip_Employee(T, displayName)	Fügt Mitarbeiterinfo zu IP-Knoten hinzu	ClientIp
Enrich_Node_Username_Employee(T, displayName)	Fügt Mitarbeiterinfo zu Benutzerknoten hinzu	Username
Enrich_Node_Event_Authentication_Username(T, displayName)	Fügt Authentifizierungskontext hinzu	Username
Enrich_Node_Ip_Domain(T, displayName)	Fügt DNS-Domänen hinzu	ClientIp
Enrich_Node_Ip_Event_NetworkOutbound(T, displayName)	Fügt ausgehende Ereignisse hinzu	ClientIp
Enrich_Graph_Ip_Employee(T, mappingJson)	Erweitert den Graph um Mitarbeiterknoten	ClientIp
Enrich_Graph_Username_Employee(T, mappingJson)	Erweitert den Graph um Mitarbeiterknoten	Username
Enrich_Graph_Event_Authentication_Username(T, mappingJson)	Erweitert um Authentifizierungsknoten	Username

JSON-Zuordnungsschema

Die JSON-Zuordnung enthält zwei Arrays: node_types und edges.

node_types[]

Feld	Erforderlich	Beschreibung
type	Ja	Knotentyplabel (z. B. "User", "Host", "IP")
id	Ja	Präfix für die Knoten-ID; normalerweise identisch mit dem Typ
key	Ja	Spaltenname, dessen Wert zur Identität des Knotens wird
props	Ja	Array von Spalten, die als Knoteneigenschaften übernommen werden
defaults	Nein	Objekt mit Fallback-Werten für null/leere Eigenschaften
defIcon	Nein	Standard-Icon-URL für diesen Knotentyp
displayName	Nein	Spalte, die für das Anzeigelabel verwendet wird (Standard: id)
color	Nein	Spalte, aus der die Farbe bezogen wird
size	Nein	Spalte, aus der die Größe bezogen wird

edges[]

Feld	Erforderlich	Beschreibung
type	Ja	Kantentyplabel (z. B. "AuthenticatesTo", "SentEmail")
source	Ja	{"id": "<Präfix>", "type": "<NodeType>"}
target	Ja	{"id": "<Präfix>", "type": "<NodeType>"}
props	Nein	Array von Spalten, die als Kanteneigenschaften übernommen werden
displayName	Nein	Spalte für das Kantenlabel
color	Nein	Spalte für die Kantenfarbe

Icon-Repository

Verwende Icons von https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/:

• IP: Public-IP-Addresses-(Classic).svg
• Host/VM: Virtual-Machine.svg
• Benutzer: Users.svg
• E-Mail: Mailbox.svg (oder azure-cds/command-1070-Mail.svg)
• Prozess: App-Services.svg
• Datei: Storage-Accounts.svg
• Warnung: Activity-Log.svg
• Domäne: DNS-Zones.svg

Regeln zur Zuordnungsgenerierung

Generiere ausgehend von den Spalten der gelieferten Abfrage und der Benutzerbeschreibung des Graphen die JSON-Zuordnung, indem du:

1. Entitäten identifizierst -> jedes eindeutige Substantiv wird zu einem node_type
2. Beziehungen identifizierst -> jedes Verb/jede Präposition wird zu einer edge
3. Spalten zuordnest -> verwende tatsächliche Spalten, die von der gelieferten Abfrage erzeugt werden; nimm niemals nicht verfügbare Spalten an
4. Richtung festlegst -> Quelle ist der Akteur, Ziel ist der Beeinflusste
5. Eigenschaften hinzufügst -> füge Spalten ein, die für die Untersuchung relevant sind (Zeitstempel, Ergebnisse, Hashes)
6. Icons zuweist -> wähle aus dem oben genannten Icon-Set basierend auf dem Entitätstyp

Spaltenreferenz (IRQL einheitliches Schema)

Entität	Schlüsselspalte	Verfügbare Eigenschaften
Benutzer	Username	Username, Name, Role, Email
Host	Hostname	Hostname
IP	ClientIp	ClientIp
E-Mail-Nachricht	Subject	EnvTime, Subject, Verdict, Url
Absender	EmailSender	EmailSender, Domain
Empfänger	EmailRecipient	EmailRecipient
Prozess	ProcessName	EnvTime, ProcessName, ProcessCommandLine, ProcessHash
Datei	Filename	EnvTime, Filename, Path, Sha256
Domäne	DomainName	DomainName
Authentifizierungsereignis	(synthetische ID)	EnvTime, UserAgent, Result, Description

Funktionsauswahl

1. Beginne mit der gelieferten KQL/IRQL-tabellarischen Pipeline.
2. Verwende Lift_To_Graph(mapping), um Graphenentitäten zu erstellen.
3. Füge Extract_Node_*, Enrich_Node_* oder Enrich_Graph_* nur hinzu, wenn dies angefordert wird und mit den zugeordneten Schlüsseln kompatibel ist.
4. Füge Graph_Fold_By_Property() nur hinzu, wenn eine Gruppierung/Faltung angefordert wird.
5. Beende die visuelle Ausgabe mit Graph_Render_View().
6. Überprüfe vorab die genauen gespeicherten Funktionen, die für die Pipeline ausgewählt wurden.

Pipeline-Muster

// 1. Bewahre die gelieferte KQL- oder IRQL-Abfrage
<Eingabeabfrage>
// 2. In Graph heben
| invoke Lift_To_Graph(<Zuordnungs_JSON>)
// 3. Optional: Graphenentitäten extrahieren oder anreichern
| invoke <Extract_Node_* | Enrich_Node_* | Enrich_Graph_*>()
// 4. Optional: Knoten falten, wenn angefordert
| invoke Graph_Fold_By_Property("<NodeType>", "<PropertyName>")
// 5. Rendern
| invoke Graph_Render_View()

Beispiele

Weitere Aufforderungen und ausgearbeitete Beispiele findest du unter references/EXAMPLES.md.

Authentifizierungsgraph: IP -> AuthEvent -> Benutzer -> Host

Eingabeabfrage: Get_Event_Authentication_All | where Result == "Failed Login" | take 200

Graphanfrage: „Zeige IPs, Authentifizierungsereignisse, Benutzer und Hosts; falte Ereignisse nach Ergebnis.“

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()

E-Mail-Graph: Absender -> Nachricht -> Empfänger

Eingabeabfrage: Get_Email_All | take 400

Graphanfrage: „Visualisiere den Fluss von Absender zu Nachricht zu Empfänger und falte Nachrichten nach Ergebnis (Verdict).“

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()

Untersuchung verdächtiger Domänen (Ende-zu-Ende)

Einfache Quellenanfrage: „Verwende ausgehende Netzwerkereignisse für diese verdächtigen Domänen und stelle IP-zu-Domänen-Verbindungen grafisch dar, angereichert mit Mitarbeiternamen.“

Dies ist der eingeschränkte Fallback: ein bekannter Selektor, ein Extraktor und ein direkter Filter.

let suspicious_domain_mapping = '{"node_types":[{"type":"IP","id":"IP","key":"ClientIp","props":["ClientIp"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/Public-IP-Addresses-(Classic).svg"},{"type":"DomainName","id":"Domain","key":"DomainName","props":["DomainName"],"defaults":{},"defIcon":"https://raw.githubusercontent.com/benc-uk/icon-collection/master/azure-icons/DNS-Zones.svg"}],"edges":[{"type":"ConnectsTo","source":{"id":"IP","type":"IP"},"target":{"id":"Domain","type":"DomainName"},"props":["EnvTime"]}]}';
Get_Event_Network_Outbound
| where DomainName in ("suspicious1.com", "suspicious2.net")
| take 100
| invoke Lift_To_Graph(suspicious_domain_mapping)
| invoke Extract_Node_Event_Network_Domain("DomainName")
| invoke Enrich_Node_Ip_Employee("ClientIp")
| invoke Graph_Render_View()

Fehlerbehebung

„Funktion Lift_To_Graph ist nicht verfügbar“

Überprüfe mit .show functions, ob die Funktionen auf der Zieldatenbank bereitgestellt sind. Siehe references/DEPLOY_IRQL_FUNCTIONS.md für Bereitstellungsanweisungen.

„Knoten erscheinen nicht wie erwartet“

Vergewissere dich, dass id-Präfixe und key-Spalten korrekt über source/target in edges[] verweisen. Überprüfe, ob der Ausdruck extend AuthEventId eine eindeutige Identität erzeugt.

„Graph_Render_View öffnet kein Fenster“

Bestätige, dass du die Kusto Explorer Desktop-App verwendest (nicht die Web-Oberfläche). make-graph erfordert die Desktop-Anwendung für das interaktive Rendering.

Verwandte Skills

• azure-kusto-graph – native make-graph-Analyse mit graph-match, kürzesten Pfaden, Komponenten und persistenten Graphen.
• Kusto/IRQL Query Generation – für die Erstellung nicht-trivialer Abfragen aus natürlicher Sprache; verwende dieses Skill dann für die Visualisierung.

⚠️ Wichtig: Verwende dieses Skill nicht, um generisches NL-zu-KQL/IRQL durchzuführen. Es ist ein Visualisierungsskill, das mit vorhandenen tabellarischen Abfrageergebnissen arbeitet. Wenn keine Abfrage vorliegt und die Quelle nicht trivial ist, fordere zuerst die KQL-Abfrage an.