Detective Kusto

Un agente KQL que lee tu esquema real antes de escribir una consulta.

Pídele a cualquier modelo que escriba KQL y te dará algo que parece correcto. Luego lo pegas en un workspace real y falla, porque UserPrincipleName no es una columna, signinlogs no es una tabla y el campo por el que filtró está vacío en tu inquilino. Lo corriges a mano, confías un poco menos en la herramienta y, con el tiempo, dejas de preguntar.

D-Kusto soluciona la causa. Mantiene un catálogo local de las tablas que realmente tienes, un archivo donde anotas lo que realmente buscas y un validador que comprueba cada nombre de una consulta contra ese catálogo antes de que tú lo veas.

No está atado a un solo asistente. Habla MCP, por lo que funciona en GitHub Copilot, Claude Code, Cursor, Continue y Zed. Si tu asistente no tiene soporte MCP, compila las mismas reglas en el archivo de instrucciones que sí lee.

Por qué el grounding, específicamente

Este es un hallazgo de Microsoft, no una afirmación nuestra. En el artículo NL2KQL (arXiv 2404.02933 — la investigación detrás del asistente de consultas de Security Copilot), las consultas se puntuaron ejecutándolas contra un banco de pruebas de 400 preguntas:

Su ablación aísla los ingredientes: eliminar el esquema reduce la precisión de 0.635 a 0.431, y eliminar también los ejemplos resueltos la reduce a 0.232. El grounding de esquema y los ejemplos resueltos son los dos mayores contribuyentes, y son en torno a los que está construido este repositorio.

Related MCP server: mcp-kql-server

Lo que obtienes

.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

Todo lo que hay en esa carpeta es tuyo. Nada de ello viene incluido con el paquete.

Inicio rápido

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'

Ese último comando te dice que UserPrincipleName no existe, sugiere UserPrincipalName y lo hace sin tocar un clúster ni una credencial.

Luego apúntalo a tu propio esquema:

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 no está aún en PyPI; instálalo desde git hasta que lo esté.

Conectándolo a tu asistente

Mismo servidor, cinco clientes. Elige el tuyo.

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, con la misma forma que Claude Code.

Continue / Zed — registra un servidor stdio ejecutando dkusto mcp.

El servidor encuentra tu workspace recorriendo hacia arriba desde su directorio de trabajo. La mayoría de los clientes lo lanzan en la carpeta del proyecto, por lo que funciona directamente. Si el tuyo no lo hace, sé explícito: establece DKUSTO_WORKSPACE en el env del servidor, o pasa la ruta, teniendo en cuenta que es una bandera global y por lo tanto va antes del subcomando:

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

Apúntalo al directorio que contiene .dkusto/, o al propio .dkusto/; ambos funcionan. Si la ruta no es un workspace, el servidor termina con un error en lugar de iniciarse y reportar que no tienes tablas.

¿Sin soporte MCP? Ejecuta dkusto instructions. Compila el protocolo más un resumen en vivo de tu workspace en AGENTS.md, .github/copilot-instructions.md, CLAUDE.md y .cursor/rules/dkusto.mdc, y le dice al modelo que lea los archivos del catálogo directamente. Nuestra región de cada archivo está delimitada, por lo que no pisará notas que ya guardes allí. Volver a ejecutarlo es un no-op si nada ha cambiado.

Las siete herramientas

Que search_schema devuelva fragmentos es intencionado. Un catálogo de 300 tablas pegado en un prompt es caro y produce peores respuestas que un puñado enfocado.

Lo que el validador detecta, y lo que no

Detecta el modo de fallo que realmente duele:

• tablas y columnas que no existen, con una sugerencia «quizás quisiste decir»

• una columna que existe en una tabla diferente, y te dice cuál

• una columna que era válida antes en el pipeline pero fue eliminada por un project, project-away o summarize antes de que la referenciaras

• mayúsculas incorrectas: los nombres de entidades en Kusto distinguen mayúsculas, por lo que signinlogs falla en tiempo de ejecución aunque se lea bien

• operadores que no son operadores, pipes colgantes

• comandos de control (.drop, .set-or-replace, .ingest) — rechazados de plano

También advierte, sin fallar, sobre la falta de un filtro temporal, un join sin kind= explícito y una consulta sin límite de filas.

Siendo honestos sobre los límites:

• Es un comprobador que conoce el esquema, no un analizador sintáctico completo. La gramática real de KQL de Microsoft vive en una biblioteca .NET; reimplementarla en Python sería una carrera perdida. Sustituirla por la misma interfaz está en la hoja de ruta para quien quiera fidelidad total.

• No verifica tipos de expresiones.

• No puede saber lo que devuelve un plugin evaluate o una función almacenada.

• Cuando se encuentra con algo que no puede modelar, deja de afirmar: el seguimiento de columnas se vuelve abierto y los hallazgos posteriores pasan de error a advertencia. Esa es una elección deliberada. Un validador que da falsas alarmas se desactiva, y entonces no detecta nada en absoluto. Sub-reportar es la dirección correcta para fallar.

v1 no ejecuta consultas. No hay conexión a clúster ni manejo de credenciales en ninguna parte. Lee archivos locales y devuelve texto de consulta.

El ciclo de aprendizaje

Cuando editas una consulta que el agente te dio, retroalimenta la edición:

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

Hace un diff de ambas, clasifica lo que cambió — un intercambio de columna, una corrección de mayúsculas, una ventana de tiempo ampliada, una deduplicación añadida — y escribe una oración duradera, indexada por las tablas involucradas. dkusto_context muestra las relevantes la próxima vez. En unas semanas, el agente deja de cometer tus errores específicos, en lugar de errores en general.

Privacidad, porque esto importa. El almacén vive en .dkusto/memory/, y dkusto init hace que ese directorio se ignore a sí mismo: escribe un .gitignore que contiene * dentro, para que git no lo recoja sin importar tus propias reglas de ignorado. Te protege a ti en lugar de decirte que te protejas tú. Todo se pasa por redacción antes de escribirse: los UPN, direcciones IP, nombres de host, GUIDs, hashes y tokens se convierten en marcadores de posición. Solo hay una ruta de compartición, dkusto export-pack, nunca es automática, y excluye el texto de la consulta a menos que lo pidas. Lee el archivo antes de enviarlo a cualquier lado.

EXPERTISE.md es la parte que la gente se salta

El esquema le dice al agente qué es posible. EXPERTISE.md le dice qué es útil: que un pico por debajo de diez fallos es una credencial en caché obsoleta y no un ataque, que tu cuenta de servicio domina el volumen de inicios de sesión y arruina cualquier línea base, que una pregunta de primera vez vista necesita una ventana de línea base y un join leftanti en lugar de un único where.

Un agente con grounding pero sin archivo de experiencia escribe consultas que se analizan sintácticamente. Con uno, escribe consultas que merecen la pena ejecutar. dkusto init te da una plantilla estructurada; quince minutos rellenándola es lo que más rendimiento te puede dar con esta herramienta.

Trae tu propio esquema

El alcance es cualquier Kusto: Azure Data Explorer, Fabric Eventhouse, Log Analytics, Microsoft Sentinel, búsqueda avanzada de Defender XDR. No hay ningún catálogo de proveedor incluido en el paquete ni ninguna suposición sobre cómo se llaman tus tablas.

dkusto import acepta varios formatos, incluyendo la salida de .show database schema as json, filas de getschema, y un mapa plano de tabla a columnas. docs/schema-format.md documenta cada uno con un ejemplo resuelto y el comando que lo produce.

Una advertencia que debe ir al principio: los valores de muestra son datos reales. Desinféctalos antes de que se acerquen a un commit.

Usándolo junto con el servidor MCP de Sentinel de Microsoft

Se complementan en lugar de competir. El servidor de Microsoft tiene acceso a datos en vivo y enriquecimiento de entidades; D-Kusto tiene tus tablas personalizadas, tu experiencia escrita, validación sin conexión y un bucle de aprendizaje privado, sin onboarding a un lago de datos ni facturación por consulta. Registra ambos, escribe y valida con uno, ejecuta con el otro. docs/sentinel-mcp.md tiene el detalle, con fuentes citadas y cualquier cosa que no pudimos verificar explícitamente marcada como tal.

Referencia de comandos

Hoja de ruta

Introspección de esquema en vivo solo lectura, aprendizaje a partir de resultados de ejecución, detección de desviación de esquema y un ask en CLI con adaptadores para endpoints compatibles con OpenAI, Anthropic y Gemini. docs/roadmap.md indica claramente lo que existe hoy y lo que no.

Contribuir

Los registros de operadores y funciones del validador son datos simples en src/dkusto/validator/operators.py. Si marcó algo válido, la solución suele ser añadir un nombre allí — una pull request genuinamente de una línea. Por favor, incluye un caso fallido en tests/test_validator.py; el conjunto de oro trata un falso positivo en una consulta válida como el tipo de error más grave.

Licencia y marcas comerciales

MIT. Ver LICENSE.

Kusto, Azure Data Explorer, Microsoft Sentinel, Microsoft Defender y GitHub Copilot son marcas comerciales de Microsoft Corporation. Esta es una herramienta independiente y no afiliada que lee archivos de esquema que tú proporcionas. No se implica ningún respaldo.