Search-UnifiedAuditLogCustom

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] <int>] [[-ChunkDays] <int>] [-SimpleView] [-HelperGUI]

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.

PARAMETERS

-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: System.Int32
DefaultValue: 7
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 6
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-EndDate

The end date and time for the audit log search. If not specified, defaults to the current date and time.

Type: System.DateTime
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-FreeText

A free text string to search for within the audit log records.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 4
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-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: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-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: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ResultSize

The maximum number of results to return from the search. Defaults to 5000.

Type: System.Int32
DefaultValue: 5000
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 5
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-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: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases:
- Simple
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-StartDate

The start date and time for the audit log search. If not specified, defaults to 24 hours ago.

Type: System.DateTime
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-UserIds

An array of user identifiers (e.g., email addresses) to filter the search results by specific users.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

NOTES

Not documented.

Getting started

Azure

Entra

Exchange

Intune

M365 Apps

Misc

MS Commerce

Share Point

Unified Logs

Search-UnifiedAuditLogCustom

Search-UnifiedAuditLogCustom

SYNOPSIS

SYNTAX

DESCRIPTION

EXAMPLES

EXAMPLE 1

PARAMETERS

-ChunkDays

-EndDate

-FreeText

-HelperGUI

-Operations

-ResultSize

-SimpleView

-StartDate

-UserIds

CommonParameters

INPUTS

OUTPUTS

NOTES

​Search-UnifiedAuditLogCustom

​SYNOPSIS

​SYNTAX

​DESCRIPTION

​EXAMPLES

​EXAMPLE 1

​PARAMETERS

​-ChunkDays

​-EndDate

​-FreeText

​-HelperGUI

​-Operations

​-ResultSize

​-SimpleView

​-StartDate

​-UserIds

​CommonParameters

​INPUTS

​OUTPUTS

​NOTES

​RELATED LINKS

Search-UnifiedAuditLogCustom

SYNOPSIS

SYNTAX

DESCRIPTION

EXAMPLES

EXAMPLE 1

PARAMETERS

-ChunkDays

-EndDate

-FreeText

-HelperGUI

-Operations

-ResultSize

-SimpleView

-StartDate

-UserIds

CommonParameters

INPUTS

OUTPUTS

NOTES

RELATED LINKS