Using Search-UnifiedAuditLog in Powershell: All You Need To Know

When you're managing a large organization or handling sensitive data, keeping track of user activity across your Microsoft 365 environment is always necessary. Whether you're auditing for compliance, investigating a potential issue, or just trying to understand how your team's using different tools, the Search-UnifiedAuditLog cmdlet in PowerShell is an essential command.

However, using this cmdlet effectively can be a bit tricky if you're not familiar with PowerShell or the different parameters involved.

In this post, we’ll walk through how to use the Search-UnifiedAuditLog command, breaking down the key parameters and showing you how to run searches for specific user actions, operations and time frames.

What Is The Search-UnifiedAuditLog PowerShell Exchange Cmdlet?

The Search-UnifiedAuditLog command in PowerShell is used to search the unified audit log in Microsoft 365, which records actions and events from various services like Exchange Online, SharePoint, OneDrive, Microsoft Teams, and others. The cmdlet lets you filter and retrieve logs based on criteria such as date ranges, users, specific actions or objects.

Here we have the syntax of Search-UnifiedAuditLog, and, as always, it is really important to understand the meaning of each parameter.

• -EndDate: Sets the end of the date range for the search in UTC. -StartDate: Sets the start of the date range for the search in UTC.
• -Formatted: Converts numeric codes in the results into readable text. -FreeText: Filters results to entries containing a specific text string.
• -HighCompleteness: Prioritizes thoroughness over speed in the search results.
• -IPAddresses <String[]>: Filters results by specific IP addresses.
• -LongerRetentionEnabled: Reserved for future use; no current description available.
• -ObjectIds <String[]>: Filters results by specific object IDs, such as file URLs or user IDs.
• -Operations <String[]>: Filters results by specific actions performed, like "FileAccessed."
• -RecordType: Filters results by the type of event, such as SharePoint or Exchange actions.
• -ResultSize: Limits the number of results returned in a single query, up to 5,000.
• -SessionCommand: Defines how results are paginated or retrieved for large queries.
• -SessionId: Sets an identifier to group multiple paginated queries together.
• -SiteIds <String[]>: Filters results by SharePoint site identifiers (GUIDs).
• -UserIds <String[]>: Filters results by the accounts of users who performed the actions.

What Can You Use Search-UnifiedAuditLog For?

Let’s take a quick look at three practical ways to use the Search-UnifiedAuditLog command:

1. Tracking Security Incidents: The unified audit log is your friend when investigating suspicious activity. For example, if there’s an alert about unusual login attempts, you can use this command to quickly search for login events tied to a specific IP address or user.
2. Auditing Admin Changes: Ever wonder who made a critical change to your Exchange Online environment? With the Search-UnifiedAuditLog command, you can pull up detailed logs of admin actions, like mailbox changes or permission updates.
3. Ensuring Compliance: If your organization needs to prove compliance with regulations, this command simplifies the process. For example, you may need to confirm who accessed a specific document in SharePoint last week. By specifying the document’s URL, you can generate a precise audit trail in minutes, making compliance reporting easier for everyone.

Prerequisites to Run Search-UnifiedAuditLog in PowerShell

To use the Search-UnifiedAuditLog command, there are a few key prerequisites you need to meet:

Exchange Online Environment: This command is only available in Exchange Online. If you’re using an on-premises version of Exchange, it won’t work. According to Microsoft, it’s designed specifically for organizations using Microsoft 365 services like Exchange Online, SharePoint Online, and OneDrive for Business.

Appropriate Permissions: You need to have the right permissions assigned to your account. For example, roles like "View-Only Audit Logs" or "Audit Logs" in the Microsoft Purview compliance portal are required. Without these permissions, you won’t be able to access the unified audit log or run the command.

Unified Auditing Enabled: Unified auditing must be turned on for your organization. In most cases, this is enabled by default for Microsoft 365 tenants, but if it’s been disabled, the command won’t return results.

Understanding UTC for Dates: When using the StartDate and EndDate parameters, you need to provide the date and time in UTC. If you use local time, you’ll need to convert it to UTC using PowerShell functions like ToUniversalTime() to ensure accurate results.

How to Use Search-UnifiedAuditLog Step-by-Step

Now, let’s explore the best way to use Search-UnifiedAuditLog in a few quick steps.

Step 1: Connect to Exchange Online PowerShell

First, before you can run any audit log searches, you need to establish a connection to your Exchange Online session. Open your PowerShell window and use the Connect-ExchangeOnline command to authenticate with your Office 365 account.

Make sure you are using your admin credentials. For example, to connect with your admin account [email protected], run the following command:

Step 2: Determine the Parameters You Need for the Search

Before running the search, figure out what you are looking for in the audit logs. The Search-UnifiedAuditLog command has a variety of parameters that allow you to filter results based on what is relevant to your search.

For example, you can filter by the start and end date, specific user activity, or the type of operation. That’s why it’s really important to understand the meaning of each parameter before running this PowerShell cmdlet.

Step 3: Define the Date Range for the Search

Use the -StartDate and -EndDate parameters to specify the period for which you want to search the audit logs. Make sure the dates are in UTC format.

For example, to search for activity between March 1, 2024 and March 2, 2024, you would define the date range like this:

This ensures that the logs only reflect the activity within these exact times.

Step 4: Choose Specific Users for the Search

The -UserIds parameter allows you to narrow your search by specific users. If you are looking for activity performed by James Smith, use his email address in the -UserIds parameter like this:

Step 5: Specify the Type of Operations to Track

The -Operations parameter helps you focus on specific actions that were performed during the search period. For example, you might want to track file accesses or message reads. To look for file access events, you could use:

Step 6: Set the Record Type for the Search

The -RecordType parameter helps you filter the search based on the type of activity you’re tracking. Some record types include SharePoint, OneDrive, or Exchange mail activities. If you're interested in SharePoint file activity, you would use:

Step 7: Run the Search-UnifiedAuditLog Command

Now that you've defined all your parameters, it’s time to execute the command. An example command to search for file access by James Smith between March 1 and March 2, 2024, would look like this:

This will retrieve the relevant audit log entries for James Smith accessing SharePoint files within the specified time frame.

Step 8: Review and Interpret the Results

Once the command is executed, PowerShell will return the audit log results based on your defined parameters. The information you’ll see on the screen can be interpreted like this:

• CreationDate: The timestamp of the event.
• UserIds: The user who performed the action.
• Operations: The action taken (e.g., "FileAccessed").
• ObjectIds: The target object, such as a file or URL.

These results can be exported as a CSV file if you need to. Keep in mind that if you don’t see any results, ensure your parameters are correct and adjust as needed.The Search-UnifiedAuditLog cmdlet is a handy tool for tracking and auditing activity across Microsoft 365. By understanding how to use its parameters, you can gather valuable insights for security, compliance and day-to-day operations.