Detective Kusto

KQL-агент, который сначала читает вашу реальную схему, а потом пишет запрос.

Попросите любую модель написать KQL — и она выдаст то, что выглядит правильно. Затем вы вставляете это в реальный workspace — и оно падает, потому что UserPrincipleName — не столбец, signinlogs — не таблица, а поле, по которому идёт фильтрация, пусто в вашем тенанте. Вы правите руками, немного меньше доверяете инструменту и в конце концов перестаёте его использовать.

D-Kusto устраняет причину. Он хранит локальный каталог таблиц, которые у вас реально есть, файл, где вы записываете, что именно ищете, и валидатор, который проверяет каждое имя в запросе по этому каталогу, прежде чем вы его увидите.

Он не привязан к одному ассистенту. Он использует MCP, поэтому работает в GitHub Copilot, Claude Code, Cursor, Continue и Zed. Если ваш ассистент вообще не поддерживает MCP, инструмент компилирует те же правила в файл инструкций, который ваш ассистент читает.

Почему grounding, в частности

Это собственное открытие Microsoft, а не наше утверждение. В статье NL2KQL (arXiv 2404.02933 — исследование, лежащее в основе ассистента запросов Security Copilot), запросы оценивались путём их фактического выполнения по бенчмарку из 400 вопросов:

Абляция выделяет компоненты: удаление схемы снижает точность с 0,635 до 0,431, а удаление ещё и примеров — до 0,232. Grounding по схеме и проработанные примеры — два самых больших вклада, и именно на них построен этот репозиторий.

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, пока не появится.

Подключение к вашему ассистенту

Один сервер, пять клиентов. Выберите свой.

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 — зарегистрируйте stdio-сервер, запускающий dkusto mcp.

Сервер находит вашу рабочую область, поднимаясь вверх от своего рабочего каталога. Большинство клиентов запускают его в папке проекта, так что это работает «из коробки». Если ваш клиент этого не делает, укажите явно — либо установите DKUSTO_WORKSPACE в env сервера, либо передайте путь, учитывая, что это глобальный флаг и поэтому ставится перед подкомандой:

{ "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 и сообщает модели читать файлы каталога напрямую. Наш участок каждого файла ограничен, так что он не затрёт заметки, которые вы там уже храните. Повторный запуск — это пустая операция, если ничего не изменилось.

Семь инструментов

То, что search_schema возвращает срезы, сделано намеренно. Каталог из 300 таблиц, вставленный в промпт, дорог и даёт худшие ответы, чем сфокусированная горстка.

Что валидатор ловит, а что нет

Он ловит тот сбой, который реально кусает:

• таблицы и столбцы, которые не существуют, с подсказкой «возможно, вы имели в виду»

• столбец, который существует в другой таблице, и он сообщает, в какой именно

• столбец, который был допустим на более раннем этапе конвейера, но был удалён project, project-away или summarize до того, как вы на него сослались

• неправильный регистр — имена сущностей Kusto чувствительны к регистру, поэтому signinlogs упадёт во время выполнения, хотя выглядит нормально

• операторы, которые не являются операторами, «висящие» пайпы

• управляющие команды (.drop, .set-or-replace, .ingest) — отклоняются сразу

Он также предупреждает, не вызывая ошибку, об отсутствии фильтра по времени, о join без явного kind= и о запросе без ограничения строк.

Будем откровенны об ограничениях:

• Это проверка с учётом схемы, а не полноценный парсер. Реальная грамматика KQL от Microsoft находится в .NET-библиотеке; её переписывание на Python было бы проигрышной гонкой. Замена на неё за тем же интерфейсом стоит в планах для тех, кому нужна полная точность.

• Он не проверяет типы выражений.

• Он не может знать, что возвращает плагин evaluate или хранимая функция.

• Когда он сталкивается с тем, что не может смоделировать, он прекращает утверждать: отслеживание столбцов становится открытым, а последующие находки переходят из ошибок в предупреждения. Это намеренное решение. Валидатор, который «кричит волк», будет отключён, и тогда он не ловит ничего. Недостаточная отчётность — правильное направление для отказа.

v1 не выполняет запросы. В нём нет подключения к кластеру и никакой обработки учётных данных. Он читает локальные файлы и возвращает текст запроса.

Цикл обучения

Когда вы редактируете запрос, который дал вам агент, передайте правку обратно:

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

Он вычисляет разницу между двумя версиями, классифицирует, что изменилось — замена столбца, исправление регистра, расширение временного окна, добавление дедупликации — и записывает одно устойчивое предложение, проиндексированное по задействованным таблицам. При следующем вызове dkusto_context показывает соответствующие уроки. Через несколько недель агент перестаёт делать ваши конкретные ошибки, а не ошибки вообще.

Конфиденциальность, потому что это важно. Хранилище находится в .dkusto/memory/, и dkusto init делает этот каталог самоигнорируемым — он создаёт внутри .gitignore с содержимым *, так что git не подхватит его независимо от ваших собственных правил игнорирования. Он защищает вас, а не говорит вам защищаться самостоятельно. Всё перед записью проходит через редокцию: UPN, IP-адреса, имена хостов, GUID, хэши и токены становятся заполнителями. Есть ровно один путь обмена — dkusto export-pack, он никогда не автоматический и исключает текст запросов, если вы специально не попросите. Прочитайте файл, прежде чем отправить его кому-либо.

EXPERTISE.md — та часть, которую пропускают

Схема сообщает агенту, что возможно. EXPERTISE.md сообщает, что полезно: что всплеск менее десяти сбоев — это устаревшие кэшированные учётные данные, а не атака; что ваша сервисная учётная запись доминирует в объёме входов и портит любую базовую линию; что вопрос «впервые увиденное» требует базового временного окна и соединения leftanti, а не одного where.

Агент с grounding, но без файла экспертизы, пишет запросы, которые проходят синтаксический анализ. С ним — пишет запросы, которые стоит запускать. dkusto init даёт вам структурированный шаблон; пятнадцать минут на его заполнение — самое эффективное, что можно сделать с этим инструментом.

Используйте свою собственную схему

Область применения — любой Kusto: Azure Data Explorer, Fabric Eventhouse, Log Analytics, Microsoft Sentinel, Defender XDR advanced hunting. В комплекте нет никакого каталога вендора и никаких предположений о том, как называются ваши таблицы.

dkusto import принимает несколько форматов, включая вывод .show database schema as json, строки getschema и плоское отображение таблица-столбцы. В docs/schema-format.md каждый из них описан с рабочим примером и командой, которая его создаёт.

Одно предупреждение, которое должно быть сразу: образцы значений — это реальные данные. Обезличьте их, прежде чем они попадут в коммит.

Использование вместе с MCP-сервером Sentinel от Microsoft

Они дополняют, а не конкурируют. Сервер Microsoft имеет доступ к живым данным и обогащение сущностей; D-Kusto — ваши пользовательские таблицы, вашу письменную экспертизу, офлайн-валидацию и частный цикл обучения, без подключения к озеру данных и без оплаты за каждый запрос. Зарегистрируйте оба, пишите и проверяйте с помощью одного, выполняйте с помощью другого. В docs/sentinel-mcp.md есть подробности с указанием источников, а всё, что мы не смогли проверить, явно помечено как таковое.

Справочник команд

Планы

Живая read-only интроспекция схемы, обучение на результатах выполнения, обнаружение дрейфа схемы и CLI ask с адаптерами для совместимых с OpenAI конечных точек, Anthropic и Gemini. В docs/roadmap.md чётко указано, что существует сегодня, а что нет.

Участие

Реестры операторов и функций валидатора — это обычные данные в src/dkusto/validator/operators.py. Если он пометил что-то корректное как ошибку, исправление обычно состоит в добавлении одного имени — действительно однострочный pull request. Пожалуйста, добавьте ошибочный случай в tests/test_validator.py; эталонный набор считает ложное срабатывание на корректном запросе самым серьёзным видом ошибки.

Лицензия и товарные знаки

MIT. См. LICENSE.

Kusto, Azure Data Explorer, Microsoft Sentinel, Microsoft Defender и GitHub Copilot являются товарными знаками Microsoft Corporation. Это независимый, неаффилированный инструмент, который читает предоставляемые вами файлы схемы. Никакого одобрения не подразумевается.