Change Auditor 7.3 - PowerShell User Guide


	NOTE: When you delete a template (see Remove-CAAgentTemplate), the web application created in Azure Active Directory remains. You can delete the web application using the Azure management portal. 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 Azure Active Directory and Office 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 77. Available parameters

Parameter

Description

-AgentInfo

An agent obtained by using the Get-CAAgents command.

NOTE: The agent must be able to connect to Azure.

•

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 Azure 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 Azure Active Directory sign-in page opens automatically.

To grant permission for all administrators to create a web application:

Provide an account with the Global Administrator role.

Enter the required password, and select Sign in.

Review the required permissions for the Change Auditor Configuration Assistant on the Azure 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.

-Tenant

The Azure Active Directory 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 Azure Active Directory and Office 365 User Guide for the required steps.

For more details on integrating applications with Azure Active Directory and creating a web application, consult the Microsoft documentation. When creating a web application in the Azure Classic Portal, 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 78. Available parameters

Parameter

Description

-AgentInfo

An agent object obtained by using the Get-CAAgents command.

NOTE: The agent must be able to connect to Azure.

•

-Connection

A connection obtained by using the Connect-CAClient command.

-Tenant

The Azure AD tenant/Directory that you would like Change Auditor to audit (for example: yourTenantName.onmicrosoft.com).

-WebAppId

An Azure Active Directory web application Id. This application is needed for Change Auditor to authenticate to your Azure Active Directory tenant.

NOTE: Azure Active Directory and Office 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 Azure Active Directory 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 Azure 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 Azure Active Directory sign-in page opens automatically.

To grant permission for all administrators to create a web application:

Select an account with the Global Administrator role.

Enter the required password, and select Sign in.

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

An Azure Active Directory web application Id. This application is needed for Change Auditor to authenticate to your Azure Active Directory tenant.

NOTE: Azure Active Directory and Office 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 Azure Active Directory 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 Azure.

•

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 79. 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 80. 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 81. 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 82. 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 83. 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 84. 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

Managing Skype for Business auditing

The following commands are available to manage Skype for Business auditing:

•

Get-CASkypeEventClassInfo

•

New-CASkypeTemplate

•

Get-CASkypeTemplates

•

Set-CASkypeTemplate

•

Remove-CASkypeTemplate

Get-CASkypeEventClassInfo

Use this command to see the list of event classes available for the Skype for Business subsystem.

Table 85. Available parameters


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

Example: Get a list of all available Skype for Business event classes

Get-CASkypeEventClassInfo –Connection $connection

New-CASkypeTemplate

Use this command to add a Skype for Business template to Change Auditor.


	NOTE: It is recommended that the Change Auditor Coordinator Service is running in the same forest as the Skype for Business Central Management Store (CMS) database server.

Once the template has been created, the agent is notified of the Skype for Business Central Management Store details and the events to audit.

Table 86. Available parameters


Parameter	Description
-AgentInfo	The Change Auditor agent to audit the Skype events. This agent must be running on the Skype for Business Central Management Store database server.
-AuditItems	Collection of events to audit.
-Connection	A connection obtained by using the Connect-CAClient command.
-CMSInstanceName (Optional)	The Microsoft Skype for Business server 2015 / Microsoft Lync Server 2013 Central Management Store (CMS) SQL Server Instance Name. The CMS Instance name must be provided only when the Change Auditor Coordinator Service is not in the same Active Directory forest as Microsoft Skype for Business Server 2015 / Microsoft Lync Sever 2013.
-DatabaseCMSCredential	Skype for Business Central Management Store database credentials.
-TemplateName	The name of the template.
-UseWindowsAuthentication	Specifies whether to use Windows authentication when connecting to the Central Management Store database. If Windows authentication is not used, SQL Authentication will be used.
-SkipCMSDatabaseConnectivityTest (Optional)	Specifies whether to test the Central Management Store (CMS) SQL Server Connection using the supplied CMS credentials.
-Disabled (Optional)	Specifies whether the template is disabled.

Example: Create a Skype for Business template

New-CASkypeTemplate -AgentInfo $agentInfo -AuditItems $auditItems -Connection

$connection -DatabaseCMSCredential $dbCredential -TemplateName 'Skype for Business

Template' -UseWindowsAuthentication $True -Disabled $False

Get-CASkypeTemplates

Use this command to see all the Skype for Business templates that have been created.

Table 87. Available parameters


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

Example: Get a list of all Skype for Business templates

Get-CASkypeTemplates -Connection $connection

Set-CASkypeTemplate

Use this command to update the properties of an existing Skype for Business template. Once the template has been updated, the agent is notified of the Skype for Business Central Management Store details, and the events to audit.


	NOTE: If the Central Management Store database server has changed, you need to redeploy your agent to the new Central Management Store SQL Server, delete the existing template, then create a new template.

Table 88. Available parameters


Parameter	Description
-AgentInfo	The Change Auditor agent to audit the Skype events. This agent must be running on the Skype for Business Central Management Store database server.
-AuditItems	Collection of events to audit.
-Connection	A connection obtained by using the Connect-CAClient command.
-DatabaseCMSCredential	Skype for Business Central Management Store database credentials.
-Template	The name of the existing template to update.
-TemplateName	The name of the template.
-UseWindowsAuthentication	Specifies whether to use Windows authentication when connecting to the Central Management Store database. If Windows authentication is not used, SQL Authentication will be used.
-SkipCMSDatabaseConnectivityTest (Optional)	Specifies whether to test the Central Management Store (CMS) SQL Server Connection using the supplied CMS credentials.
-Disabled (Optional)	Specifies whether the template is disabled.

Example: Modify a Skype for Business template

Set-CASkypeTemplate -Connection $connection -Template $templateToUpdate ‘Updated Skype for Business Template’ -AgentInfo &agentInfo -AuditItems &$auditItems -DatabaseCMSCredential $dbCredential -UseWindowsAuthentication $True -Disabled $False

Remove-CASkypeTemplate

Use this command to remove a Skype for Business template. Agents associated with the template would be notified and Skype for Business configuration events would not be audited anymore.

Table 89. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-TemplateName	The name of the template to remove.

Example: Remove a Skype for Business template

Remove-CASkypeTemplate -Connection $connection -TemplateName 'Skype For Business

Template'

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 Office 365 and Azure Active Directory.

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 90. 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 91. 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")

Working with Active Directory protection templates

Enabling Active Directory protection allows you to lock down critical objects and attributes to prevent accidental or unauthorized creations, modifications, or deletions.


	IMPORTANT: The following commands are only supported for protection templates that are stored in SQL. They will not function if the protection templates are stored in Active Directory.

The following commands are available to manage Active Directory protection:

•

New-CAADProtectionTemplate

•

New-CAProtectedObject

•

Remove-CAProtectedObject

•

New-CAForestCredential

•

New-CAScheduledTimeRange

•

Get-CAADProtectionTemplates

•

Remove-CAADProtectionTemplate

•

Set-CAADProtectionTemplate

New-CAADProtectionTemplate

Use this command to create an Active Directory protection template.

Table 92. Available parameters


Parameter	Description
-Credential	Credentials used to access the foreign forest.
-Name	The template name.
-ProtectedObjects	List of ProtectedObjects. See New-CAProtectedObject for details.
-Attributes (Optional)	List of attributes to protect. When AttributeType is not set to “All” this specifies the attributes for the template. Default is none.
-AttributeType (Optional)	This is applied to the list of attributes specified in the Attributes parameter. Possible values include “All”, “Only” and “AllExcept”. Default is All.
-OverrideAccounts (Optional)	Accounts allowed or not allowed to change the protected objects.
-OverrideAccountsDenied (Optional)	Specifies if you want to deny the list of user in the OverrideAccounts access. You can specify either $true or $false. Default is false which means that the user accounts are not denied access.
-AdminAccounts (Optional)	Accounts that can manage the protection template. Default is none.
-Locations (Optional)	IP addresses to protect. Default is none.
-LocationProtectionType (Optional)	Applied to the IP addresses specified by the Locations parameter. The potential values include ProtectAllLocations, ProtectSelectLocations, AllowSelectLocations, or ProtectUnknownLocations. Default is ProtectAllLocations.
-Schedule (Optional)	It is a list of PSCAScheduledTimeRange objects, created with the New-CAScheduledTimeRange cmdlet. Default is no specified schedule, which means that protection is always enabled. See New-CAScheduledTimeRange for details.

Example: Create an Active Directory protection template

$protectedObject = New-CAProtectedObject -ObjectDistinguishName “ObjectName” -ProtectedScope ScopeObject -Operations Create

New-CAADProtectionTemplate -Connection $connection -Name TemplateSample1 -ProtectedObjects $protectedObject

Example: Creating an Active Directory Protection template to protect objects in a foreign forest

$forestCredential = New-CAForestCredential -ForestName $forestName -Credential $creds

New-CAADProtectionTemplate -Connection $connection -Name $templateName -ProtectedObjects $protectedObject -OverrideAccounts $overrideAccountDn -AdminAccounts $adminAccountDn -Schedule $schedule -Credential $forestCredential

New-CAProtectedObject

Use this command to create a protected object to include in a protection template.

Table 93. Available parameters

Parameter

Description

-ObjectDistinguishName

Distinguish name of object to protect.

-ProtectedScope

Scope of coverage for the protected object. Specify the scope using one of the following values:

•

•

•

Operations to be denied for the selected object:

•

•

•

•

•

NOTE: You can specify multiple operations.

Example: Create a new protected object

New-CAProtectedObject -Connection $connection -ObjectDistinguishName “ObjectName” -ProtectedScope ScopeObject -Operations Create

Remove-CAProtectedObject

Use this command to remove protected objects from a protection template.


	NOTE: Both the -ProtectedObject and the -All parameters are optional, however, one or the other must be specified in the command.

Table 94. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	The PSCAProtectionTemplate object to remove protected objects from. Obtain the template objects using the Get-CAADProtectionTemplates command and filter to select the template object to remove protected objects from.
-Credential	Credentials used to access the foreign forest. NOTE: If the Active Directory protection template contains protected objects from a foreign forest, you must specify the -Credential parameter and value when getting the template object and when removing the protected object. The -Credential parameter value is obtained by running the New-CAForestCredential cmdlet.
-ProtectedObject (Optional)	Protected object (distinguished name).
-All (Optional)	Remove all the protected objects.

Example: Remove protected object

Remove-CAProtectedObject -Connection $connection -Template $template -ProtectedObject $protectedObjectDn

Example: Remove protected object from a foreign forest

$forestCredential = New-CAForestCredential -ForestName $forestName -Credential $creds

$templates = Get-CAADProtectionTemplates -Connection $connection -Credential $forestCredential

Remove-CAProtectedObject -Connection $connection -Templates $template[2] -ProtectedObject $protectedObjectDn -Credential $forestCredential

New-CAForestCredential

Use this command to input credentials for foreign forests when creating Active Directory protection templates with PowerShell.

Table 95. Available parameters


Parameter	Description
-ForestName	The name of the forest to access.
-Credential	Credentials used to access the foreign forest. The credential object is obtained by using the Get-Credential command.

Example: Creating an Active Directory Protection template to protect objects in a foreign forest

$forestCredential = New-CAForestCredential -ForestName $forestName -Credential $creds

New-CAScheduledTimeRange

Use this command to schedule when to enforce the protection.

Table 96. Available parameters


Parameter	Description
-Day	Spelled out day of the week to begin the protection. For example, Monday.
-StartTime	The time to start the protection. This parameter requires an integer and validates that the input is between 0 and 24 inclusive. This implies an hour of the day to start on.
-EndTime	The time to end the protection. This parameter requires an integer and validates that the input is between 0 and 24 inclusive. This implies an hour of the day to end on.

Example: Create a scheduled time range for a protected template

New-CAScheduledTimeRange -Day Monday -StartTime 7 -EndTime 18

Get-CAADProtectionTemplates

Use this command to see all the Active Directory protection templates that have been created including those in a foreign forest.

Table 97. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Credential	Credentials used to access the foreign forest.

Example: Get a list of all Active Directory Protection templates

Get-CAADProtectionTemplates -Connection $connection

Example: Get a list of all Active Directory Protection templates in a foreign forest

$forestCredential = New-CAForestCredential -ForestName $forestName -Credential $creds

Get-CAADProtectionTemplates -Connection $connection -Credential $forestCredential

Remove-CAADProtectionTemplate

Use this command to remove an Active Directory protection template.

Table 98. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Credential	Credentials used to access the foreign forest.
-Template	The PSCAProtectionTemplate object to remove. Obtain the template objects using the Get-CAADProtectionTemplates command and filter to select the object to remove.
-Force	Removes the template without providing confirmation.

Example: Remove an Active Directory protection template

Remove-CAADProtectionTemplate -Connection $connection -Template $template

Example: Remove an Active Directory Protection template in a foreign forest

$forestCredential = New-CAForestCredential -ForestName $forestName -Credential $creds

Remove-CAADProtectionTemplate -Connection $connection -Template $selectedTemplate -Credential $forestCredential

Set-CAADProtectionTemplate

Use this command to modify Active Directory protection templates.

Table 99. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	The PSCAProtectionTemplate object to update. Obtain the template objects using the Get-CAADProtectionTemplates command and filter to select the template object to update.
-TemplateName (Optional)	Sets the template name (string).
-Credential (Optional)	Credentials used to access the foreign forest. NOTE: If the Active Directory protection template contains protected objects and accounts from a foreign forest, you must specify the -Credential parameter and value when getting the template and when modifying the template object. The -Credential parameter value is obtained by running the New-CAForestCredential cmdlet.
-ProtectedObjects (Optional)	List of ProtectedObjects. See New-CAProtectedObject for details.
-Attributes (Optional)	List of attributes to protect. When AttributeType is not set to “All” this specifies the attributes for the template. Default is none specified.
-AttributeType (Optional)	This is applied to the list of attributes specified in the Attributes parameter. Possible values include “All”, “Only” and “AllExcept”. Default is All.
-OverrideAccounts (Optional)	Accounts allowed or not allowed to change the protected objects. String array of distinguished names.
-OverrideAccountsDenied (Optional)	Specifies if you want to deny the list of user in the OverrideAccounts access. You can specify either $true or $false. Default is false which means that the user accounts are not denied access.
-AdminAccounts (Optional)	Accounts that can manage the protection template. (If accounts are specified, then only those specified accounts can manage the template. If no accounts are specified, then all Change Auditor administrators can manage the template.) Default is none specified. This is a string array of distinguished names.
-Locations (Optional)	IP addresses to protect. Default is none specified.
-LocationProtectionType (Optional)	Applied to the IP addresses specified by the Locations parameter. The potential values include ProtectAllLocations, ProtectSelectLocations, AllowSelectLocations, or ProtectUnknownLocations. Default is ProtectAllLocations.
-Schedule (Optional)	It is a list of PSCAScheduledTimeRange objects, created with the New-CAScheduledTimeRange cmdlet. Default is no specified schedule, which means that protection is always enabled. See New-CAScheduledTimeRange for details.
-Disabled	Enable and disable the template.