Gather Rules
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.
Collector Types
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).
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.
C:\Windows\Panther\UnattendGC\setupact.logParameters
readContent— Set totrueto 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
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 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
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) ortext. 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
Trigger Types
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.Output
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.
Autopilot Monitor v1.0.0