Skip to main content

​
SYNOPSIS

Search-UnifiedAuditLogCustom is an enhanced wrapper around the native Search-UnifiedAuditLog cmdlet, providing additional features such as a user-friendly GUI for constructing search queries, simplified output formatting, and integration with the Microsoft 365 audit operations catalog.

​
SYNTAX

Search-UnifiedAuditLogCustom [[-StartDate] <DateTime>] [[-EndDate] <DateTime>] [[-Operations] <String[]>]
 [[-UserIds] <String[]>] [[-FreeText] <String>] [[-ResultSize] <Int32>] [-SimpleView] [-HelperGUI]
 [[-ChunkDays] <Int32>] [-ProgressAction <ActionPreference>] [<CommonParameters>]

​
DESCRIPTION

This function allows administrators and security professionals to perform more efficient and targeted searches of the Microsoft 365 Unified Audit Log. It includes a helper GUI that enables users to easily select operations from the official Microsoft Learn catalog, specify date ranges, user filters, and other parameters without needing to remember complex cmdlet syntax. The output can be returned in a simplified format that flattens nested JSON structures for easier analysis and export. This is particularly useful for security investigations, compliance audits, and general monitoring of activities across Microsoft 365 services.

​
EXAMPLES

​
EXAMPLE 1

Search-UnifiedAuditLogCustom -StartDate (Get-Date).AddDays(-7) -EndDate (Get-Date) -Operations "UserLoggedIn", "FileAccessed" -SimpleView
This example searches the Unified Audit Log for “UserLoggedIn” and “FileAccessed” operations that occurred in the last 7 days, and returns the results in a simplified format.

​
EXAMPLE 2

​
PARAMETERS

​
-StartDate

The start date and time for the audit log search. If not specified, defaults to 24 hours ago. 
Type: DateTime
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-EndDate

The end date and time for the audit log search. If not specified, defaults to the current date and time. 
Type: DateTime
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-Operations

An array of operation names to filter the search. These can be selected from the helper GUI, which loads the catalog of operations from Microsoft Learn. Users can also enter raw cmdlet names (e.g., New-TransportRule) to filter by specific operations. 
Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-UserIds

An array of user identifiers (e.g., email addresses) to filter the search results by specific users. 
Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-FreeText

A free text string to search for within the audit log records. 
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-ResultSize

The maximum number of results to return from the search. Defaults to 5000. 
Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: 5000
Accept pipeline input: False
Accept wildcard characters: False

​
-SimpleView

When specified, the output will be processed to flatten nested JSON structures into a simpler format. This is ideal for exporting to CSV or performing quick analysis without dealing with complex nested properties. 
Type: SwitchParameter
Parameter Sets: (All)
Aliases: Simple

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

​
-HelperGUI

When specified, opens a graphical user interface to assist in constructing the search query with user-friendly controls and operation selection. The operations list is populated from the Microsoft Learn catalog of audit log activities, allowing users to easily find and select relevant operations for their search. Make sure to have access to the Microsoft Learn page for audit log activities to load the operations catalog successfully (https://learn.microsoft.com/en-us/purview/audit-log-activities). 
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

​
-ChunkDays

Size (in days) of each sub-window used to split the StartDate/EndDate range. Defaults to 7. The function loops over the full range one chunk at a time and uses session pagination inside each chunk, which avoids the server-side ‘Search duration too long’ error encountered on very wide windows. Lower this value (e.g. 1 or 3) if a chunk itself returns the ‘too long’ error. 
Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 7
Default value: 7
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

​
NOTES