Read-DbaAuditFile

Synopsis

Parses SQL Server audit files (.sqlaudit) into structured event data for security analysis and compliance reporting.

Description

Reads and parses SQL Server audit files (.sqlaudit) created by SQL Server Audit functionality, converting binary audit data into readable PowerShell objects. Each audit event is returned with its timestamp, event details, fields, and actions in a structured format that’s easy to filter, export, or analyze. This is essential for security investigations, compliance reporting, and monitoring database access patterns since SQL Server audit files are stored in a proprietary binary format that can’t be read directly. Works with local files, UNC paths, or can be piped from Get-DbaInstanceAudit to automatically locate and read audit files from remote instances.

Syntax

Read-DbaAuditFile
    [-Path] <Object[]>
    [-Raw]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Read-DbaAuditFile -Path C:\temp\logins.sqlaudit

Returns events from C:\temp\logins.sqlaudit.

Example: 2

PS C:\> Get-ChildItem C:\temp\audit\*.sqlaudit | Read-DbaAuditFile

Returns events from all .sqlaudit files in C:\temp\audit.

Example: 3

PS C:\> Get-DbaInstanceAudit -SqlInstance sql2014 -Audit LoginTracker | Read-DbaAuditFile

Reads remote Audit details by accessing the file over the admin UNC share.

Required Parameters

-Path

Specifies the path to SQL Server audit files (.sqlaudit) to read and parse. Accepts file paths, FileInfo objects from Get-ChildItem, or Audit objects from Get-DbaInstanceAudit.
Supports UNC paths for reading remote files and automatically expands wildcards to process multiple related audit files. Use this when you need to analyze audit data from specific files or when
piping from other dbatools audit commands.

Optional Parameters

-Raw

Returns the unprocessed enumeration object instead of structured PowerShell objects.
Use this when you need access to the raw audit data structure for custom processing or when working with audit parsing tools that expect the native format.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.