Chat now with support
Chat mit Support

Change Auditor 7.3 - PowerShell User Guide

Managing Windows File System auditing

Change Auditor for Windows File Server tracks, audits, and alerts on file and folder changes in real time, translating events into simple terms and eliminating the time and complexity required by system provided auditing. The auditing scope can be set on an individual file or folder or an entire file system recursive or non-recursive. You can include or exclude certain files or folders from the audit scope to ensure a faster and more efficient audit process.

Managing Windows file system auditing is available through the following PowerShell commands:

•
New-CAWindowsFSAuditObject
•
New-CAWindowsFSAuditTemplate
•
Remove-CAWindowsFSAuditTemplate
•
Set-CAWindowsFSAuditTemplate
•
Get-CAWindowsFSAuditTemplates
•
Get-CAWindowsFSEventClassInfo
New-CAWindowsFSAuditObject

Use this command to define a folder or file paths to audit.

* 
NOTE:  
•
For All Drives - IncludePath is '*', IncludePathType is Folder and IncludeScope is ScopeOneLevel or ScopeSubtree.
•
When IncludePath is set to '[All Shares]', this is a SystemShare.
Table 50. Parameter description
Parameter
Description

-IncludePath

Specifies the folder or file to audit.

NOTE: Built-in folder values include Common Program Files, Program Files, System Drive, Windows Directory, and All Shares.

-IncludePathType

Specifies the type of path to audit based on one of the following values:

•
SystemFile
•
SystemFolder
•
SystemShare
NOTE: Only one type of path can be specified.

-IncludeScope

 

Specifies the scope to monitor for the Includepath based on one of the following values:

•
ScopeObject
•
ScopeOneLevel
•
ScopeSubtree

-AuditEvents

The events to audit.

Use Get-CAWindowsFSEventClassInfo to get the list of event classes.

-IncludeMask (Optional)

Specifies what to include in the selected folder or file path to audit. Entering * will audit all files and folders in the selected folder.

NOTE: Includemask is required for Systemfolder and systemshare types but not systemfile.

-ExcludeFilePaths (Optional)

Specifies the names and paths of any files to exclude from auditing.

The default is set to None.

-ExcludeFolderPaths (Optional)

Specifies the names and paths of any subfolders to exclude from auditing. The default is set to None.

-Disabled (Optional)

Specifies whether auditing is enabled or disabled on the selected path or folder. The default is set to false.

Example: Monitoring a directory for all file types and all subfolders but excluding one subfolder

New-CAWindowsFSAuditObject -IncludePath "C:\ExampleDirectory" -IncludePathType SystemFolder -IncludeScope ScopeSubTree -AuditEvents $auditEvents -IncludeMask "*"
–ExcludeFolderPaths "C:\ExampleDirectory\ExcludedDirectory"

Example: Monitoring a directory for one level for all file type except for .tmp files

New-CAWindowsFSAuditObject -IncludePath "C:\ExampleDirectory" -IncludePathType SystemFolder -IncludeScope ScopeOneLevel -AuditEvents $auditEvents -IncludeMask "*" –ExcludeFilePaths "*.tmp"

New-CAWindowsFSAuditTemplate

To enable Windows File System auditing, you must first create an auditing template for each file or folder to audit. Each auditing template defines the files or folders to audit, the auditing scope, and the excluded processes.

Use this command to create a Windows file system auditing template.

Table 51. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-TemplateName

The template name.

-AuditObjects

The folder or file path objects created using
New-CAWindowsFSAuditObject.

-ExcludeProcess (Optional)

The list of processes to exclude from auditing. The default is none.

-DiscardTooltipEvents (Optional)

Multiple folder open events are generated by tooltips (folder content information that is displayed when you hover your mouse over a folder) because Windows Explorer navigates the folder tree for all the sub-folders when you hover over the parent folder to see the tooltip. To ignore the folder opened events generated by this action set this parameter to 'true'.

-DiscardBrowsingEvents (Optional)

Multiple file open events are generated by file scans because Windows Explorer opens and reads the header of all files contained in an opened folder for information to display in the window. To ignore the file open events generated by this action set this parameter to 'true'.

-Disabled (Optional)

Specifies whether the template is enabled or disabled. Default is set to false.

Example: Create a Windows File System template

New-CAWindowsFSAuditTemplate -Connection $connection -TemplateName 'New-FSTemplate' -AuditObjects $auditObject -ExcludeProcess $excludeProcess -DiscardTooltipEvents $true -DiscardBrowsingEvents $true -Disabled $false

Remove-CAWindowsFSAuditTemplate

Use this command to delete a Windows File System auditing template.

Table 52. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-Template

The CAWindowsFSAuditTemplate object to remove. Obtain the template objects using the Get-CAWindowsFSAuditTemplates command and filter to select the object to remove.

-Force (Optional)

Removes template without prompting for a confirmation. The default is false.

Example: Remove a Windows File System template

Remove-CAWindowsFSAuditTemplate -Connection $connection -Template $removeTemplate

 

Set-CAWindowsFSAuditTemplate

Use this command to edit an existing Windows File System auditing template.

Table 53. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-Template

The CAWindowsFSAuditTemplate object to edit. Obtain the template objects using the Get-CAWindowsFSAuditTemplates command and filter to select the object to remove.

-TemplateName (Optional)

The template name.

-AuditObjects (Optional)

The folder or file path objects created using
New-CAWindowsFSAuditObject.

-ExcludeProcess (Optional)

The list of processes to exclude from auditing. The default is none.

-DiscardTooltipEvents (Optional)

Multiple folder open events are generated by tooltips (folder content information that is displayed when you hover your mouse over a folder) because Windows Explorer navigates the folder tree for all the sub-folders when you hover over the parent folder to see the tooltip. To ignore the folder opened events generated by this action set this parameter to 'true'.

-DiscardBrowsingEvents (Optional)

Multiple file open events are generated by file scans because Windows Explorer opens and reads the header of all files contained in an opened folder for information to display in the window. To ignore the file open events generated by this action set this parameter to 'true'.

-Disabled (Optional)

Set to true or false to enable or disable the template.

Example: Excluding and changing the template name

Set-CAWindowsFSAuditTemplate -Connection $connection -Template $Template -ExcludeProcess "avsoftware.exe" -TemplateName "NewTemplateName"

Get-CAWindowsFSAuditTemplates

Use this command to see all the Windows File System auditing templates available within your installation.

Table 54. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

Example: Get a list of all Windows File Server templates

Get-CAWindowsFSAuditTemplates -Connection $connection

Example: Get a template based on name

$template = Get-CAWindowsFSAuditTemplates -Connection $connection | where TemplateName -eq TemplateName

Get-CAWindowsFSEventClassInfo

Use this command to get a list of all available Windows File System auditing event classes.

Table 55. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

Example: Get a list of all Windows File Server event classes

Get-CAWindowsFSEventClassInfo -Connection $connection

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 instance name of the SQL server.

-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 of the SQL server.

-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 Fluid File System auditing

Change Auditor for Fluid File System tracks, audits, reports, and alerts on file and folder changes in real time, translating events into simple text and eliminating the time and complexity required by system provided auditing. The auditing scope can be set on an individual file or folder or an entire file system recursive or non-recursive. Change Auditor also allows you to include or exclude certain files or folders from the audit scope to ensure a fast and efficient audit process.

Change Auditor captures events and provides detailed information relating to the following activities:

•
File and folder access
•
File and folder creation, deletion, and renames
•
File and folder permission changes
•
Content changes, such as file opens and writes
* 
NOTE: Change Auditor for Fluid File System audits only SMB operations on FluidFS clusters.

The following commands are available to manage Fluid File System auditing:

•
Get-CAFluidFSClusters
•
Get-CAFluidFSEncryptionStatus
•
Get-CAFluidFSEventClassInfo
•
Get-CAFluidFSTemplates
•
Get-CAFluidFSVolumes
•
New-CAFluidFSAuditVolume
•
New-CAFluidFSTemplate
•
Clear-CAFluidFSTemplate
•
Set-CAFluidFSTemplate
•
Set-CAFluidFSEncryptionCredential
Get-CAFluidFSClusters

Use this command to see a list of all Fluid File Service clusters available to audit.

Table 62. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

Example: See a list of FluidFS cluster names

Get-CAFluidFSClusters -Connection $connection

Get-CAFluidFSEncryptionStatus

Use this command to see if encryption has been set. Encryption protects the data as it passes between the FluidFS cluster and the Change Auditor agents.

Table 63. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-ClusterName

The name of the FluidFS cluster to audit.

-ClusterConfigurationCredential

Administrator credentials to access Enterprise Manager.

Example: Determine if FluidFS encryption has been set (True if the encryption status is set; false otherwise)

Get-CAFluidFSEncryptionStatus -Connection $connection -ClusterName $clustername -ClusterConfigurationCredential $credential

Get-CAFluidFSEventClassInfo

Use this command to get a list of all available FluidFS event classes.

Table 64. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

Example: Get a list of all FluidFS event classes.

Get-CAFluidFSEventClassInfo -Connection $connection

Get-CAFluidFSTemplates

Use this command to see all the Fluid File System templates available within your installation.

Table 65. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

Example: Get a list of all FluidFS templates

Get-CAFluidFSTemplates -Connection $connection

Get-CAFluidFSVolumes

Use this command to get a list of all volumes on a specified cluster.

Table 66. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-ClusterName

The name of the cluster from which to retrieve volume names.

-ClusterConfigurationCredential

Administrator credentials to access Enterprise Manager. This allows the Coordinator to connect with the Enterprise Manager Data Collector service and populate the list of available volumes to audit.

Example: See a list of all available volumes on a cluster

Get-CAFluidFSVolumes -Connection $connection -ClusterName $clustername -ClusterConfigurationCredential $credential

New-CAFluidFSAuditVolume

Use this command to define which volumes to audit.

•
Inclusions allows you to specify what in the selected volume to be audit.
•
Exclusions allow you to refine the settings defined on the Inclusions tab. That is, you can optionally specify the names and paths of any subfolders and files in the selected volume to exclude from auditing.
* 
NOTE: When specifying exclusions with PowerShell, you must specify the volume. This is not required for inclusion masks.

For example:
$includePaths = "?folder\**"
$excludeFilePaths = "\vol1\*.tmp"

 

Table 67. Parameter description
Parameter
Description

-Volume

The name of the volume to audit.

-IncludePaths

The folders\files to include.

NOTE: You can also enter the name of an individual subfolder or file to include. However, if you enter the name of a subfolder, you will only receive events for operations performed against the specified subfolder. You will not receive events for operations performed against any child objects under the specified subfolder.

-EventClasses

The events to audit.

-ExcludeFilePaths (Optional)

The name and path of files to exclude from auditing.

-ExcludeFolderPaths (Optional)

The name and path of subfolders to exclude from auditing.

-Disabled (Optional)

Specifies whether auditing is enabled or disabled on the volume. The disable feature allows you to temporarily stop auditing the specified volume without having to remove the auditing template or individual volume from a template.

Example: Define the volumes to audit

$auditVolume = New-CAFluidFSAuditVolume -Volume $volumes[0] -IncludePaths $includePaths -EventClasses $fluidFSEventClasses -ExcludeFilePaths $excludeFilePaths -ExcludeFolderPaths $excludeFolderPaths -Disabled $False

New-CAFluidFSTemplate

To enable FluidFS auditing in Change Auditor, you must first create an auditing template for each file server to audit. Each auditing template defines the location of the file server, the auditing scope, and the Change Auditor agents that are to receive the events.

* 
NOTE: There can be only 1 FluidFS auditing template per file server. If you want to audit multiple audit paths, use the same template to specify all the paths to audit on the selected file server.

Use this command to create a Fluid File System auditing template.

Returns: A FluidFS template object.

Table 68. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-ClusterName

The name of the cluster to audit.

-Agents

The Change Auditor agents that are to receive the FluidFS events.

NOTE: Specifying multiple agents may provide better performance because the file server will load balance audit events and send each assigned agent events round-robin style. However, the downside is that the ‘where’ field for FluidFS events may contain any one of these agents. Also, if FluidFS event logging is enabled, events are written on multiple agent servers.

-AuditItems

The volumes and their list of exclusions and inclusions.

-ClusterConfigurationCredential

Administrator credentials to access Enterprise Manager. This allows the Coordinator to connect with the Enterprise Manager Data Collector service and populate the list of available volumes to audit.

-Disabled (Optional)

Specifies whether the template is enabled or disabled.

Example: Create a FluidFS template

New-CAFluidFSTemplate -Connection $connection -ClusterName $clustername -Agents $agents -AuditItems $auditItems -ClusterConfigurationCredential $credential
-Disabled $False

Clear-CAFluidFSTemplate

Use this command to delete a FluidFS to delete a template when a connection cannot be made with the FluidFS cluster.

* 
NOTE: Auditing settings must then be removed from the cluster using Enterprise Manager.
Table 69. Parameter description
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-Template

The template to delete.

Example: Delete a template when the Fluid FS cluster cannot be reached

Clear-FluidFSTemplate -Connection $connection -Template $template

Set-CAFluidFSTemplate

Use this command to edit an existing Fluid File System template.

* 
NOTE: You can also use the Enable-CAAgentTemplate and Disable-CAAgentTemplate to enable or disable the template.
Table 70. Available parameters
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-Template

The template to edit.

-ClusterConfigurationCredential

Administrator credentials to access Enterprise Manager. This allows the Coordinator to connect with the Enterprise Manager Data Collector service and populate the list of available volumes to audit.

-Agents (Optional)

The Change Auditor agents that are to receive the FluidFS events.

-AuditItems (Optional)

The volumes and their list of exclusions and inclusions.

-Enable (Optional)

Set to true or false to enable and disable the template.

Example: Modify a FluidFS template

Set-CAFluidFSTemplate -Connection $connection -Template $template -ClusterConfigurationCredential $credential -Enable True -Agents $agents -AuditItems $auditItems

Set-CAFluidFSEncryptionCredential

Use this command to enable or disable encryption for auditing on the Fluid File System cluster. Encryption allows you to protect the event traffic as it passes between the FluidFS cluster and the Change Auditor agents.

Table 71. Available parameters
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

-ClusterName

The name of the cluster to audit.

-ClusterConfigurationCredential

Administrator credentials to access Enterprise Manager.

-EncryptionCredential

The service account credentials for the cluster to use when encrypting events.

Example: Modify the encryption (required or not) for auditing on the Fluid FS cluster

Set-CAFluidFSEncryptionCredential -Connection $connection -ClusterName $clustername -ClusterConfigurationCredential $credential -EncryptionCredential $EncryptionCredential

Managing Azure Active Directory auditing

Change Auditor audits activity in the Azure portal that corresponds to the events in the Azure Active Directory auditing logs and sign-in activity. Managing Azure Active Directory 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 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)

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

Table 72. Available parameters
Parameter
Description

-AgentInfo

An agent object obtained using the Get-CAAgents command. The agent is used for Azure Active Directory auditing.

NOTE: The agent must be allowed to connect to Azure Active Directory.
•
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 Azure Active Directory 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 Azure Active Directory 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:
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 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).

-AuditLogs

Specifies whether or not to audit the Azure Active Directory 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 Azure Active Directory 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 Azure Active Directory.

Example: Creating Azure Active Directory 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 Azure web application that Change Auditor will use 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:

Table 73. 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 74. Available parameters
Parameter
Description

-AgentInfo

An agent object obtained using the Get-CAAgents command. The agent will be used for Azure Active Directory auditing.

NOTE: The agent must be allowed to connect to Azure Active Directory.
•
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 Azure Active Directory 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 Azure Active Directory auditing. This is the port that is used for communicating with the tenant.

-Connection

A connection obtained by using the Connect-CAClient command.

-Tenant

The Azure Active Directory tenant/directory that you want to audit (for example: yourTenantName.onmicrosoft.com).

-AuditLogs

Specifies whether or not to audit the Azure Active Directory 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 Azure Active Directory sign-in activity. You must enable at least one type of activity to audit using the
- AuditLogs or -SignIns parameter.

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

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

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


Example: Creating an Azure Active Directory 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 Azure Active Directory 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 75. Available parameters
Parameter
Description

-AgentInfo

An agent object obtained using the Get-CAAgents command. The agent will be used for Azure Active Directory auditing.

NOTE: The agent must be allowed to connect to Azure Active Directory.
•
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 Azure Active Directory 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 Azure Active Directory 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 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:
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 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.

-AuditLogs

Specifies whether or not to audit the Azure Active Directory 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 Azure Active Directory sign-in activity. You must enable at least one type of activity to audit using the
- AuditLogs or -SignIns parameter.

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

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

Example: Modify Azure Active Directory 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 Azure Active Directory templates available within your installation.

Table 76. Available parameters
Parameter
Description

-Connection

A connection obtained by using the Connect-CAClient command.

Example: Get a list of all Azure AD templates

Get-CAAzureADTemplates -Connection $connection

Verwandte Dokumente

The document was helpful.

Bewertung auswählen

I easily found the information I needed.

Bewertung auswählen