Change Auditor 7.5 - User Guide

Managing SQL Extended Events Auditing (Preview)

Managing SQL Extended Events Auditing (Preview)

SQL Server Extended Events allow users to gather information on the performance of their SQL database. These commands allow you to create and manage SQL Extended Events auditing templates for auditing SQL Extended Events.

NOTE:   • A Change Auditor SQL Server license is required for SQL Extended Events auditing. • Managing SQL Extended Events auditing templates is only available to Change Auditor administrators or users that hold a custom Change Auditor role that includes the View_SQL_Template operation. • The specified SQL login account must have the following SQL Server permissions: ▪ Alter any event session ▪ View server state ▪ Connect SQL ▪ View any database Alternatively, the account must have an SQL Server role that contains these permissions, for example 'Sysadmin'. • If using Windows authentication for the SQL Login account, and the specified agent for the auditing template is not installed on the target SQL server, the agent host computer account must also be added to the SQL Security Logins on the target SQL server with the same permissions requirement as the specified SQL login account for the auditing template. • If using Windows authentication for the SQL Login account, and the agent for the auditing template is installed on the target SQL server, the local computer ‘NT AUTHORITY\SYSTEM' account must be added to the SQL Security Logins on the target SQL server with the View Server State permission granted.

•	Get-CASQLExtendedEventsInfo

•	New-CASQLExtendedEventsFilter

•	New-CASQLExtendedEventsObject

•	New-CASQLExtendedEventsTemplate

•	Get-CASQLExtendedEventsTemplates

•	Remove-CASQLExtendedEventsTemplate

Get-CASQLExtendedEventsInfo

Use this command to retrieve the list of event names and filters available from the SQL server to use when configuring the SQL Extended Events template. Change Auditor audits event information from the Admin, Operational, and Analytic channels.

Table 56. Parameter description

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-SQLServerName	The name or IP of the SQL Server and the instance name if a named instance. For example, SQLTestServer\InstanceName.
-SQLServerLoginCredential	The SQL server credentials used to retrieve the list of available events and filters from the SQL server.

Example: Get all available SQL Extended Events event names and filters (predicates) available from the SQL Server.

Get-CASQLExtendedEventsInfo –Connection $connection -SQLServerName $sqlservername -SQLServerLoginCredential $dbcredential

New-CASQLExtendedEventsFilter

Use this command to specify a filter for the SQL Extended Events to audit when creating templates.

Table 57. Parameter description

Parameter	Description
-EventsInfo	The available event and filter information obtained using the Get-CASQLExtendedEventsInfo command.
-FieldName	The field on which to filter.
-Operator	The operator to be used for comparison. See the output obtained from the Get-CASQLExtendedEventsInfo command for available operators for the specified filter field.
-Value	The value to be used for comparison.
-FilterType	The type of filter AND or OR.

Example: Filter on a specified field and value.

New-CASQLExtendedEventsFilter -EventsInfo $eventsInfo -FieldName database_name -Operator Equals -Value testdb1 -FilterType 'AND'

New-CASQLExtendedEventsObject

Use this command to specify the SQL Extended Events to audit.

Table 58. Parameter description

Parameter	Description
-EventsInfo	The available event and filter information obtained using thee Get-CASQLExtendedEventsInfo command.
-EventNames	A string array of event names to be included.
-EventPackages	A string array of event packages to be applied for the specified array of event names when the object is created. The array values for parameters -EventNames and -EventPackages must be the same length as each index element of each array is paired with one another. You can specify an empty value for the default package.

Example: Populate a SQL Extended Events audited event name list

New-CASQLExtendedEventsObject -EventsInfo $sqlExtendedEventClasses -EventNames "login_event","database_stopped","error_reported" -EventPackages "sqlserver","sqlserver","xesvlpkg"

New-CASQLExtendedEventsTemplate

Use this command to create SQL Extended Events auditing templates.

Table 59. Parameter description

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-SQLServerName	The name or IP of the SQL Server and the instance name if a named instance. For example, SQLTestServer\InstanceName.
-SQLServerLogonCredential	The SQL server logon credential. NOTE:   • Both SQL and Windows authentication are supported. • If using Windows authentication for the SQL Login account, and the specified agent for the auditing template is not installed on the target SQL server, the agent host computer account must also be added to the SQL Security Logins on the target SQL server with the same permissions requirement as the specified SQL login account for the auditing template. • If using Windows authentication for the SQL Login account, and the agent for the auditing template is installed on the target SQL server, the local computer ‘NT AUTHORITY\SYSTEM' account must be added to the SQL Security Logins on the target SQL server with the View Server State permission granted.
-Name	A unique name for the template.
-ExtendedEvents	The list of events to audit using New-CASQLExtendedEventsObject.
-Filters (Optional)	A list of event filters using New-CASQLExtendedEventsFilter.
-MaxMemorySize (Optional)	SQL Extended Events maximum memory size in megabytes. Minimum is 250 MB (default if parameter not specified).
-Disabled (Optional)	Set to determine if the template is enabled or disabled. By default this is set to False.
-AgentInfo (Optional)	An agent object obtained using the Get-CAAgents command. If not specified, it will expect an agent installed on the SQL server to be audited. The agent is used for SQL Extended Events session management and event auditing.

Example: New SQL Extended Events template

New-CASQLExtendedEventsTemplate -Connection $connection -AgentInfo $Agent -SQLServerName $sqlServerName -SQLServerLoginCredential $sqlCredential -Name 'testXEventTemplate' -ExtendedEvents $events -Filters $filters

Get-CASQLExtendedEventsTemplates

Use this command to see all the SQL Extended Events templates that have been created.

Table 60. Parameter description

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Get all the SQL Extended Events templates

Get-CASqlExtendedEventsTemplates -Connection $connection

Example: Get SQL Extended Events templates filtered by a specified name

Get-CASqlExtendedEventsTemplates -Connection $connection | Filter.Where(_$.name = "MyTemplate")

Remove-CASQLExtendedEventsTemplate

Use this command to delete a specified SQL Extended Events template.

Table 61. Parameter description

Parameter	Description
-Connection	A connection obtained by using Connect-CAClient.
-Template	The template object obtained using Get-CASQLExtendedEventsTemplates.

Example: Remove all the SQL Extended Events templates

Remove-CASQLExtendedEventsTemplate -Connection $connection -Template $template

Managing Microsoft Entra ID auditing

Managing Microsoft Entra ID auditing

Change Auditor audits activity in the Microsoft Entra admin center that corresponds to the events in the Microsoft Entra ID auditing logs and sign-in activity. Managing Microsoft Entra ID auditing is available through the following PowerShell commands:

•	New-CAAzureADTemplate

•	Get-CAAzureADTemplates

•	Set-CAAzureADTemplate

NOTE: When you delete a template (see Remove-CAAgentTemplate), the web application created in Microsoft Entra ID remains. You can delete the web application using the Microsoft Entra admin center. If you do not have the portal, see https://technet.microsoft.com/en-us/library/dn832618.aspx for instructions.

NOTE: If your organization uses a proxy server to connect to the internet, you must configure the agent settings to audit Microsoft Entra ID and Microsoft 365 targets. (See Set-CAConfiguration)

The following sample scripts are available in the Change Auditor client folder. By default they are located here: C:\Program Files\Quest\ChangeAuditor\Client\PowerShell Sample Scripts:

•	CreateAzureADTemplate

•	CreateAzureADTemplateUsingWebAppKey

•	RemoveAzureADTemplate

•	DisableAzureADTemplate

•	ModifyAzureADTemplate-ChangeAgent

•	GetAzureADTemplates

 

New-CAAzureADTemplate

Use this command to create a template for auditing Microsoft Entra ID.

Table 62. Available parameters

Parameter	Description
-AgentInfo	An agent object obtained using the Get-CAAgents command. The agent is used for Microsoft Entra ID auditing. NOTE: The agent must be allowed to connect to Microsoft Entra ID. • If the agent is separated from the coordinator by a firewall, you must create a firewall exception for port 8373 on every agent computer to be used for Microsoft Entra ID auditing. This is the default port that enables the coordinator to communicate with the agent. A different port number can, however, be specified by running the Set-CAConfiguration command. • A firewall outbound exception for remote port 443 (https) must exist for every agent computer that will be used for Microsoft Entra ID auditing. This is the port that is used for communicating with the tenant.
-Connection	A connection obtained by using the Connect-CAClient command.
-CreateWebApp (Optional)	Specifies that you want to create a new web application. You will need to login to register Change Auditor in the tenant and ensure the required consent has been granted. Note: Internet access is required. The Microsoft sign-in page opens automatically. To grant permission for all administrators to create a web application: 1 Select an account with the Global Administrator role. 2 Enter the required password, and select Sign in. 3 Review the required permissions for the Change Auditor Configuration Assistant on the Microsoft Entra ID consent page. (Consent is only required once per tenant. You may, however, be prompted to enter your log on credentials when creating a new web application.) To apply the consent to all the users in your organization, click to enable Consent on behalf of your organization and click Accept. To apply the consent for just the current signed-in user simply click Accept. NOTE: When you specify this parameter a new web application is created and assigned to the template.
-DeploymentType	Specifies the tenant type (Commercial, GCC, or GCCHigh). If not set, the default is Commercial.
-Tenant	The Microsoft Entra tenant/directory that you want to audit (for example: yourTenantName.onmicrosoft.com).
-AuditLogs	Specifies whether or not to audit the Microsoft Entra ID audit logs. You must enable at least one type of activity to audit using the - AuditLogs or -SignIns parameter.
-SignIns	Specifies whether or not to audit Microsoft Entra sign-in activity. You must enable at least one type of activity to audit using the - AuditLogs or -SignIns parameter.
-HistoricalEventCollectionHours (Optional)	Specifies how many hours the agent should go back in time to start event collection. The parameter accepts values from 1 to 720. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionDays parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected.
-HistoricalEventCollectionDays (Optional)	Specifies how many days the agent should go back in time to start event collection. The parameter accepts values from 1 to 30. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionHours parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected.
-Disabled (Optional)	Specifies whether auditing is enabled or disabled for Microsoft Entra ID.

Example: Creating Microsoft Entra ID auditing template that will collect events generated 30 days in the past.

$connection = Connect-CAClient –InstallationName ‘Default'

$agent = Get-CAAgents –Connection $connection | where{$_.agentfqdn -like "CAAGENT.DOMAIN.COM"} *Keep in Uppercase

New-CAAzureADTemplate -Connection $connection -CreateWebApp -Tenant $tenant
-AgentInfo $agent –HistoricalEventCollectionDays 30 -SignIns $True -AuditLogs $True

Create a template using an existing web application

Alternatively, use these parameters if you are using a pre-created web application that Change Auditor will use for authentication.

For details on integrating applications with Microsoft Entra ID and creating a web application, consult the Microsoft documentation. When creating a web application in the Microsoft Entra admin center, you are required to provide the following URLs: Sign-On URL, App ID URL. Specify any URL address that is unique to your tenant (for example: http://ChangeAuditorApp) for each of them.

The following permissions must be assigned to the web application:

Table 63. Required permission

System	Permissions
Office 365 Management APIs	Application Permissions: • ActivityFeed.Read – Application - Read activity data for your organization
Microsoft Graph	Application Permissions: • AuditLog.Read.All – Application - Read all audit log data • Directory.Read.All – Application - Read directory data • IdentityRiskEvent.Read.All – Application - Read all identity risk information

Once the required permissions are applied, click Grant admin consent for… and confirm with Yes.

Table 64. Available parameters

Parameter	Description
-AgentInfo	An agent object obtained using the Get-CAAgents command. The agent will be used for Microsoft Entra ID auditing. NOTE: The agent must be allowed to connect to Microsoft Entra ID. • If the agent is separated from the coordinator by a firewall, you must create a firewall exception for port 8373 on every agent computer to be used for Microsoft Entra ID auditing. This is the default port that enables the coordinator to communicate with the agent. A different port number can, however, be specified by running the Set-CAConfiguration command. • A firewall outbound exception for remote port 443 (https) must exist for every agent computer that will be used for Microsoft Entra ID auditing. This is the port that is used for communicating with the tenant.
-Connection	A connection obtained by using the Connect-CAClient command.
-DeploymentType	Specifies the tenant type (Commercial, GCC, or GCCHigh). If not set, the default is Commercial.
-Tenant	The Microsoft Entra tenant/directory that you want to audit (for example: yourTenantName.onmicrosoft.com).
-AuditLogs	Specifies whether or not to audit the Microsoft Entra ID audit logs. You must enable at least one type of activity to audit using the - AuditLogs or -SignIns parameter.
-SignIns	Specifies whether or not to audit Microsoft Entra sign-in activity. You must enable at least one type of activity to audit using the - AuditLogs or -SignIns parameter.
-WebAppId	A web application ID. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant. NOTE: Microsoft Entra ID and Microsoft 365 must each have their own dedicated web application.
-WebAppKey	The key assigned to the web application specified for the WebAppId parameter. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant. NOTE: When using this parameter, you cannot also specify –WebAppCreationCredential parameter.
-HistoricalEventCollectionHours (Optional)	Specifies how many hours the agent should go back in time to start event collection. The parameter accepts values from 1 to 720. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionDays parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected.
-HistoricalEventCollectionDays (Optional)	Specifies how many days the agent should go back in time to start event collection. The parameter accepts values from 1 to 30. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionHours parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected.
-Disabled (Optional)	Specifies whether auditing is enabled or disabled for Microsoft Entra ID.

Example: Creating an Microsoft Entra ID auditing template using a pre-created web application that will collect events generated 30 days in the past.

New-CAAzureADTemplate -Connection $connection -AgentInfo $agent -WebAppKey $webAppKey -WebAppId $webAppId -Tenant $tenant –HistoricalEventCollectionDays 30
-SignIns $True -AuditLogs $True

Set-CAAzureADTemplate

Use this command to edit the web application key and ID, and the agent in an existing Microsoft Entra ID template. This also allows you to replace an expired or revoked web application.

NOTE:   • You cannot edit the type of activity to audit (audit logs and/or sign-ins) and the WebAppId, WebApp Key, and agent at the same time. Activity must be edited in a separate command.

Table 65. Available parameters

Parameter	Description
-AgentInfo	An agent object obtained using the Get-CAAgents command. The agent will be used for Microsoft Entra ID auditing. NOTE: The agent must be allowed to connect to Microsoft Entra ID. • If the agent is separated from the coordinator by a firewall, you must create a firewall exception for port 8373 on every agent computer to be used for Microsoft Entra ID auditing. This is the default port that enables the coordinator to communicate with the agent. A different port number can, however, be specified by running the Set-CAConfiguration command. • A firewall outbound exception for remote port 443 (https) must exist for every agent computer that will be used for Microsoft Entra ID auditing. This is the port that is used for communicating with the tenant. NOTE: The web application ID and key values are encrypted; therefore, each time you change the agent associated with a template you must explicitly specify the values again.
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	A template object obtained by the Get-CAAzureADTemplates command.
-CreateWebApp (Optional)	Specifies that you want to create a new web application. You will need to login to register Change Auditor in the tenant and ensure the required consent has been granted. Note: Internet access is required. The Microsoft sign-in page opens automatically. To grant permission for all administrators to create a web application: 1 Select an account with the Global Administrator role. 2 Enter the required password, and select Sign in. 3 Review the required permissions for the Change Auditor Configuration Assistant on the Microsoft consent page. (Consent is only required once per tenant. You may, however, be prompted to enter your log on credentials when creating a new web application.) To apply the consent to all the users in your organization, click to enable Consent on behalf of your organization and click Accept. To apply the consent for just the current signed-in user simply click Accept. NOTE: When you specify this parameter a new web application is created and assigned to the template.
-AuditLogs	Specifies whether or not to audit the Microsoft Entra ID audit logs. You must enable at least one type of activity to audit using the - AuditLogs or -SignIns parameter.
-SignIns	Specifies whether or not to audit Microsoft Entra sign-in activity. You must enable at least one type of activity to audit using the - AuditLogs or -SignIns parameter.
-WebAppId	A web application ID. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant. NOTE: Microsoft Entra ID and Microsoft 365 must each have their own dedicated web application.
-WebAppKey	The key assigned to the web application specified for the WebAppId parameter. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant.

Example: Modify web application credentials in an auditing template

Set-CAAzureADTemplate -Connection $connection -Template $template -WebAppKey $webAppKey -WebAppId $webAppId

Example: Add auditing of all activities to an existing template

Set-CAAzureADTemplate -Connection $connection -Template $template -SignIns $True
-AuditLogs $True

Get-CAAzureADTemplates

Use this command to see all the Microsoft Entra ID templates available within your installation.

Table 66. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Get a list of all Microsoft Entra ID templates

Get-CAAzureADTemplates -Connection $connection

Managing Office 365 auditing

Managing Office 365 auditing

Change Auditor for Exchange and Change Auditor for SharePoint have been extended to include the auditing of activities taking place in Exchange Online, SharePoint Online, and OneDrive for Business. The following commands are available to manage Office 365 auditing:

•	New-CAO365Template

•	Set-CAO365Template

•	Get-CAO365Templates

•	Remove-CAO365Template

•	Get-CAO365ExchangeMailboxes

•	Add-CAO365ExchangeTemplateMailboxes

•	Remove-CAO365ExchangeTemplateMailboxes

•	Get-CAO365ExchangeTemplateMailboxes

NOTE: When you delete a template (see Remove-CAAgentTemplate), the web application created in Microsoft Entra ID remains. You can delete the web application using the Microsoft Entra admin center. If you do not have the portal, see https://technet.microsoft.com/en-us/library/dn832618.aspx for instructions.

NOTE: If your organization uses a proxy server to connect to the internet, you must configure the agent settings to audit Microsoft Entra ID and Microsoft 365 targets. (See Set-CAConfiguration)

New-CAO365Template

Use this command to create a template for auditing Office 365 Exchange Online, SharePoint Online, and OneDrive for Business.

Table 67. Available parameters

 

Parameter	Description
-AgentInfo	An agent obtained by using the Get-CAAgents command. NOTE: The agent must be able to connect to Microsoft Entra ID. • If the agent is separated from the coordinator by a firewall, you must create a firewall exception for port 8373 on every agent computer to be used for Office 365 auditing. This is the default port that enables the coordinator to communicate with the agent. A different port number can, however, be specified by running the Set-CAConfiguration command. • A firewall outbound exception for remote port 443 (https) must exist for every agent computer that will be used for Office 365 auditing. This is the port that is used for communicating with the tenant.
-Connection	A connection obtained by using the Connect-CAClient command.
-CreateWebApp (Optional)	Specifies that you want to create a new web application. You will need to login to register Change Auditor in the tenant and ensure the required consent has been granted. Note: Internet access is required. The Microsoft sign-in page opens automatically. To grant permission for all administrators to create a web application: 1 Provide an account with the Global Administrator role. 2 Enter the required password, and select Sign in. 3 Review the required permissions for the Change Auditor Configuration Assistant on the Microsoft consent page. (Consent is only required once per tenant. You may, however, be prompted to enter your log on credentials when creating a new web application.) To apply the consent to all the users in your organization, click to enable Consent on behalf of your organization and click Accept. To apply the consent for just the current signed-in user simply click Accept. NOTE: When you specify this parameter a new web application is created and assigned to the template.
-DeploymentType	Specifies the tenant type (Commercial, GCC, or GCCHigh). If not set, the default is Commercial.
-Tenant	The Microsoft Entra tenant/directory that you want to audit (for example: yourTenantName.onmicrosoft.com).
-AuditAdministration (Optional)	Specifies whether to audit administration events.
-AuditOrganization (Optional)	Specifies whether to audit all Exchange Online mailboxes accessed by users other than the mailbox owner.
-CertificateFile (Optional)	The filename of an exported X509 certificate with private key. NOTE: This parameter is not required if the -CertificateThumbprint or -GenerateCertificate parameter is specified.
-CertificateFilePassword (Optional)	The password for the certificate file. NOTE:   • If the -CertificateFile parameter is not specified this parameter is ignored. • If the -CertificateFile parameter is specified this parameter is required. The private key must be protected by password. Protection with security principal is not supported.
-CertificateThumbprint (Optional)	The thumbprint of a certificate that is located in the user's personal certificate store on the host workstation and must have a private key (string format). NOTE:   • The private key must be marked as exportable. • This parameter is not required if the -CertificateFile or -GenerateCertificate parameter is specified.
-GenerateCertificate (Optional)	If specified, will generate a new self-signed certificate.
-Disabled (Optional)	Specifies whether the auditing template is enabled or disabled.
-EnableExchangeOnline (Optional)	Specifies whether Exchange Online auditing is enabled or disabled.
-EnableOneDrive (Optional)	Specifies whether OneDrive for Business auditing is enabled or disabled.
-EnableSharePoint (Optional)	Specifies whether SharePoint Online auditing is enabled or disabled.
-HistoricalEventCollectionHours (Optional)	Specifies how many hours the agent should go back in time to start event collection. The parameter accepts values from 1 to 168. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionDays parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected. NOTE: The historical data returned is based on the information in the Office 365 audit logs. This may not reflect the configuration options in the current template.
-HistoricalEventCollectionDays (Optional)	Specifies how many days the agent should go back in time to start event collection. The parameter accepts values from 1 to 7. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionHours parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected. NOTE: The historical data returned is based on the information in the Office 365 audit logs. This may not reflect the configuration options in the current template.
-ExcludedOperations (Optional)	String that specifies events to exclude from the Office 365 OneDrive for Business event, Office 365 SharePoint Online event, and Office 365 Exchange Online event. These generic dynamically constructed events are created when associated activity is detected that does not have a corresponding event defined in Change Auditor.
-OverwriteTenantMailboxAuditing (Optional)	Specifies whether the template auditing settings will overwrite the existing tenant auditing settings.

Example: Create a template that audits both Exchange Online administration and mailbox non-owner events and will collect events generated 7 days in the past.

New-CAO365Template -Connection $connection -Tenant $tenant -AgentInfo $agent -CreateWebApp -GenerateCertificate -EnableExchangeOnline $true -AuditAdministration $true –AuditOrganization $true –HistoricalEventCollectionDays 7

Create a template using an existing web application

When you create or edit an Office 365 auditing template and you select to use an existing web application, it must be configured to support certificate authentication. See the Microsoft Entra ID and Microsoft 365 User Guide for the required steps.

For more details on integrating applications with Microsoft Entra ID and creating a web application, consult the Microsoft documentation. When creating a web application in the Microsoft Entra admin center, you are required to provide the following URLs: Sign-On URL, App ID URL. Specify any URL address that is unique to your tenant (for example: http://ChangeAuditorApp) for each of them.

Table 68. Available parameters

Parameter	Description
-AgentInfo	An agent object obtained by using the Get-CAAgents command. NOTE: The agent must be able to connect to Microsoft Entra ID. • If the agent is separated from the coordinator by a firewall, you must create a firewall exception for port 8373 on every agent computer to be used for Office 365 auditing. This is the default port that enables the coordinator to communicate with the agent. A different port number can, however, be specified by running the Set-CAConfiguration command. • A firewall outbound exception for remote port 443 (https) must exist for every agent computer that will be used for Office 365 auditing. This is the port that is used for communicating with the tenant.
-Connection	A connection obtained by using the Connect-CAClient command.
-DeploymentType	Specifies the tenant type (Commercial, GCC, or GCCHigh). If not set, the default is Commercial.
-Tenant	The Microsoft Entra tenant/Directory that you would like Change Auditor to audit (for example: yourTenantName.onmicrosoft.com).
-WebAppId	A web application Id. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant. NOTE: Microsoft Entra ID and Microsoft 365 must each have their own dedicated web application. NOTE: When using this parameter, you cannot also specify the –CreateWebApp parameter.
-WebAppKey	The key assigned to the web application specified for the WebAppId parameter. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant.
-AuditAdministration (Optional)	Specifies whether to audit administration events.
-CertificateFile (Optional)	The filename of an exported X509 certificate with private key. NOTE: This parameter is not required if the -CertificateThumbprint or -GenerateCertificate parameter is specified.
-CertificateFilePassword (Optional)	The password for the certificate file. NOTE:   • If the -CertificateFile parameter is not specified this parameter is ignored. • If the -CertificateFile parameter is specified this parameter is required. The private key must be protected by password. Protection with security principal is not supported.
-CertificateThumbprint (Optional)	The thumbprint of a certificate that is located in the user's personal certificate store on the host workstation and must have a private key (string format). NOTE:   • The private key must be marked as exportable. • This parameter is not required if the -CertificateFile or -GenerateCertificate parameter is specified.
-AuditOrganization (Optional)	Specifies whether to audit all Exchange Online mailboxes accessed by users other than the mailbox owner.
-Disabled (Optional)	Specifies whether the auditing template is enabled or disabled.
-EnableExchangeOnline (Optional)	Specifies whether Exchange Online auditing is enabled or disabled.
-EnableOneDrive (Optional)	Specifies whether OneDrive for Business auditing is enabled or disabled.
-EnableSharePoint (Optional)	Specifies whether SharePoint Online auditing is enabled or disabled.
-HistoricalEventCollectionDays (Optional)	Specifies how many days the agent should go back in time to start event collection. The parameter accepts values from 1 to 7. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionHours parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected. NOTE: The historical data returned is based on the information in the Office 365 audit logs. This may not reflect the configuration options in the current template.
-HistoricalEventCollectionHours (Optional)	Specifies how many hours the agent should go back in time to start event collection. The parameter accepts values from 1 to 168. NOTE: When using this parameter, you cannot also specify the –HistoricalEventCollectionDays parameter. NOTE: Using this parameter may cause a duplication of events if the same events have been previously collected. NOTE: The historical data returned is based on the information in the Office 365 audit logs. This may not reflect the configuration options in the current template.
-ExcludedOperations (Optional)	String that specifies events to exclude from the Office 365 OneDrive for Business event, Office 365 SharePoint Online event, and Office 365 Exchange Online event. These generic dynamically constructed events are created when associated activity is detected that does not have a corresponding event defined in Change Auditor.
-OverwriteTenantMailboxAuditing (Optional)	Specifies whether the template auditing settings will overwrite the existing tenant auditing settings.

Example: Create a template that audits both Exchange Online administration and mailbox non-owner events and will collect events generated 7 days in the past.

New-CAO365Template -Connection $connection -Tenant $tenant -AgentInfo $agent -WebAppId $webAppID -WebAppKey $webAppKey1 -CertificateFile 'C:\Users\user.domain\Desktop\CertificateFile.pfx' -CertificateFilePassword $password -EnableExchangeOnline $true -AuditAdministration $true –AuditOrganization $true –HistoricalEventCollectionDays 7

Set-CAO365Template

Use this command to edit the account used to access Office 365 Exchange Online, the type of service and events to audit, and select a new agent.

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	A template object obtained by using the Get-CAO365Templates command.
-CreateWebApp (Optional)	Specifies that you want to create a new web application. You will need to login to register Change Auditor in the tenant and ensure the required consent has been granted. Note: Internet access is required. The Microsoft sign-in page opens automatically. To grant permission for all administrators to create a web application: 1 Select an account with the Global Administrator role. 2 Enter the required password, and select Sign in. 3 Review the required permissions for the Change Auditor Configuration Assistant on the Microsoft consent page. (Consent is only required once per tenant. You may, however, be prompted to enter your log on credentials when creating a new web application.) To apply the consent to all the users in your organization, click to enable Consent on behalf of your organization and click Accept. To apply the consent for just the current signed-in user simply click Accept. NOTE: When you specify this parameter a new web application is created and assigned to the template.
-WebAppId	A web application Id. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant. NOTE: Microsoft Entra ID and Microsoft 365 must each have their own dedicated web application. NOTE: When using this parameter, you cannot also specify the –CreateWebApp parameter.
-WebAppKey	The key assigned to the web application specified for the WebAppId parameter. This application is needed for Change Auditor to authenticate to your Microsoft Entra tenant.
-AgentInfo (Optional) NOTE: This parameter is required if you are modifying the web application.	An agent object obtained by using the Get-CAAgents command. NOTE: The agent must be able to connect to Microsoft Entra ID. • If the agent is separated from the coordinator by a firewall, you must create a firewall exception for port 8373 on every agent computer to be used for Office 365 auditing. This is the default port that enables the coordinator to communicate with the agent. A different port number can, however, be specified by running the Set-CAConfiguration command. • A firewall outbound exception for remote port 443 (https) must exist for every agent computer that will be used for Office 365 auditing. This is the port that is used for communicating with the tenant. NOTE: The web application ID and key values are encrypted; therefore, each time you change the agent associated with a template you must explicitly specify the values again.
-AuditAdministration (Optional)	Specifies whether to audit administration events.
-AuditOrganization (Optional)	Specifies whether to audit all Exchange Online mailboxes accessed by non-owners.
-CertificateFile (Optional)	The filename of an exported X509 certificate with private key. NOTE: This parameter is not required if the -CertificateThumbprint or -GenerateCertificate parameter is specified, or if the web application is not being modified.
-CertificateFilePassword (Optional)	The password for the certificate file. NOTE:   • If the -CertificateFile parameter is not specified this parameter is ignored. • If the -CertificateFile parameter is specified this parameter is required. The private key must be protected by password. Protection with security principal is not supported.
-CertificateThumbprint (Optional)	The thumbprint of a certificate that is located in the user's personal certificate store on the host workstation and must have a private key (string format). NOTE:   • The key must be marked as exportable. • This parameter is not required if the -CertificateFile or -GenerateCertificate parameter is specified, or if the web application is not being modified.
-GenerateCertificate (Optional)	If specified, will generate a new self-signed certificate.
-EnableExchangeOnline (Optional)	Specifies whether Exchange Online auditing is enabled or disabled.
-EnableOneDrive (Optional)	Specifies whether OneDrive for Business auditing is enabled or disabled.
-EnableSharePoint (Optional)	Specifies whether SharePoint Online auditing is enabled or disabled.
-ExcludedOperations (Optional)	String that specifies events to exclude from the Office 365 OneDrive for Business event, Office 365 SharePoint Online event, and Office 365 Exchange Online event. These generic dynamically constructed events are created when associated activity is detected that does not have a corresponding event defined in Change Auditor.
-OverwriteTenantMailboxAuditing (Optional)	Specifies whether the template auditing settings will overwrite the existing tenant auditing settings.

Example: Enable auditing all Office 365 Exchange Online mailboxes accessed by non-owners

Set-CAO365Template -Connection $connection -Template $template
-AuditOrganization $true

Example: Enable auditing of SharePoint Online and OneDrive for Business

Set-CAO365Template -Connection $connection -Template $template -EnableSharePoint $true -EnableOneDrive $true

Example: Generate a new web application and new certificate for an existing O365 auditing template.

Set-CAO365Template -Connection $connection -Template $template -CreateWebApp -GenerateCertificate -AgentInfo $agent

Example: Replace the web application

Set-CAO365Template -Connection $connection -Template $template -WebAppId $webAppId -WebAppKey $webAppKey -CertificateThumbprint $certificateThumbprint -AgentInfo $agent

NOTE: The certificate with the exportable private key is in the current client user personal certificate store and the web application is updated with the specified certificate (.cer file is uploaded to the web app - matching specified thumbprint).

Example: Replace the agent

Set-CAO365Template -Connection $connection -Template $template -AgentInfo $agent

Get-CAO365Templates

Use this command to see all the Office 365 templates available within your installation.

Table 69. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Get a list of all Office 365 templates

Get-CAO365Templates -Connection $connection

Remove-CAO365Template

Use this command to remove a template for auditing Office 365 Exchange Online, SharePoint Online, and OneDrive for Business.

Table 70. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Tenant	The Office 365 tenant that is used for auditing. For example, yourTenantName.onmicrosoft.com.

Example: Remove an Office 365 template

Remove-CAO365Template -Connection $connection -Tenant $tenant

Get-CAO365ExchangeMailboxes

Use this command to find specific mailboxes that can be added to an existing Office 365 Exchange Online template.

NOTE: To run this command, you must first create an Office 365 auditing template. See New-CAO365Template.

Table 71. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Tenant	The Office 365 tenant that is used for auditing. For example, yourTenantName.onmicrosoft.com.
-SearchText (Optional)	The search criteria specified as the mailbox display name. This can be the full name of the mailbox to return a specific mailbox or the starting characters to return a list of mailboxes that start with those characters.
-Skip (Optional)	The number of objects to exclude from the list of returned objects, starting from the top.
-First (Optional)	The number of objects to return.
-IncludeTotalCount (Optional)	The total number of objects in the data set. Values specified for the First or Skip parameters do not impact this count.

Example: Find all Office 365 mailboxes that start with the letter a

Get-CAO365ExchangeMailboxes -Connection $connection -Tenant $tenant -SearchText "a"

Add-CAO365ExchangeTemplateMailboxes

Use this command to audit specific mailboxes in your organization by adding them to an existing Office 365 Exchange Online template.

Table 72. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	A template object obtained by using the Get-CAO365Templates command.
-Mailboxes	Mailbox objects obtained by using the Get-CAO365ExchangeMailboxes command.
-AuditOwnerEvents (Optional)	A switch that indicates that the added mailboxes will be audited for owner activity in addition to the non-owner activity. By default, the mailboxes will be audited for non-owner mailbox activity only. IMPORTANT: It is recommended that you select owner auditing for critical mailboxes only. Owner auditing for a large number of mailboxes produces many events that may affect performance.
-OverwriteExisting (Optional)	If the mailboxes already exist in the template, this switch indicates that the mailboxes will have their current owner/non-owner auditing settings overwritten with new settings.

Example: Add Office 365 mailboxes to the existing Exchange Online template

Add-CAO365ExchangeTemplateMailboxes -Connection $connection -Template $template -Mailboxes $mailboxes –AuditOwnerEvents

Remove-CAO365ExchangeTemplateMailboxes

Use this command to remove mailboxes from an existing Office 365 Exchange Online template.

Table 73. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	A template object obtained by using the Get-CAO365Templates command.
-Mailboxes	Mailbox objects obtained by using the Get-CAO365ExchangeMailboxes command.
-All (Optional)	A switch that indicates that all mailboxes will be removed from the template.

Example: Remove all Office 365 mailboxes from the existing Exchange Online template

Remove-CAO365ExchangeTemplateMailboxes -Connection $connection -Template $template –All

Get-CAO365ExchangeTemplateMailboxes

Use this command to retrieve a list of mailboxes being audited by a particular Office 365 Exchange Online template.

Table 74. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	A template object obtained by using the Get-CAO365Templates command.
-AuditTypeFilter	Parameter that allows you to narrow the search based on the type of activities being audited: non-owner only, owner (non-owner, owner), or any (non-owner only, owner and non-owner).
-DisplayNameFilter	The search criteria specified as the mailbox display name. This can be the full name of the mailbox to return a specific mailbox or the starting characters to return a list of mailboxes that start with those characters.
-Skip (Optional)	The number of objects to exclude from the list of returned objects, starting from the top.
-First (Optional)	The number of objects to return.
-IncludeTotalCount (Optional)	The total number of objects in the data set. Values specified for the First or Skip parameters do not impact this count.

Example: Get all Office 365 audited mailboxes from the existing Exchange Online template

Get-CAO365ExchangeTemplateMailboxes -Connection $connection -Template $template

Example: This example will return mailboxes that are not enabled for owner auditing where the display name starts with “Sam S”

Get-CAO365ExchangeTemplateMailboxes -Connection $connection -Template $template -DisplayNameFilter "Sam S" -AuditTypeFilter NonOwnerOnly

Configuring a Quest On Demand Audit integration

Configuring a Quest On Demand Audit integration

Quest On Demand Audit is a Software as a Service (SaaS) application, available through quest-on-demand.com that provides extensive, customizable auditing of critical activities and detailed alerts about vital changes taking place in Microsoft 365 and Microsoft Entra ID.

On Demand Audit can also provide a single view of activity across hybrid Microsoft environments. By sending Change Auditor Active Directory event data, you can gain visibility to on premises changes (including events gathered up to 30 days prior to installing or upgrading Change Auditor).

To begin, you need to configure a connection between Change Auditor and your organization in On Demand Audit. Once the connection is made, On Demand Audit creates the required subscription used to send events from Change Auditor to On Demand Audit. For details on how Change Auditor uses subscriptions to send events, see the Change Auditor SIEM Integration Guide.

NOTE: Although the configuration is made through Change Auditor, the subscription is managed (edited and removed) through On Demand Audit. See the On Demand Audit User Guide for details.

•	New-CAODAConfiguration

•	Get-CAODAConfiguration

•	Set-CAODAConfiguration

New-CAODAConfiguration

Use this command to create the connection required to send Change Auditor event data to On Demand Audit. When you run this command, you are presented with a dialog where you need to enter the information required to configure the connection. Enter your Quest account credentials to sign in to On Demand Audit and if prompted select the organization. By default, the current installation is used for the configuration name. If required, you can enter a different name for the configuration. This is the configuration name used in On Demand Audit; it does not change the Chane Auditor installation name.

 

Table 2. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Create a subscription to send Active Directory event data to On Demand Audit

New-CAODAConfiguration -Connection $connection

Get-CAODAConfiguration

Use this command to see the details of the current On Demand Audit configuration.

Table 75. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-SubscriptionId (optional)	The ID of an existing On Demand Audit subscription.

Example: Get information about the On Demand Audit configuration

Get-CAODAConfiguration -Connection $connection

Command output

The command returns the following information.

Table 76. Available information about the subscription created by the configuration

Setting	Description
ActiveBatchSize	The current batch size. (The current number of events to include in a single notification message.) The batch size is automatically adjusted based on network throughput and system performance. Its value never exceeds the specified batch size.
AllowedCoordinators	List of coordinators permitted to send events.
BatchSize	Batch size. (The maximum number of events that the active batch size can increase to.)
BatchesSent	Number of batches sent.
Enabled	Whether the subscription is enabled.
EventsSent	Number of events sent.
LastCoordinator	The coordinator that is sending events. If the subscription is disabled, this is the last coordinator that sent events.
LastEventResponse	The last event response. Provides the response in JSON format from the event receiver.
LastEventTimeUTC	When the last event was sent.
NotificationInterval	How often how often (in milliseconds) notifications are sent.
StartTimeUTC	Starting point in time for events being sent.
Subscription Id	The subscription ID.
Subsystems	Subsystems that contain the event data being sent.
Webhook Subscription Id	The webhook subscription ID.

Set-CAODAConfiguration

Use this command to modify an On Demand Audit configuration.

Table 2. Available parameters

Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command. See the Change Auditor Command Guide for details.
-AllowedCoordinators (Optional)	Specifies the DNS or NetBIOS name of the coordinators permitted to send events. By default, any coordinator can send the events. NOTE: The list order does not determine which coordinator is selected to send events.

Example: Set the allowed coordinators for the On Demand Audit configuration to the computers named "coordinator1" and "coordinator2"

Set-CAODAConfiguration -Connection $connection -AllowedCoordinators @("coordinator1", "coordinator2")