ACSC Logo
© 2026 GEMXIT
GEMXIT Logo
Agent Foskett Academy • Lesson 17 • Creating Investigation Parameters with KQL

Creating Investigation Parameters with KQL

Good investigations need focus.
One user.
One device.
One IP address.
One time window.

But typing those values over and over creates mistakes.

In this Agent Foskett Academy lesson, you will learn how defenders use investigation parameters with let statements to make KQL queries easier to update, easier to reuse and much safer during Microsoft Defender XDR and Microsoft Sentinel investigations.

Start Lesson 17 Back to Academy
Agent Foskett Academy lesson explaining how to create investigation parameters with KQL
Lesson overview

Learn how to define investigation values once and reuse them across email, identity, endpoint and network queries.

Create user parameters
Reuse time windows
Build flexible investigations
🎯 Parameters keep the investigation focused.
Define important values once, then use them everywhere the investigation needs them.
Review Lesson 16 →

What are investigation parameters?

An investigation parameter is a value you define at the top of a query so the rest of the query can reuse it.

Instead of typing the same user, device, IP address or time range multiple times, you define it once with let and refer to it throughout the investigation.
User parametersUse one target user across email, sign-in and endpoint activity queries.
Time parametersControl the whole investigation window from one place at the top of the query.
Evidence parametersReuse devices, IP addresses, domains and message IDs across multiple tables.

Investigation scenario

A suspicious sign-in has been reported for one user.

The analyst needs to investigate the same account across sign-ins, email events, URL clicks and endpoint activity.

Rather than manually changing the username in every part of the query, the analyst creates investigation parameters at the top.

Step 1 — Create a target user parameter

Start with the most common investigation value: the user account.
target-user-parameter.kql
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
let targetUser = "user@contoso.com";
SigninLogs
| where UserPrincipalName == targetUser
| project TimeGenerated, UserPrincipalName, IPAddress, ResultDescription
| sort by TimeGenerated desc

Step 2 — Add a time window parameter

A reusable time window lets you change the investigation range once instead of editing multiple where clauses.
time-window-parameter.kql
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
let investigationStart = ago(7d);
let targetUser = "user@contoso.com";
SigninLogs
| where TimeGenerated > investigationStart
| where UserPrincipalName == targetUser
| project TimeGenerated, UserPrincipalName, IPAddress, AppDisplayName, ResultDescription

Why this helps

Parameters make investigations easier to reuse.

When the next incident comes in, you can change the values at the top of the query without rebuilding the entire investigation.
Less repetitionDefine the user, device or IP address once and reuse it throughout the query.
Fewer mistakesAvoid missing one username or time filter when copying and editing a larger query.
Cleaner handoverOther analysts can quickly see what the query is investigating by reading the top lines.

Step 3 — Use several parameters together

Real investigations often need more than one parameter.
multiple-investigation-parameters.kql
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
let investigationStart = ago(7d);
let targetUser = "user@contoso.com";
let suspiciousIP = "203.0.113.10";
SigninLogs
| where TimeGenerated > investigationStart
| where UserPrincipalName == targetUser
| where IPAddress == suspiciousIP
| project TimeGenerated, UserPrincipalName, IPAddress, Location, ResultDescription

Step 4 — Reuse parameters across multiple tables

Once parameters are defined, they can drive several parts of the same investigation.
parameters-across-tables.kql
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11
  12. 12
  13. 13
  14. 14
  15. 15
  16. 16
  17. 17
let investigationStart = ago(7d);
let targetUser = "user@contoso.com";
let emailActivity =
EmailEvents
| where Timestamp > investigationStart
| where RecipientEmailAddress == targetUser
| project TimelineTime = Timestamp, EventType = "Email", Account = RecipientEmailAddress, Detail = Subject;
let clickActivity =
UrlClickEvents
| where Timestamp > investigationStart
| where AccountUpn == targetUser
| project TimelineTime = Timestamp, EventType = "URL click", Account = AccountUpn, Detail = Url;
union emailActivity, clickActivity
| sort by TimelineTime asc

Step 5 — Add device and IP parameters

Endpoint investigations often need a device name, a remote IP address or both.
device-ip-parameters.kql
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
let investigationStart = ago(7d);
let targetDevice = "DESKTOP-01";
let suspiciousIP = "203.0.113.10";
DeviceNetworkEvents
| where Timestamp > investigationStart
| where DeviceName == targetDevice
| where RemoteIP == suspiciousIP
| project Timestamp, DeviceName, InitiatingProcessFileName, RemoteIP, RemotePort

Investigator notes

Parameters should make the query clearer, not more complicated.

A good rule is simple: if a value controls the investigation, put it near the top.
Name them clearlyUse names like targetUser, targetDevice, suspiciousIP and investigationStart.
Keep them visiblePlace important parameters at the top so another analyst can change them quickly.
Avoid overdoing itDo not turn every single value into a parameter if it makes the query harder to read.
🎓 Agent Foskett Academy — Build reusable investigations
You now understand how to create KQL parameters that make investigations easier to update and reuse.
Return to Academy

What you learned

In this lesson, you learned how to create investigation parameters with KQL.
Creating parametersYou used let to define users, time windows, devices and IP addresses at the top of a query.
Reusing valuesYou reused the same values across sign-in, email, URL click and endpoint tables.
Building flexible queriesYou made investigations easier to update, easier to share and easier to repeat.

Continue your investigation

The next step is learning how to use dynamic lists in KQL to investigate multiple users, IP addresses, domains or devices at the same time.
Agent Foskett Academy Return to the full Academy learning path and review earlier KQL foundation lessons.
Using let Statements to Reuse Evidence Review the previous lesson and strengthen your understanding of reusable KQL evidence sets.

Continue learning with Building Investigation Timelines with KQL, Connecting Tables with join, Investigating UrlClickEvents, KQL Threat Hunting Guide and Microsoft Security.

Develop IT. Protect IT. GEMXIT PTY LTD | GEMXIT UK LTD
ACSC Logo

GEMXIT PTY LTD  |  GEMXIT UK LTD  |  © GEMXIT 2026

Creating Investigation Parameters with KQL

Agent Foskett Academy Lesson 17 teaches defenders how to create investigation parameters with KQL using let statements for users, devices, IP addresses and time windows.

Learn KQL parameters for Microsoft Defender XDR

KQL investigation parameters help analysts define important values once and reuse them across Microsoft Defender XDR and Microsoft Sentinel investigations.

KQL investigation parameter lesson for Microsoft security analysts

This Agent Foskett Academy lesson explains how to build flexible, reusable KQL investigations by defining target users, suspicious IP addresses, target devices and investigation time ranges at the top of a query.