New-XdrAdvancedHuntingFunction
SYNOPSIS
Creates a new Advanced Hunting function in Microsoft Defender XDR.
SYNTAX
New-XdrAdvancedHuntingFunction [-Name] <String> [-KQLQuery] <String> [[-Description] <String>] [-IsShared]
[[-FolderPath] <String>] [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]
DESCRIPTION
Creates a new saved function for Advanced Hunting queries in Microsoft Defender XDR. These functions can be reused across multiple hunting queries and detection rules. Functions can be shared with the organization or kept private in folder structures.
EXAMPLES
EXAMPLE 1
New-XdrAdvancedHuntingFunction -Name "GetSuspiciousLogons" -KQLQuery "DeviceLogonEvents | where LogonType == 'Network'" -IsShared
Creates a shared function that can be used across the organization.
EXAMPLE 2
New-XdrAdvancedHuntingFunction -Name "ExtendedEntraIdSignInEvents" -KQLQuery $query -Description "Combines XDR and Sentinel data" -IsShared
Creates a shared function with a description.
EXAMPLE 3
New-XdrAdvancedHuntingFunction -Name "MyFunction" -KQLQuery "DeviceEvents" -FolderPath "TestFolder/SubFolder"
Creates a private function in a folder structure.
EXAMPLE 4
$query = @"
EntraIdSignInEvents
| where RiskLevelAggregated > 50
| project Timestamp, AccountUpn, IPAddress
"@
New-XdrAdvancedHuntingFunction -Name "HighRiskSignIns" -KQLQuery $query -Description "Returns high-risk sign-ins" -IsShared
Creates a shared function with a multi-line query.
PARAMETERS
-Name
The name of the function. This will be used to call the function in queries.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-KQLQuery
The KQL (Kusto Query Language) body of the function. This is the query logic that will be executed when the function is called.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Description
Optional description of what the function does.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-IsShared
Switch to make the function shared with the organization. If not specified, the function will be private to the creator.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-FolderPath
Optional folder path for organizing private functions. Use forward slashes (/) or backslashes (\) - they will be automatically converted to double backslashes. Example: "MyFolder/SubFolder" or "MyFolder\SubFolder"
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-WhatIf
Shows what would happen if the cmdlet runs. The function is not created.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Confirm
Prompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
The ProgressAction parameter is a common parameter, not a cmdlet parameter. For more information, see about_CommonParameters.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
OUTPUTS
Object
Returns the created function object from the API including:
- Id: Unique identifier for the function
- Name: Function name
- Body: KQL query body
- Description: Function description
- Path: Folder path
- IsShared: Sharing status
- CreatedBy: Creator's UPN
- LastUpdatedBy: Last updater's UPN
- LastUpdateTime: Last update timestamp
- OutputColumns: Schema of the function output
NOTES
Functions can be called in queries using their name, e.g.: GetSuspiciousLogons() Shared functions are visible to all users in the organization. Private functions can be organized in folders for better management.