XDR ReferenceSchema and PowerShell tools
← All XDRInternals commands

POWERSHELL COMMAND

Get-XdrEndpointConfigurationCustomCollectionRule

Retrieves custom collection rules for Microsoft Defender for Endpoint.

View source ↗

Gets the custom collection rules configured for Microsoft Defender for Endpoint. Custom collection rules allow you to collect specific file, registry, process, and network events based on defined criteria to support advanced hunting and detection scenarios. This function includes caching support with a 30-minute TTL to reduce API calls.

It incorporates the same YAML schema as used by Telemetry Collection Manager https://github.com/FalconForceTeam/TelemetryCollectionManager for easy export and version control of custom collection rules.

Syntax

Get-XdrEndpointConfigurationCustomCollectionRule [[-Output] <string>] [-Force] [<CommonParameters>]

Parameters

-Output

Property Value
Type String
Required No
Position 1
Pipeline input No
Default PSObject

Specifies the output format. Valid values are ‘PSObject’ (default) and ‘YAML’.

  • PSObject: Returns PowerShell objects
  • YAML: Returns rules formatted as YAML text for easy export and version control

-Force

Property Value
Type SwitchParameter
Required No
Position named
Pipeline input No
Default False

Bypasses the cache and forces a fresh retrieval from the API.

Examples

Get-XdrEndpointConfigurationCustomCollectionRule
Retrieves all custom collection rules using cached data if available.

Get-XdrEndpointConfigurationCustomCollectionRule -Force
Forces a fresh retrieval of custom collection rules, bypassing the cache.

Get-XdrEndpointConfigurationCustomCollectionRule | Where-Object { $_.isEnabled -eq $true }
Retrieves only enabled custom collection rules.

Get-XdrEndpointConfigurationCustomCollectionRule |
    Where-Object { $_.table -eq "DeviceFileEvents" } |
    Format-Table ruleName, actionType, platform, isEnabled -AutoSize
Retrieves custom collection rules for file events and displays them in a table.

$rules = Get-XdrEndpointConfigurationCustomCollectionRule
$rules | Where-Object { $_.createdBy -eq "admin@contoso.com" }
Retrieves all rules created by a specific user.

Get-XdrEndpointConfigurationCustomCollectionRule |
    Select-Object ruleName, table, actionType, scope, isEnabled
Retrieves custom collection rules and displays key properties.

Get-XdrEndpointConfigurationCustomCollectionRule -Output YAML
Retrieves custom collection rules in YAML format for export.
YAML format is intended to use with https://github.com/FalconForceTeam/TelemetryCollectionManager

Get-XdrEndpointConfigurationCustomCollectionRule -Output YAML | Out-File "rules.yaml"
Exports all custom collection rules to a YAML file.

Output

Type: Object[] or String

When Output is ‘PSObject’ (default): Returns an array of custom collection rule objects. When Output is ‘YAML’: Returns a string containing YAML-formatted rules. When Output is ‘PSObject’ (default): Returns an array of custom collection rule objects containing:

  • ruleId: Unique identifier for the rule (GUID)
  • ruleName: Name of the collection rule
  • ruleDescription: Description of the rule
  • scope: Rule scope (e.g., “Organization”)
  • isEnabled: Boolean indicating if the rule is active
  • table: Target table (e.g., DeviceFileEvents, DeviceNetworkEvents)
  • actionType: Event type to collect (e.g., FileDeleted, ConnectionSuccess)
  • createdBy: User who created the rule
  • creationDateTimeUtc: Creation timestamp
  • lastModifiedBy: User who last modified the rule
  • lastModificationDateTimeUtc: Last modification timestamp
  • platform: Target platform (e.g., Windows, Linux, macOS)
  • filters: Filter criteria for the collection rule
  • version: Rule version number
  • updateKey: Optimistic concurrency control key

View source