Skip to content

Workbooks in Sentinel

Microsoft Sentinel workbooks provide a structured way to encapsulate threat hunting logic, enabling analysts to reuse, share, and refine detection workflows. By combining Kusto Query Language (KQL) with contextual guidance, workbooks streamline repetitive tasks, reduce cognitive load, and ensure consistency across investigations. This section explains how to design reusable KQL-based workbooks for structured threat hunting in Sentinel.

Designing Workbook Structure

A well-structured workbook balances technical precision with human readability. Key components include:
1. Title and description: Clearly define the workbook’s purpose (e.g., "Detecting Lateral Movement via PowerShell").
2. KQL query: The core logic for identifying suspicious activity.
3. Contextual guidance: Notes, indicators, or mitigation steps for analysts.
4. Visualizations: Optional charts or tables to highlight patterns.

Example: A workbook for detecting lateral movement might include a query filtering PowerShell processes with suspicious parameters. 

// Example KQL query for lateral movement detection (parameterized)
let $command = "Invoke-Command";
let $keyword = "IEX";
ProcessCreation
| where ProcessName == "powershell.exe"
| where CommandLine contains $command or CommandLine contains $keyword
| project TimeGenerated, Computer, ProcessName, CommandLine, User
| top 50 by TimeGenerated desc

Writing Reusable KQL Queries

When crafting queries, prioritize modularity and parameterization to enable reuse. Use dynamic parameters (e.g., workspace() or datetime()) to adapt to different environments.

Best Practices:
- Avoid hardcoding values: Use variables for thresholds, process names, or IP ranges.
- Filter efficiently: Leverage where clauses to narrow results early.
- Include metadata: Add tags or properties to categorize queries (e.g., tag: "LateralMovement").

Example: A parameterized query to detect suspicious registry modifications: 

// Detect registry modifications with specific keys (parameterized)
let $targetKey = "HKLM\\Software\\";
RegistryEvents
| where EventID == 4106
| where TargetObject contains $targetKey
| project TimeGenerated, Computer, TargetObject, User

Adding Context and Guidance

Workbooks should guide analysts through next steps, such as:
- Indicator of Compromise (IoC): List IPs, domains, or hashes to check.
- Mitigation steps: Suggest isolation, remediation, or policy updates.
- False positive notes: Highlight common benign scenarios.

Example: A note for the PowerShell query above:

"This query identifies PowerShell processes invoking Invoke-Command or IEX. Verify if the script is signed or sourced from trusted locations. False positives may include legitimate administrative tasks."

Saving and Reusing Workbooks

  1. Export workbooks: Use the Sentinel UI to save queries as .json files for version control or sharing.
  2. Leverage templates: Create reusable templates for common hunting scenarios (e.g., ransomware detection, credential theft).
  3. Integrate with dashboards: Link workbook results to dashboards for real-time monitoring.

Command to export a workbook:

# Export workbook via REST API (example)
Invoke-RestMethod -Uri "https://api.securitycenter.microsoft.com/api/workbooks/{workbookId}" -Method Get -Headers @{Authorization = "Bearer $token"}

Note: The REST API method requires authentication tokens and is one approach. The Sentinel UI also provides an alternative for exporting workbooks as .json files.

Key takeaways

  • Structure workbooks with clear titles, queries, and contextual guidance for reusability.
  • Parameterize KQL to adapt queries to different environments and datasets.
  • Combine technical logic with human-readable notes to reduce analyst cognitive load.
  • Leverage export/import capabilities to version control and share hunting workflows.
  • Integrate with dashboards to enable real-time monitoring and triage.