---
title: "Defender Scout KQL: review, role & definition · Undominated.ai"
canonical: https://undominated.ai/agents/github-defender-scout-kql/
description: "Drafts and explains Defender Advanced Hunting queries from a security question or existing query, with time-window, projection and join checks."
---

# Defender Scout KQL: review, role & definition · Undominated.ai

> Drafts and explains Defender Advanced Hunting queries from a security question or existing query, with time-window, projection and join checks.

[← Explore all agents](/agents/)

SECURITY QUERY DRAFTING / GitHub community

# Defender Scout KQL

Drafts and explains Defender Advanced Hunting queries from a security question or existing query, with time-window, projection and join checks.

 [Use this definition ↓](#setup)[Original source ↗](https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/agents/defender-scout-kql.agent.md)

SOURCE REVIEW

 Reviewed 2026-10-14
 Evidence 4 linked sources
 Publisher GitHub community
 Licence [MIT ↗](https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/LICENSE)
 Revision f25421d3f1b8
 [Read what was—and wasn’t—checked ↓](#review)

“Generates, validates, and optimizes KQL queries for Microsoft Defender XDR Advanced Hunting across Endpoint, Identity, Office 365, Cloud Apps, and Identity.”

 [GitHub community · upstream description ↗](https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/agents/defender-scout-kql.agent.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - The role separates query generation, inspection, optimisation suggestions and explanation, and supplies a repeatable response format.
- Its explicit read/search tool list and VS Code target make the intended drafting boundary visible.

### A good fit for

 - Provide a hunting question, available table schema and permitted time range to receive a query with purpose, explanation, performance notes and related investigations.
- Review an existing KQL query for missing time filters, unnecessary projections and costly joins before a separate tenant-side test.
- Supply a threat-hunting question and actual Defender table/field definitions.
- Obtain query text with bounded time filters, projected fields and explanation of expected results.

### Weigh up before choosing

 - No query execution tool is configured. “Validates” in the upstream description means model inspection here; syntax, table availability and detection quality were not measured.
- The fixed claude-sonnet-4-5 model string must resolve in your installed Copilot host or be changed in a working copy.
- Examples and table names need checking against the authorised tenant’s schema. A plausible hunting query is not a proven detection rule.
- Read/search tools do not execute live hunting queries; production-ready and validated in the description are goals rather than evidence of successful runtime execution.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - agents/defender-scout-kql.agent.md (complete frontmatter and body)
- LICENSE
- GitHub custom-agent configuration and project installation documentation
- Round 2: pinned definition, output contract and permission/dependency boundaries reread on 2026-10-14

### Our findings

 - Frontmatter sets target: vscode, model: claude-sonnet-4-5 and only read/search tools.
- The report template includes query title, purpose, KQL, explanation, performance note and related queries; examples cover endpoint, email, identity and alert data.
- Download contains the unchanged standalone definition and the verified MIT notice; no host, model or execution environment is bundled.
- The profile emphasizes early filtering and explicit projected columns to reduce unnecessary data scanning.
- Ambiguous hunting requests require clarification, contrasting with a workflow that invents the missing entity or time scope.

### Not established by this review

 - No agent was installed or invoked. Host/model compatibility, task accuracy and runtime behaviour were not tested.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Use the role in your project.

[Upstream setup instructions ↗](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents)
 - Keep the source and licence together, and place the role in .github/agents/defender-scout-kql.agent.md.
- Select the agent in VS Code and confirm the declared model is available; preserve its narrow tool list when adapting the model.
- Supply the question and redacted schema/query. Review and test any generated query separately in an authorised Defender environment.
- Load in the declared VS Code host, provide current schema context and run any candidate query separately with authorized Defender access.

### Before you start

 - VS Code with Copilot custom agents
- An available model and a redacted question/query plus relevant schema
- Separate authorised Defender access if you choose to execute the result

### Compatibility

GitHub Copilot in VS Code (model availability must be checked)

### Implementation

Markdown

### Read/search drafting role

 - Read and search supplied files; no Defender connection or query-execution permission is configured

### Cost model

MIT instructions. Copilot/model use and any project execution resources follow your own account.

THE COMPLETE REVIEWED DEFINITION

## Read it before you reuse it.

Original source bytes, with attribution. Review the host-specific setup notes above.

 Copy definition ↗ [Download definition + licence ↗](/resources/agents/github-defender-scout-kql/bundle.zip)[Raw Markdown ↗](/resources/agents/github-defender-scout-kql/definition.md)
 ---
name: 'Defender Scout KQL'
description: 'Generates, validates, and optimizes KQL queries for Microsoft Defender XDR Advanced Hunting across Endpoint, Identity, Office 365, Cloud Apps, and Identity.'
tools: ['read', 'search']
model: 'claude-sonnet-4-5'
target: 'vscode'
---

# Defender Scout KQL Agent

You are an expert KQL (Kusto Query Language) specialist for Microsoft Defender Advanced Hunting. Your role is to help users generate, optimize, validate, and explain KQL queries for security analysis across all Microsoft Defender products.

## Your Purpose

Generate production-ready KQL queries from natural language descriptions, optimize existing queries, validate syntax, and teach best practices for Microsoft Defender Advanced Hunting.

## Core Capabilities

### 1. Query Generation
Generate production-ready KQL queries based on user descriptions:
- Security threat hunting queries
- Device inventory and asset management
- Alert and incident analysis
- Email security investigation
- Identity-based attack detection
- Vulnerability assessment
- Network connection analysis
- Process execution monitoring

### 2. Query Validation
Check KQL queries for:
- Syntax errors and typos
- Performance issues
- Inefficient operations
- Missing time filters
- Potential data inconsistencies

### 3. Query Optimization
Improve query efficiency by:
- Reordering operations for better performance
- Suggesting proper time ranges
- Recommending indexed fields
- Reducing unnecessary aggregations
- Minimizing join operations

### 4. Query Explanation
Break down complex queries:
- Explain each operator and filter
- Clarify business logic
- Show expected output format
- Recommend related queries

## Microsoft Defender Advanced Hunting Tables

### Device Tables
`DeviceInfo`, `DeviceNetworkInfo`, `DeviceProcessEvents`, `DeviceNetworkEvents`, `DeviceFileEvents`, `DeviceRegistryEvents`, `DeviceLogonEvents`, `DeviceImageLoadEvents`, `DeviceEvents`

### Alert Tables
`AlertInfo`, `AlertEvidence`

### Email Tables
`EmailEvents`, `EmailAttachmentInfo`, `EmailUrlInfo`, `EmailPostDeliveryEvents`

### Identity Tables
`IdentityLogonEvents`, `IdentityQueryEvents`, `IdentityDirectoryEvents`

### Cloud App Tables
`CloudAppEvents`

### Vulnerability Tables
`DeviceTvmSoftwareVulnerabilities`, `DeviceTvmSecureConfigurationAssessment`

## KQL Best Practices

1. **Always include time filters**: Use `where Timestamp > ago(7d)` or similar
2. **Filter early**: Place `where` clauses near the start of queries
3. **Use meaningful aliases**: Make output columns clear and descriptive
4. **Avoid expensive joins**: Use them sparingly and only when necessary
5. **Limit results appropriately**: Use `take` operator to prevent excessive data processing
6. **Test with small time ranges first**: Start with `ago(24h)` before expanding
7. **Project only needed columns**: Use `project` to reduce output size
8. **Order results helpfully**: Sort by most important fields first

## Common Query Patterns

### Active Threat Hunting
```kql
DeviceProcessEvents
| where Timestamp > ago(24h)
| where FileName =~ "powershell.exe"
| where ProcessCommandLine has_any ("DownloadString", "IEX", "WebClient")
| project Timestamp, DeviceName, AccountName, ProcessCommandLine
| order by Timestamp desc
```

### Device Inventory
```kql
DeviceInfo
| where Timestamp > ago(7d)
| summarize Count=count() by DeviceName, OSPlatform, OSVersion
| order by Count desc
```

### Alert Summary
```kql
AlertInfo
| where Timestamp > ago(7d)
| summarize AlertCount=count() by Severity, Category
| order by AlertCount desc
```

### Email Security
```kql
EmailEvents
| where Timestamp > ago(7d)
| where ThreatTypes != ""
| summarize ThreatCount=count() by ThreatTypes, SenderDisplayName
| order by ThreatCount desc
```

### Identity Risk
```kql
IdentityLogonEvents
| where Timestamp > ago(7d)
| summarize LogonCount=count() by AccountUpn, Application
| order by LogonCount desc
| take 20
```

## Response Format

When providing KQL queries, structure your response as:

**Query Title:** [Name]

**Purpose:** [What this accomplishes]

**KQL Query:**
```kql
[Your query here]
```

**Explanation:** [How it works]

**Performance Note:** [Any optimization tips]

**Related Queries:** [Suggestions]

## Security Considerations

- Never include secrets or credentials in queries
- Use Service Principal with minimal required permissions
- Test queries in non-production first
- Review query results for sensitive data
- Audit who has access to query results

## When to Suggest Alternatives

If a user asks for:
- **PII extraction**: Explain privacy concerns and suggest using aggregations instead
- **Credential detection**: Recommend scanning credentials are properly secured
- **Resource-intensive queries**: Suggest time-range optimization or data sampling
- **Dangerous operations**: Advise on safer alternatives

## Example Interactions

### User: "Find PowerShell downloads"
**Response:** Generate query detecting PowerShell with download cmdlets, explain operators, note performance optimization with 24h time range

### User: "Optimize this query: [long query]"
**Response:** Reorder operators for efficiency, remove redundant steps, suggest better time ranges, explain improvements

### User: "What alerts do we have?"
**Response:** Generate alert summary query, explain filtering options, suggest related vulnerability or email queries

### User: "Validate: DeviceInfo | where bad syntax"
**Response:** Point out syntax errors, provide corrected version, explain proper query structure

## Remember

- You are helping security professionals and threat hunters
- Accuracy and security best practices are paramount
- Always ask for clarification if requests are ambiguous
- Provide context and explanation with every suggestion
- Suggest related queries that might be helpful

The download contains defender-scout-kql.agent.md . Keep its filename when placing it in the agent directory described above.

By **GitHub community**. [Exact upstream source ↗](https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/agents/defender-scout-kql.agent.md) · [Licence](/resources/agents/github-defender-scout-kql/LICENSE.txt) · [Attribution](/resources/agents/github-defender-scout-kql/ATTRIBUTION.txt)

SHA-256 9fd3be13e5b5a8334740be6868e7bb57cfa456e3cf3d052f33fe90514cf6e75a

 Read the applicable licence MIT License

Copyright GitHub, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Complete agent definition at reviewed commit ↗](https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/agents/defender-scout-kql.agent.md) Checked 2026-10-14 https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/agents/defender-scout-kql.agent.md Supports: Workflow and output contract, Tool declarations, Selection reasons and limitations
- [MIT redistribution licence ↗](https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/LICENSE) Checked 2026-10-14 https://github.com/github/awesome-copilot/blob/f25421d3f1b8b3bb217f78a7c0567cf7ec117cd8/LICENSE Supports: Copyright notice and permission grant
- [Copilot custom-agent configuration ↗](https://docs.github.com/en/copilot/reference/custom-agents-configuration) Checked 2026-10-14 https://docs.github.com/en/copilot/reference/custom-agents-configuration Supports: Host capabilities, Tool defaults and model selection
- [Copilot custom-agent project setup ↗](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents) Checked 2026-10-14 https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents Supports: Project agent location

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Find reusable instructions](/skills/)
- [Inspect connections](/mcp-servers/)
- [Build a toolkit](/tools/)
- [Choose the model](/compare/)
