Gather Rules let you define what data the agent should collect from the device during enrollment. Each rule specifies a collector type (how to collect), a target (what to collect), optional parameters (filters and options), and a trigger (when to collect). Results are sent as events to the backend and appear in the session timeline.
Security
All collector types enforce allowlists on the agent to prevent unauthorized data access. Registry paths, file paths, WMI queries, and commands are validated against hardcoded allowlists before execution. If a rule targets a disallowed resource, the agent emits a security_warning event instead.
Registry
Reads values from the Windows Registry.
Target
Full registry path including hive prefix.
HKLM\SOFTWARE\Microsoft\EnrollmentsParameters
valueName — Read a specific value. Leave empty to read all values in the key (max 50).listSubkeys — Set to true to enumerate subkey names instead of values (max 100). Useful for keys like PolicyManager\current\device where subkeys represent policy areas.Allowed Prefixes
All paths are under HKLM\ or HKCU\. Segment-bounded matching — subkeys are allowed, but sibling keys are not.
Example
Read the BitLocker recovery key status:
Target: HKLM\SYSTEM\CurrentControlSet\Control\BitLockerStatusEvent Log
Reads entries from Windows Event Logs — supports both classic logs (Application, System, Security) and operational/analytic logs (e.g., Microsoft-Windows-Shell-Core/Operational).
Target
The full event log name.
Microsoft-Windows-Shell-Core/OperationalParameters
eventId — Filter by a specific Event ID (e.g., 62407). Leave empty for all events.messageFilter — Contains-filter on the event message. Use * as wildcard (e.g., *ESPProgress*).maxEntries — Max events to return (1–50, default: 10).source — Filter by provider/source name.Example — ESP Progress Telemetry
Collect Shell-Core ESP progress events at enrollment completion:
Target: Microsoft-Windows-Shell-Core/Operational
Event ID: 62407
Message Filter: *ESPProgress*
Max Entries: 50
Trigger: On Event → enrollment_complete
WMI Query
Executes a WMI/CIM query using full WQL syntax. The target must be a complete SELECT statement.
Target
Full WQL query string. Must start with an allowed class prefix.
SELECT * FROM Win32_BIOSAllowed WMI Classes
Example — Network Adapter Monitoring
Monitor network adapters every 30 seconds during enrollment:
Target: SELECT * FROM Win32_NetworkAdapterConfiguration
Trigger: Interval → 30 seconds
File
Checks file or directory existence and optionally reads file content. Environment variables are expanded.
Target
File or directory path. Environment variables like %ProgramData% are supported. The custom token %LOGGED_ON_USER_PROFILE% resolves to the logged-on user's profile path (e.g. C:\Users\JohnDoe). Only AppData\Local and AppData\Roaming subdirectories are allowed.
C:\Windows\Panther\UnattendGC\setupact.log%LOGGED_ON_USER_PROFILE% token
The agent runs as SYSTEM — standard variables like %USERPROFILE% or %LOCALAPPDATA% resolve to the SYSTEM profile, not the logged-on user. Use %LOGGED_ON_USER_PROFILE% instead to target user-specific log files.
Example: %LOGGED_ON_USER_PROFILE%\AppData\Local\RealmJoin\Logs\*.log
During SYSTEM-context phases (before user logon), rules using this token are skipped automatically until a user session is detected.
Parameters
readContent — Set to true to read file content (files must be <50 KB). The agent reads the last 4000 characters — most relevant for log files where recent entries are at the end.Allowed Path Prefixes
Example
Read the Panther setup log on failure:
Target: C:\Windows\Panther\setuperr.log
Parameters: readContent: true
Trigger: On Event → enrollment_failed
Command (Allowlisted)
Runs a pre-approved command (PowerShell or CLI). Only commands from the exact allowlist are permitted — custom commands are blocked.
Target
The exact command string as it appears in the allowlist. Must match exactly (case-insensitive).
Allowed Commands
Data fields produced
Unlike structured collectors (JSON, XML, WMI) where individual fields are extracted, a command produces raw text output. The event data contains:
output — Standard output (stdout) of the command, max 32 KBerror_output — Standard error (stderr), max 8 KBexit_code — Process exit code (0 = success)command — The command string that was executedIn Analyze Rules, use dataField: "output" with operators like contains, not_contains, or regex to inspect the command output.
Example — TPM at Enrollment Complete
Target: Get-Tpm
Trigger: On Event → enrollment_complete
Log Parser
Parses log files using regex patterns with named capture groups. Each match emits a separate event. Supports CMTrace format (default) and plain text mode. Supports position tracking to resume from the last read position.
Target
Path to a log file. Environment variables and the %LOGGED_ON_USER_PROFILE% token are expanded. Supports wildcards (* and ?) in the filename to match multiple files.
%ProgramData%\Microsoft\IntuneManagementExtension\Logs\AppWorkload.log
# Wildcard examples:
%ProgramData%\Microsoft\IntuneManagementExtension\Logs\AppWorkload*.log
C:\Windows\Logs\CBS\CBS-??????.log
# User profile example:
%LOGGED_ON_USER_PROFILE%\AppData\Local\RealmJoin\Logs\*.log
Wildcard matches are sorted by last write time (newest first), capped at 20 files. Position tracking works per file.
Parameters
pattern (required) — Regex with named capture groups, e.g., (?<appName>\w+)format — cmtrace (default) or text. CMTrace mode parses log structure and matches regex against the message field. Text mode matches regex directly against each raw line.trackPosition — true (default) to resume from last read position across executions.maxLines — Max lines to read per file per execution (default: 1000).Example — CMTrace: IME App Workload
Target: %ProgramData%\Microsoft\IntuneManagementExtension\Logs\AppWorkload.log
Format: CMTrace (default)
Pattern: (?<action>Install|Uninstall).*(?<appName>[A-Za-z0-9_-]+)
Trigger: Interval → 30 seconds
Example — Plain Text: CBS Logs with Wildcard
Target: C:\Windows\Logs\CBS\CBS*.log
Format: Text
Pattern: (?<timestamp>\d{4}-\d{2}-\d{2}).*(?<level>Error|Warning).*(?<message>.*)
Trigger: Startup
JSON (JSONPath)
Parses a JSON file and extracts values using JSONPath expressions. Returns matched values as event data. File size limit is 200 KB.
Target
Path to a JSON file. Environment variables are expanded. Must be within allowed directories (same as File collector).
Parameters
jsonpath (required) — JSONPath expression to query the document.maxResults — Maximum matches to return (default: 20, max: 100).JSONPath Syntax
$ — Root element
$.key — Property of root
$.store.book[0] — First array element
$.store.book[*].author — All authors
$..price — Recursive descent (all prices anywhere)
$.items[?(@.active==true)] — Filter expression
Example — Read IME Policy JSON
Target: C:\ProgramData\Microsoft\IntuneManagementExtension\Logs\HealthScripts.json
JSONPath: $..DetectionScript
Trigger: Startup
XML (XPath)
Parses an XML file and extracts values using XPath expressions. Returns matched elements/attributes as event data. File size limit is 200 KB. DTD processing is disabled for security.
Target
Path to an XML file. Environment variables are expanded. Must be within allowed directories (same as File collector).
Parameters
xpath (required) — XPath expression to query the document.namespaces — Namespace declarations (format: prefix=uri;prefix2=uri2).maxResults — Maximum matches to return (default: 20, max: 100).XPath Syntax
/root/element — Absolute path
//element — Anywhere in document
/root/item[@id='1'] — Attribute filter
/root/element/@attr — Attribute value
/root/element/text() — Text content
count(//item) — Count elements
Example — Unattend.xml Settings
Target: C:\Windows\Panther\unattend.xml
XPath: //ns:setting[@name='ComputerName']/@value
Namespaces: ns=urn:schemas-microsoft-com:unattend
Trigger: Startup
Triggers define when a gather rule executes. Choose the trigger that matches your collection needs.
Startup
Runs once when the agent starts monitoring. Use for collecting initial device state (BIOS, TPM, OS info).
Interval
Runs repeatedly at a configurable interval (5–3600 seconds). Use for continuous monitoring like network status or policy changes.
Phase Change
Runs when enrollment transitions to a specific phase. Valid phases:
Start, DevicePreparation, DeviceSetup, AppsDevice, AccountSetup, AppsUser, FinalizingSetup, Complete, Failed
On Event
Runs when a specific event type is emitted by the agent. Common event types:
enrollment_complete, enrollment_failed, app_install_failed, app_install_succeeded, phase_change
enrollment_complete or enrollment_failed to collect data "at the end" of enrollment.Each gather rule execution emits an event with the configured Output Event Type and Severity. The collected data is stored in the event's data field as key-value pairs. These events appear in the session timeline and can be inspected by Analyze Rules using the event_data condition source.
Data fields by collector type
Each collector type produces different data fields. When writing Analyze Rules, you reference these fields via dataField in event_data conditions.
| Collector | Data Fields |
|---|---|
| Registry | Value names as keys (e.g., DisplayName), or subkey_count + subkey_0, subkey_1, … |
| Event Log | Event properties as key-value pairs (varies by event) |
| WMI Query | WMI object properties as keys (e.g., Name, Status) |
| File | exists, path, size_bytes, content (if readContent is true) |
| Command | output (stdout), error_output (stderr), exit_code, command — raw text only, no parsed fields |
| Log Parser | Named capture groups from regex (e.g., appName, action) |
| JSON | Matched JSON values as structured key-value pairs |
| XML | Matched XML elements/attributes as key-value pairs |