Detective Kusto

Ein KQL-Agent, der Ihr tatsächliches Schema liest, bevor er eine Abfrage schreibt.

Bitten Sie ein beliebiges Modell, KQL zu schreiben, und es wird Ihnen etwas liefern, das richtig aussieht. Dann fügen Sie es in einen echten Arbeitsbereich ein, und es schlägt fehl, weil UserPrincipleName keine Spalte ist, signinlogs keine Tabelle ist und das Feld, nach dem gefiltert wurde, in Ihrem Mandanten leer ist. Sie korrigieren es von Hand, vertrauen dem Tool ein wenig weniger und hören schließlich auf, danach zu fragen.

D-Kusto behebt die Ursache. Es führt einen lokalen Katalog der Tabellen, die Sie tatsächlich haben, eine Datei, in der Sie notieren, wonach Sie tatsächlich suchen, und einen Validator, der jeden Namen in einer Abfrage gegen diesen Katalog prüft, bevor Sie ihn überhaupt zu sehen bekommen.

Es ist nicht an einen Assistenten gebunden. Es spricht MCP, funktioniert also in GitHub Copilot, Claude Code, Cursor, Continue und Zed. Wenn Ihr Assistent überhaupt keine MCP-Unterstützung hat, kompiliert es dieselben Regeln in die Anweisungsdatei, die Ihr Assistent liest.

Why grounding, specifically

Dies ist eine eigene Erkenntnis von Microsoft, nicht unsere Behauptung. In der NL2KQL-Veröffentlichung (arXiv 2404.02933 – die Forschung hinter dem Security Copilot-Abfrageassistenten) wurden Abfragen bewertet, indem sie tatsächlich gegen einen Benchmark mit 400 Fragen ausgeführt wurden:

Ihre Ablation isoliert die Bestandteile: Das Entfernen des Schemas senkt die Genauigkeit von 0,635 auf 0,431, und das zusätzliche Entfernen der ausgearbeiteten Beispiele senkt sie auf 0,232. Schema-Grounding und ausgearbeitete Beispiele sind die beiden größten Beitragenden, und um sie herum ist dieses Repository aufgebaut.

Related MCP server: mcp-kql-server

Was Sie erhalten

.dkusto/
  config.yaml          your databases, query style rules, redaction policy
  EXPERTISE.md         what YOU look for: thresholds, false-positive traps, query shape
  CONTEXT.md           what the data IS: naming conventions, connector gaps, join traps
  catalog/<db>/tables/ one JSON file per table - the schema, the ground truth
  corpus/*.kql         worked examples with front-matter, adapted rather than reinvented
  memory/              learned corrections. Private, gitignored, never shared by default

Alles in diesem Ordner gehört Ihnen. Nichts davon wird mit dem Paket ausgeliefert.

Schnellstart

pip install git+https://github.com/KC-Explore/d-kusto
cd your-project
dkusto init --demo     # a working 6-table synthetic workspace to poke at
dkusto tables
dkusto validate --query 'SigninLogs | where TimeGenerated > ago(1d) | project UserPrincipleName'

Der letzte Befehl teilt Ihnen mit, dass UserPrincipleName nicht existiert, schlägt UserPrincipalName vor und tut dies, ohne einen Cluster oder eine Anmeldeinformation zu berühren.

Dann richten Sie es auf Ihr eigenes Schema aus:

dkusto init                              # a blank workspace
dkusto import my-schema.json             # see docs/schema-format.md for the shapes accepted
$EDITOR .dkusto/EXPERTISE.md             # this is the part that makes it good

d-kusto ist noch nicht auf PyPI; installieren Sie es von Git, bis es soweit ist.

Einbinden in Ihren Assistenten

Derselbe Server, fünf Clients. Wählen Sie Ihren aus.

GitHub Copilot (VS Code) — .vscode/mcp.json

{ "servers": { "dkusto": { "command": "dkusto", "args": ["mcp"] } } }

Claude Code — .mcp.json

{ "mcpServers": { "dkusto": { "command": "dkusto", "args": ["mcp"] } } }

Cursor — ~/.cursor/mcp.json, gleiche Form wie Claude Code.

Continue / Zed — registrieren Sie einen stdio-Server, der dkusto mcp ausführt.

Der Server findet Ihren Arbeitsbereich, indem er von seinem Arbeitsverzeichnis aus nach oben geht. Die meisten Clients starten ihn im Projektordner, also funktioniert das einfach. Wenn Ihres das nicht tut, seien Sie explizit – setzen Sie entweder DKUSTO_WORKSPACE in der env des Servers oder übergeben Sie den Pfad, wobei zu beachten ist, dass es sich um ein globales Flag handelt und daher vor dem Unterbefehl kommt:

{ "command": "dkusto", "args": ["--workspace", "/path/to/project", "mcp"] }

Richten Sie es auf das Verzeichnis, das .dkusto/ enthält, oder auf .dkusto/ selbst; beides funktioniert. Wenn der Pfad kein Arbeitsbereich ist, beendet sich der Server mit einem Fehler, anstatt zu starten und zu melden, dass Sie keine Tabellen haben.

Keine MCP-Unterstützung? Führen Sie dkusto instructions aus. Es kompiliert das Protokoll plus eine Live-Zusammenfassung Ihres Arbeitsbereichs in AGENTS.md, .github/copilot-instructions.md, CLAUDE.md und .cursor/rules/dkusto.mdc und weist das Modell an, die Katalogdateien direkt zu lesen. Unser Bereich jeder Datei ist abgegrenzt, sodass es keine Notizen überschreibt, die Sie dort bereits führen. Eine erneute Ausführung ist ein No-Op, wenn sich nichts geändert hat.

Die sieben Werkzeuge

Dass search_schema Ausschnitte zurückgibt, ist beabsichtigt. Ein Katalog mit 300 Tabellen, der in einen Prompt eingefügt wird, ist teuer und liefert schlechtere Antworten als eine fokussierte Handvoll.

Was der Validator erfasst und was nicht

Es erfasst die Fehlermodi, die tatsächlich wehtun:

• Tabellen und Spalten, die nicht existieren, mit einem ‚Meinten Sie‘

• eine Spalte, die in einer anderen Tabelle existiert, und es sagt Ihnen, welche

• eine Spalte, die früher in der Pipeline gültig war, aber durch ein project, project-away oder summarize entfernt wurde, bevor Sie darauf verwiesen haben

• falsche Groß-/Kleinschreibung – Kusto-Entitätsnamen sind case-sensitiv, daher schlägt signinlogs zur Laufzeit fehl, obwohl es gut lesbar ist

• Operatoren, die keine Operatoren sind, lose Pipes

• Steuerbefehle (.drop, .set-or-replace, .ingest) – rundweg abgelehnt

Es warnt auch, ohne fehlzuschlagen, vor einem fehlenden Zeitfilter, einem join ohne explizites kind= und einer Abfrage ohne Zeilenbegrenzung.

Um ehrlich zu sein, was die Grenzen betrifft:

• Es ist ein schema-bewusster Prüfer, kein vollständiger Parser. Die echte KQL-Grammatik von Microsoft lebt in einer .NET-Bibliothek; eine Neuimplementierung in Python wäre ein verlorenes Rennen. Es hinter derselben Schnittstelle auszutauschen, steht auf der Roadmap für alle, die vollständige Genauigkeit wünschen.

• Es führt keine Typprüfung von Ausdrücken durch.

• Es kann nicht wissen, was ein evaluate-Plugin oder eine gespeicherte Funktion zurückgibt.

• Wenn es auf etwas stößt, das es nicht modellieren kann, hört es auf zu behaupten: Die Spaltenverfolgung wird offen und spätere Funde werden von Fehler auf Warnung herabgestuft. Das ist eine bewusste Entscheidung. Ein Validator, der ‚Wolf‘ schreit, wird abgeschaltet, und dann fängt er gar nichts mehr. Unterberichterstattung ist die richtige Richtung, um zu versagen.

v1 führt keine Abfragen aus. Es gibt keine Clusterverbindung und keine Handhabung von Anmeldeinformationen darin. Es liest lokale Dateien und gibt Abfragetext zurück.

Der Lernkreislauf

Wenn Sie eine Abfrage bearbeiten, die der Agent Ihnen gegeben hat, geben Sie die Bearbeitung zurück:

dkusto learn --original before.kql --corrected after.kql --intent "new-country sign-ins"

Es vergleicht die beiden, klassifiziert, was sich geändert hat – einen Spaltentausch, eine Korrektur der Groß-/Kleinschreibung, ein erweitertes Zeitfenster, eine hinzugefügte Deduplizierung – und schreibt einen dauerhaften Satz, indexiert nach den beteiligten Tabellen. dkusto_context zeigt die relevanten beim nächsten Mal an. Nach ein paar Wochen hört der Agent auf, Ihre spezifischen Fehler zu machen, anstatt allgemeine Fehler.

Datenschutz, weil das wichtig ist. Der Speicher befindet sich in .dkusto/memory/, und dkusto init macht dieses Verzeichnis selbstignorierend – es schreibt eine .gitignore mit * darin, sodass git es nicht aufnimmt, egal was Ihre eigenen Ignorierregeln sagen. Es schützt Sie, anstatt Ihnen zu sagen, dass Sie sich selbst schützen sollen. Alles wird vor dem Schreiben durch Schwärzung geleitet: UPNs, IP-Adressen, Hostnamen, GUIDs, Hashes und Token werden zu Platzhaltern. Es gibt genau einen Freigabepfad, dkusto export-pack, er ist niemals automatisch und schließt Abfragetext aus, es sei denn, Sie fragen danach. Lesen Sie die Datei, bevor Sie sie irgendwohin senden.

EXPERTISE.md ist der Teil, den die Leute überspringen

Das Schema sagt dem Agenten, was möglich ist. EXPERTISE.md sagt ihm, was nützlich ist: dass ein Ausbruch unter zehn Fehlern eher ein veraltetes zwischengespeichertes Anmeldeinformationsobjekt als ein Angriff ist, dass Ihr Dienstkonto das Anmeldevolumen dominiert und jede Baseline zerstört, dass eine Frage zum ersten Mal gesehen ein Baseline-Fenster und einen leftanti-Join benötigt, anstatt eines einzelnen where.

Ein grundierter Agent ohne Expertise-Datei schreibt Abfragen, die parsen. Mit einer schreibt er Abfragen, die es wert sind, ausgeführt zu werden. dkusto init gibt Ihnen eine strukturierte Vorlage; fünfzehn Minuten Ausfüllen ist die wirkungsvollste Sache, die Sie mit diesem Tool tun können.

Bringen Sie Ihr eigenes Schema mit

Der Anwendungsbereich ist jedes Kusto: Azure Data Explorer, Fabric Eventhouse, Log Analytics, Microsoft Sentinel, Defender XDR Advanced Hunting. Es gibt keinen mitgelieferten Anbieterkatalog und keine Annahme darüber, wie Ihre Tabellen heißen.

dkusto import akzeptiert mehrere Formate, darunter die Ausgabe von .show database schema as json, getschema-Zeilen und eine flache Tabelle-zu-Spalten-Zuordnung. docs/schema-format.md dokumentiert jedes mit einem ausgearbeiteten Beispiel und dem Befehl, der es erzeugt.

Eine Warnung, die vorneweg gehört: Beispielwerte sind echte Daten. Bereinigen Sie sie, bevor sie in die Nähe eines Commits kommen.

Verwendung zusammen mit Microsofts Sentinel MCP-Server

Sie ergänzen sich eher, als dass sie konkurrieren. Microsofts Server hat Live-Datenzugriff und Entity-Anreicherung; D-Kusto hat Ihre benutzerdefinierten Tabellen, Ihre schriftliche Expertise, Offline-Validierung und einen privaten Lernkreislauf, ohne Data Lake Onboarding und ohne Abrechnung pro Abfrage. Registrieren Sie beide, schreiben und validieren Sie mit dem einen, führen Sie mit dem anderen aus. docs/sentinel-mcp.md enthält die Details, mit zitierten Quellen und allem, was wir nicht verifizieren konnten, explizit als solches gekennzeichnet.

Befehlsreferenz

Fahrplan

Live-Schema-Introspection (schreibgeschützt), Lernen aus Ausführungsergebnissen, Schema-Drift-Erkennung und ein CLI ask mit Adaptern für OpenAI-kompatible Endpunkte, Anthropic und Gemini. docs/roadmap.md gibt klar an, was heute existiert und was nicht.

Mitwirken

Die Operator- und Funktionsregister des Validators sind einfache Daten in src/dkusto/validator/operators.py. Wenn es etwas Gültiges markiert hat, besteht die Korrektur normalerweise darin, dort einen Namen hinzuzufügen – ein wirklich einzeiliger Pull-Request. Bitte fügen Sie einen fehlschlagenden Fall in tests/test_validator.py hinzu; der Goldstandard behandelt einen Fehlalarm bei einer gültigen Abfrage als schwerwiegendste Art von Fehler.

Lizenz und Marken

MIT. Siehe LICENSE.

Kusto, Azure Data Explorer, Microsoft Sentinel, Microsoft Defender und GitHub Copilot sind Marken der Microsoft Corporation. Dies ist ein unabhängiges, nicht verbundenes Tool, das von Ihnen bereitgestellte Schema-Dateien liest. Es wird keine Befürwortung impliziert.