Get-DbaInstanceAudit

Synopsis

Retrieves SQL Server audit objects from instance-level security auditing configurations.

Description

Retrieves all configured SQL Server audit objects at the instance level, which define where security audit events are stored and how they’re managed. These audits capture login attempts, permission changes, and other security-related activities across the entire SQL Server instance. The function returns detailed information including audit file paths, size limits, rollover settings, and current status, helping DBAs monitor compliance and troubleshoot security configurations without manually querying system views.

Syntax

Get-DbaInstanceAudit
    [-SqlInstance] <DbaInstanceParameter[]>
    [[-SqlCredential] <PSCredential>]
    [[-Audit] <String[]>]
    [[-ExcludeAudit] <String[]>]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Get-DbaInstanceAudit -SqlInstance localhost

Returns all Security Audits on the local default SQL Server instance

Example: 2

PS C:\> Get-DbaInstanceAudit -SqlInstance localhost, sql2016

Returns all Security Audits for the local and sql2016 SQL Server instances

Required Parameters

-SqlInstance

The target SQL Server instance or instances. This can be a collection and receive pipeline input to allow the function
to be executed against multiple SQL Server instances.

Optional Parameters

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-Audit

Specifies which audit objects to retrieve by name. Accepts multiple audit names to return only those specific audits.
Use this when you need to check configuration or status for particular audits instead of retrieving all instance-level audits.

-ExcludeAudit

Specifies which audit objects to exclude from results by name. Accepts multiple audit names to filter out unwanted audits.
Use this when you want to retrieve most audits but skip specific ones, such as excluding test or temporary audits from compliance reports.

-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.