Chat now with support
Chat with Support

Change Auditor 7.1.1 - PowerShell Command User Guide

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:

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.

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

 

-AgentInfo

An agent obtained by using the Get-CAAgents command.

-Connection

A connection obtained by using the Connect-CAClient command.

-WebAppCreationCredential

Azure Active Directory account credentials required to create an Azure web application. The credential object is obtained by using the Get-Credential command.

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

-Disabled (Optional)

Specifies whether the auditing template 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.

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

-O365ExchangeAdminCredential (Optional)

An account with the Exchange Administrator role. It is used to configure the mailbox auditing settings in the tenant that are defined in the template (such as enabling auditing of owner activity). These credentials are used periodically by the agent to validate or update auditing settings, so they are securely stored in Change Auditor.

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

New-CAO365Template -Connection $connection -WebAppCreationCredential $azureCreds -AgentInfo $agent -O365ExchangeAdminCredential $o365Creds -AuditAdministration $true –AuditOrganization $true –HistoricalEventCollectionDays 7

Alternatively, use these parameters when using a pre-created Azure web application that will be used by Change Auditor for authentication.

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

The following permissions must be assigned to the Azure web application:

Windows Azure Active Directory

Application Permissions:

Delegated Permissions:

Microsoft Graph

Application Permissions:

Office 365 Management APIs

Application Permissions:

Delegated Permissions:

-AgentInfo

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

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

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

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

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

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

-O365ExchangeAdminCredential (Optional)

An account with the Exchange Administrator role. It is used to configure the mailbox auditing settings in the tenant that are defined in the template (such as enabling auditing of owner activity). These credentials are used periodically by the agent to validate or update auditing settings, so they are securely stored in Change Auditor.

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

New-CAO365Template -Connection $connection -AgentInfo $agent -O365ExchangeAdminCredential $o365Creds -WebAppKey $webAppKey -WebAppId $webAppId - Tenant $tenant -AuditAdministration $true –AuditOrganization $true
–HistoricalEventCollectionDays 7

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.

-Connection

A connection obtained by using the Connect-CAClient command.

-Template

A template object obtained by using the Get-CAO365Templates command.

-WebAppCreationCredential

Azure Active Directory account credentials required to create an Azure web application. The credential object is obtained by using the Get-Credential command.

-WebAppId

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

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

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

-AuditAdministration (Optional)

Specifies whether to audit administration events.

-AuditOrganization (Optional)

Specifies whether to audit all Exchange Online mailboxes accessed by non-owners.

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

-O365ExchangeAdminCredential (Optional)

An account with the Exchange Administrator role. It is used to configure the mailbox auditing settings in the tenant that are defined in the template (such as enabling auditing of owner activity). These credentials are used periodically by the agent to validate or update auditing settings, so they are securely stored in Change Auditor.

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

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

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

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

Set-CAO365Template -Connection $connection -Template $template -AgentInfo $agent -WebAppId $webAppId -WebAppKey $webAppKey -O365ExchangeAdminCredential $o365LiveCreds

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

-Connection

A connection obtained by using the Connect-CAClient command.

Get-CAO365Templates -Connection $connection

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

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

Remove-CAO365Template -Connection $connection -Tenant $tenant

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

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

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

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

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

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

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

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

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

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

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

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

Get-CAO365ExchangeTemplateMailboxes -Connection $connection -Template $template

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:

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

-Connection

A connection obtained by using the Connect-CAClient command.

Get-CASkypeEventClassInfo –Connection $connection

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

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

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

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

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

Template' -UseWindowsAuthentication $True -Disabled $False

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

-Connection

A connection obtained by using the Connect-CAClient command.

Get-CASkypeTemplates -Connection $connection

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.

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

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

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.

-Connection

A connection obtained by using the Connect-CAClient command.

-TemplateName

The name of the template to remove.

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

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.

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

-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

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

-Connection

A connection obtained by using the Connect-CAClient command.

-SubscriptionId (optional)

The ID of an existing On Demand Audit subscription.

Get-CAODAConfiguration -Connection $connection

Command output

The command returns the following information.

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.

LastEventTime

When the last event was sent.

NotificationInterval

How often how often (in milliseconds) notifications are sent.

StartTime

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.

Use this command to modify an On Demand Audit configuration.

Table 2. Available parameters

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

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 protection templates

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

The following commands are available to manage Active Directory protection:

Use this command to create an Active Directory protection template.

-Connection

A connection obtained by using the Connect-CAClient command.

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

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

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

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

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

 

 

 

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

-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

Operations to be denied for the selected object:

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

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

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

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

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

Use this command to schedule when to enforce the protection.

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

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

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

-Connection

A connection obtained by using the Connect-CAClient command.

-Credential

Credentials used to access the foreign forest.

Get-CAADProtectionTemplates -Connection $connection

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

Get-CAADProtectionTemplates -Connection $connection -Credential $forestCredential

Use this command to remove an Active Directory protection template.

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

Remove-CAADProtectionTemplate -Connection $connection -Template $template

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

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

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

 

 

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating