Detective Kusto

実際のスキーマを読み取ってからクエリを書くKQLエージェント。

どのモデルにKQLを書かせても、一見正しそうなものが返ってきます。そして実際のワークスペースに貼り付けると失敗します。なぜなら、UserPrincipleName はカラムではなく、signinlogs はテーブルではなく、フィルタ対象のフィールドが自分のテナントでは空だからです。手で修正し、そのツールへの信頼が少し減り、最終的に使わなくなります。

D-Kustoはその原因を修正します。実際に持っているテーブルのローカルカタログ、実際に何を調査しているかを書き留めるファイル、そしてクエリ内のすべての名前をそのカタログと照合してチェックするバリデーターを保持し、あなたが目にする前にチェックします。

特定のアシスタントに依存しません。MCPを話すため、GitHub Copilot、Claude Code、Cursor、Continue、Zedで動作します。アシスタントがMCPをまったくサポートしていない場合でも、同じルールをアシスタントが読み取る指示ファイルにコンパイルします。

なぜグラウンディングが特に重要なのか

これは私たちの主張ではなく、Microsoft自身の調査結果です。NL2KQL論文（arXiv 2404.02933 — Security Copilot クエリアシスタントの背後にある研究）では、400問のベンチマークに対して実際にクエリを実行してスコアを付けました。

彼らのアブレーション研究では、各要素の影響を分離しています。スキーマを削除すると精度が0.635から0.431に低下し、さらにサンプルも削除すると0.232に低下します。スキーマグラウンディングとサンプルが最大の寄与要素であり、このリポジトリはこれらを中心に構築されています。

Related MCP server: mcp-kql-server

得られるもの

.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

そのフォルダ内のものはすべてあなたのものです。パッケージに同梱されるものは何もありません。

クイックスタート

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'

最後のコマンドは、UserPrincipleName が存在しないことを伝え、UserPrincipalName を提案し、クラスターや認証情報に触れることなく実行します。

次に、自分のスキーマを指定します。

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 はまだPyPIに公開されていません。その間はgitからインストールしてください。

アシスタントへの接続

同じサーバー、5つのクライアント。自分のものを選んでください。

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、Claude Codeと同じ形式。

Continue / Zed — dkusto mcp を実行する stdio サーバーを登録します。

サーバーは作業ディレクトリから上位に移動してワークスペースを見つけます。ほとんどのクライアントはプロジェクトフォルダ内で起動するため、そのまま動作します。そうでない場合は明示的に指定します。サーバーの env に DKUSTO_WORKSPACE を設定するか、パスを渡します（グローバルフラグであるため、サブコマンドの前に置くことに注意）。

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

.dkusto/ を含むディレクトリ、または .dkusto/ 自体を指定します。どちらでも動作します。パスがワークスペースでない場合、サーバーは起動せずエラーで終了し、テーブルがないと報告します。

MCPをサポートしていない場合？ dkusto instructions を実行します。プロトコルとワークスペースのライブサマリーを AGENTS.md、.github/copilot-instructions.md、CLAUDE.md、.cursor/rules/dkusto.mdc にコンパイルし、モデルにカタログファイルを直接読むように指示します。各ファイルの該当領域は区切られているため、既存のメモを上書きしません。変更がない場合は再実行しても何も行われません。

7つのツール

search_schema がスライスを返すのは意図的です。300テーブルのカタログをプロンプトに貼り付けるとコストがかかり、焦点を絞った数個よりも悪い回答を生成します。

バリデーターが検出するものと検出しないもの

実際に問題となる失敗モードを捉えます。

• 存在しないテーブルやカラム（「もしかして」提案付き）

• 別のテーブルに存在するカラム（どのテーブルかも表示）

• パイプラインの前半では有効だったが、project、project-away、summarize によって参照前に削除されたカラム

• 大文字小文字の誤り — Kustoのエンティティ名は大文字小文字を区別するため、signinlogs は見た目は正しくても実行時に失敗します

• 演算子ではないもの、ぶら下がったパイプ

• 制御コマンド（.drop、.set-or-replace、.ingest）— 完全に拒否

また、タイムフィルタの欠落、明示的な kind= のない join、行キャップのないクエリについては、失敗はせずに警告を出します。

制限について正直に述べます。

• スキーマ対応のチェッカーであり、完全なパーサーではありません。Microsoftの実際のKQL文法は.NETライブラリにあります。Pythonで再実装するのは負け戦です。同じインターフェースの背後にそれを差し替えることは、完全な忠実度を求める人向けのロードマップにあります。

• 式の型チェックは行いません。

• evaluate プラグインやストアド関数が何を返すかを知ることはできません。

• モデル化できないものに遭遇した場合、アサートを停止します。カラム追跡はオープンになり、以降の検出はエラーから警告に格下げされます。これは意図的な選択です。オオカミ少年のバリデーターはオフにされ、その結果何もキャッチできなくなります。過少報告は失敗すべき正しい方向です。

v1はクエリを実行しません。 クラスター接続や認証情報の処理は一切含まれていません。ローカルファイルを読み取り、クエリテキストを返すだけです。

学習ループ

エージェントが提供したクエリを編集した場合、その編集をフィードバックします。

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

2つのクエリを比較し、変更内容（カラムの交換、大文字小文字の修正、時間枠の拡大、重複除去の追加など）を分類し、対象のテーブルでインデックス付けされた1つの永続的な文を書き出します。次回、dkusto_context が関連するものを表示します。数週間もすれば、エージェントは一般的な間違いではなく、あなた固有の間違いを犯さなくなります。

プライバシーについて、これは重要です。 ストアは .dkusto/memory/ にあり、dkusto init はそのディレクトリを自己無視設定にします。内部に * を含む .gitignore を書き込むため、自分の無視ルールに関係なくgitはそれを拾いません。自分で守ってくださいと言うのではなく、守ってくれます。すべては書き込まれる前にマスク処理を経ます。UPN、IPアドレス、ホスト名、GUID、ハッシュ、トークンはプレースホルダーになります。共有パスは dkusto export-pack の1つだけで、自動的には行われず、明示的に要求しない限りクエリテキストは除外されます。どこかに送信する前にファイルを読んでください。

EXPERTISE.md はみんなが省略する部分

スキーマはエージェントに何が可能かを教えます。EXPERTISE.md は何が有用かを教えます。つまり、10未満のバーストは攻撃ではなく期限切れのキャッシュされた認証情報であること、サービスアカウントがサインイン量の大半を占めてベースラインを歪めること、初めて見たものを尋ねる質問にはベースラインウィンドウと単一の where ではなく leftanti 結合が必要であること、などです。

専門知識ファイルがないグラウンディングエージェントは、解析可能なクエリを書きます。あれば、実行する価値のあるクエリを書きます。dkusto init は構造化されたテンプレートを提供します。15分かけて記入することは、このツールでできる最も効果的なことです。

独自のスキーマを持ち込む

対象はあらゆるKusto：Azure Data Explorer、Fabric Eventhouse、Log Analytics、Microsoft Sentinel、Defender XDR 高度な追求。ベンダーカタログは同梱されておらず、テーブル名についての前提はありません。

dkusto import は .show database schema as json の出力、getschema の行、フラットなテーブル→カラムマップなど、複数の形式を受け入れます。 docs/schema-format.md にそれぞれの形式について、サンプルとそれを生成するコマンドを含めて記載されています。

先に述べておくべき注意点：サンプル値は実際のデータです。コミットの近くに置く前に必ずサニタイズしてください。

MicrosoftのSentinel MCPサーバーとの併用

競合ではなく補完し合います。Microsoftのサーバーはライブデータアクセスとエンティティエンリッチメントを持ち、D-Kustoはカスタムテーブル、あなたの書いた専門知識、オフラインバリデーション、プライベート学習ループを持ち、データレイクのオンボーディングやクエリごとの課金はありません。両方を登録し、一方で作成・検証し、もう一方で実行します。 docs/sentinel-mcp.md に詳細があり、引用元が示され、検証できなかったものは明示的にそのようにフラグ付けされています。

コマンドリファレンス

ロードマップ

ライブ読み取り専用スキーマイントロスペクション、実行結果からの学習、スキーマドリフト検出、およびOpenAI互換エンドポイント、Anthropic、Gemini向けのアダプターを備えたCLI ask。docs/roadmap.md には現在存在するものと存在しないものが明確に記載されています。

コントリビューション

バリデーターの演算子と関数のレジストリは src/dkusto/validator/operators.py のプレーンデータです。有効なものをフラグ付けした場合、修正は通常そこに1つの名前を追加するだけです。真に1行のプルリクエストです。tests/test_validator.py に失敗ケースを含めてください。ゴールデンセットは、有効なクエリに対する誤検出を最も深刻なバグとして扱います。

ライセンスと商標

MIT。 LICENSE を参照。

Kusto、Azure Data Explorer、Microsoft Sentinel、Microsoft Defender、GitHub Copilot は Microsoft Corporation の商標です。これは、お客様が提供するスキーマファイルを読み取る独立した非提携のツールです。いかなる保証も暗示されていません。