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개 질문 벤치마크에 대해 쿼리를 실제 실행하여 점수를 매겼습니다:

해당 연구의 ablation 분석은 각 요소의 기여도를 분리합니다: 스키마를 제거하면 정확도가 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에서 설치하세요.

어시스턴트에 연결하기

동일한 서버, 다섯 가지 클라이언트. 원하는 것을 선택하세요.

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로 컴파일하고, 모델에게 카탈로그 파일을 직접 읽도록 지시합니다. 각 파일의 영역은 구분되어 있으므로 기존 메모를 덮어쓰지 않습니다. 변경 사항이 없으면 재실행해도 아무 일도 일어나지 않습니다.

일곱 가지 도구

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"

두 쿼리를 비교하고, 변경 사항(컬럼 교체, 대소문자 수정, 시간 범위 확장, 중복 제거 추가 등)을 분류하여 관련 테이블별로 색인된 하나의 지속적인 문장으로 기록합니다. 다음 번에 dkusto_context가 관련 교훈을 표시합니다. 몇 주가 지나면 에이전트는 일반적인 실수가 아닌 사용자 특정 실수를 하지 않게 됩니다.

개인정보 보호는 중요합니다. 저장소는 .dkusto/memory/에 있으며, dkusto init은 해당 디렉토리를 자동으로 무시하도록 설정합니다 — 내부에 *를 포함한 .gitignore 파일을 작성하여 git이 무시 규칙과 관계없이 이를 추적하지 않도록 합니다. 사용자를 보호하도록 설계되었으며, 사용자 스스로 보호하라고 요구하지 않습니다. 모든 내용은 기록되기 전에 수정(redaction)됩니다: UPN, IP 주소, 호스트 이름, GUID, 해시, 토큰은 자리 표시자로 대체됩니다. 공유 경로는 dkusto export-pack 하나뿐이며, 자동으로 실행되지 않으며, 요청하지 않으면 쿼리 텍스트를 제외합니다. 파일을 보내기 전에 내용을 확인하세요.

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의 일반 데이터입니다. 유효한 항목이 플래그된 경우, 일반적으로 해당 파일에 이름을 추가하는 한 줄짜리 풀 리퀘스트로 수정됩니다. tests/test_validator.py에 실패 케이스를 포함시켜 주세요; 골든 테스트 세트는 유효한 쿼리에 대한 거짓 양성을 가장 심각한 버그로 간주합니다.

라이선스 및 상표

MIT. LICENSE를 참조하세요.

Kusto, Azure Data Explorer, Microsoft Sentinel, Microsoft Defender, GitHub Copilot은 Microsoft Corporation의 상표입니다. 이는 사용자가 제공한 스키마 파일을 읽는 독립적이고 비관련 도구입니다. 어떠한 보증도 암시되지 않습니다.