Change Auditor 7.1.1 - PowerShell Command User Guide

Adding the PowerShell module Viewing available commands and help Installing Change Auditor coordinators and web clients Setting the master time zone Finding Change Auditor installations and coordinators Connecting to and disconnecting from Change Auditor installations and coordinators Managing client authentication options Gathering Change Auditor system information Deploying Change Auditor agents Managing auditing templates Working with searches

Copy-CASearch

Managing Windows File System auditing Managing Fluid File System auditing Managing Azure Active Directory auditing Managing Office 365 auditing Managing Skype for Business auditing Configuring a Quest On Demand Audit integration Working with protection templates

Setting the master time zone

Starting with version 6.9, Change Auditor calculates the Next Run of the reports, and archive and purge jobs based on the master time zone. For new deployments, the master time zone is set to the time zone of the server where the first coordinator is being installed. During an upgrade, the master time zone is set to UTC. You can manually change the master time zone, using the set-CAScheduleMasterTimeZone and get-CAScheduleMasterTimeZone commands. We recommend that you set the master time zone to the time zone where most the users are located.


	NOTE: Because Daylight Saving Time changes on different dates worldwide, Change Auditor’s schedules follow the time change of that specific time zone.

•

Set-CAScheduleMasterTimeZone

•

Get-CAScheduleMasterTimeZone

Set-CAScheduleMasterTimeZone

Use this command to specify which time zone the coordinators should use to calculate Next Run of the reports and archive and purge jobs.

Table 4. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-TimeZoneID	The identifier of a system time zone.
-TimeZoneInfo	A TimeZoneInfo object.


	NOTE: The TimeZoneID and TimeZoneInfo parameters must be a system-recognized time zone obtained through a call to the PowerShell command "[System.TimeZoneInfo]::GetSystemTimezones()".

Example: Set the schedule master time zone with a time zone info object

$atlanticTime = [System.TimeZoneInfo]::GetSystemTimeZones() |? {$_.Id -eq "Atlantic Standard Time"}

Set-CAScheduleMasterTimeZone -Connection $connection -TimeZoneInfo $atlanticTime

Example: Set the schedule master time zone with a time zone identifier

Set-CAScheduleMasterTimeZone -Connection $connection -TimeZoneId "Eastern Standard Time"

Get-CAScheduleMasterTimeZone

Use this command to retrieve what time zone the coordinators should use to calculate Next Run of the reports and archive and purge jobs.

Table 5. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.

Example: Retrieve the schedules master time zone

Get-CAScheduleMasterTimeZone -Connection $connection

Finding Change Auditor installations and coordinators

The following commands allow you to find the Change Auditor installations and coordinators available in your Active Directory environment. Once connected, you can run additional commands to manage the deployment.


	NOTE: The installations and coordinators that a search returns depends on your credentials and domain trusts.

•

Find-CAInstallations

•

Find-CACoordinators

•

Find-CASuitableCoordinator

Find-CAInstallations

Use this command to search Active Directory for all available Change Auditor installations. The default is the current computer’s forest, however, you can optionally specify a domain to search cross-forest for deployments.


	NOTE: This command runs in the context of the current user running PowerShell. The user must have permission to search Active Directory in the specified domain.

Example: Find all Change Auditor installations in DomainName.com

Find-CAInstallations –DomainName ‘DomainName.com’

Find-CACoordinators

Use this command to search Active Directory for all available coordinators. The default is the current computers forest, however, you can optionally specify a domain to search cross-forest for deployments. This search returns all the information required to connect to the coordinator including ports.


	NOTE: This command runs in the context of the current user running PowerShell. The user must have permission to search Active Directory in the specified domain.

Example: Find all available coordinators in DomainName.com

Find-CACoordinators -DomainName 'DomainName.com'

Find-CASuitableCoordinator

Use this command to search Active Directory for a coordinator to which a connection can be made. The default is the current computers forest; however, you can optionally specify a domain to search cross-forest for deployments.

If more than one Change Auditor installation is discovered, the call fails and the –InstallationName parameter is required.

Table 6. Available parameters


Parameter	Description
-Certificate (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies the thumbprint string copied from a certificate found in the certmgr.msc Certificate Manager for the current user in the Personal\Certificates folder. This certificate must be trusted, not expired, have a private key and at least the “Client Authentication” purpose. (“Proves your identity to a remote computer”).

Example: Find a coordinator in ‘DEFAULT’ installation that you have the credentials to connect to

Find-CASuitableCoordinator –InstallationName ‘DEFAULT’

Example: Find a coordinator in Domain that you have the credentials to connect to, when using certificate authentication

$creds = Get-Credential

$connection = Connect-CAClient -Credential $creds

Find-CASuitableCoordinator -Credential $creds -DomainName ‘DomainName.com'

Connecting to and disconnecting from Change Auditor installations and coordinators

•

Connect-CAClient

•

Disconnect-CAClient

Connect-CAClient

Most Change Auditor commands require a connection to a coordinator. This connection can be assigned to a variable and used for any command that requires it. This command searches for a suitable coordinator in a Change Auditor installation and creates a connection. Suitable coordinators are those to which you have access to and can be located by searching through Active Directory service connection points.

You can also connect to Change Auditor installations in untrusted domains or to a specific coordinator by specifying the -ComputerName and -Port parameters.

You can make multiple connections to different coordinators or deployments in the same script as long as the version of Change Auditor is the same.


	NOTE: Connections are closed when the PowerShell session is ended or disconnected.

Table 7. Available parameters


Parameter	Description
-Credential (Optional)	Windows credentials specifying the user to connect to the Change Auditor installation. All operations using this connection will be authorized as this user. When not specified, the current client running PowerShell is used. NOTE: Credentials are required when certificate authentication is being used.
-CoordinatorConnectionPoint	Specify to use a specific coordinator found from a previous call to Find-CACoordinators.
-SelectLocalCoordinator	Create a connection to the local coordinator.
-InstallationName (Optional)	The installation name to connect to. If an installation cannot be found with this name, no connection is made. If more than one Change Auditor installation exists in the current forest, this parameter is mandatory. Omitting it results in a connection failure due to ambiguity.
-DomainName (Optional)	The name of the domain where the Change Auditor installation exists.
-ComputerName	The computer to connect to.
-Port	The port to connect to.
-WaitForServiceReady (Optional)	The number of seconds to wait for the connected coordinator service to be ready. NOTE: If not specified, when the Change Auditor coordinator is not ready for connections due to an in-progress install or upgrade, an error is returned. The maximum is 144,000 seconds, or 10 hours.
-UseCertificateAuth (Optional)	This parameter specifies that the coordinator is expected to be configured for certificate authentication. This parameter does not require an input value. When specified, this parameter is $true.
-DisableCertificateCrlCheck (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies that Certificate Revocation List checking is disabled. This parameter does not require an input value. When specified, this parameter is $true.
-Certificate (Optional)	When certificate authentication between the client and coordinator in environments is in place, this parameter specifies the thumbprint string copied from a certificate found in the certmgr.msc Certificate Manager for the current user in the Personal\Certificates folder. This certificate must be trusted, not expired, have a private key and at least the “Client Authentication” purpose. (“Proves your identity to a remote computer”).

Table 8. Supported parameter sets that enable a connection
Example	Enter the following command:
Recommended: Connect to the installation “XYZ” in the local forest. NOTE: This allows for fault tolerance if you have numerous coordinators by selecting the best option in the domain.	Connect-CAClient –InstallationName ‘XYZ’ -DomainName 'DomainName.com'
Connect to the first suitable coordinator found in any installation in any trusted domain.	$connection = Connect-CAClient
Connect to a specific coordinator by computer name and port.	Connect-CAClient –ComputerName ‘ca-cord.DomainName.com’ –Port 52289
Connect to the first suitable coordinator in the domain “DomainName.com”.	Connect-CAClient –DomainName ‘DomainName.com’
Connect to the first suitable coordinator in the domain “DomainName.com” with an installation name “DEFAULT”.	Connect-CAClient –DomainName ‘DomainName.com’ –InstallationName ‘DEFAULT’
Connect to a coordinator found from Find-CACoordinators.	$coordinators = Find-CACoordinators –DomainName ‘DomainName.com’ $connection = Connect-CAClient –CoordinatorConnectionPoint $coordinators[0]
Connect to a specific coordinator by computer name and port, when using certificate authentication.	$creds = Get-Credential Connect-CAClient -Credential $creds -ComputerName ‘ca-coordinator.DomainName.com’ –Port 52289 -UseCertificateAuth

Disconnect-CAClient

Use this command to disconnect from Change Auditor. (This is the equivalent of closing the Change Auditor client.)

Example: Connect to a Change Auditor deployment, and then close the connection

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

# perform some actions

Disconnect-CAClient $connection

Managing client authentication options

Change Auditor has two authentication method:

•

Windows Forms Authentication (enabled by default)

When users log in, they must enter a Windows user account and a password.

•

Active Directory Client Certificate Authentication

When users log in, they must specify a smart card or certificate. User account and password are not required.

These commands allow you to manage the authentication used in your Change Auditor deployment.

Get-CAAuthenticationOptions

Use this command to view the authentication profile Change Auditor coordinators use in a particular installation.

Returns: An object containing the options for authentication for the specified installation.

Table 9. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-InstallationName (Optional)	The installation name to connect to. If an installation cannot be found with this name, no connection is made. If more than one Change Auditor installation exists in the current forest, this parameter is mandatory. Omitting it results in a connection failure due to ambiguity.
-DomainName (Optional)	The name of the domain where the Change Auditor installation exists.

Example

Get-CAAuthenticationOptions –InstallationName ‘DEFAULT’ –DomainName ‘DomainName.com’

Get-CAAuthenticationOptions -Connection $connection

Set-CAAuthenticationOptions

Use this command to alter the authentication profile the Change Auditor coordinators use in a particular installation.

Returns: An object containing the options for authentication for the specified installation.

Table 10. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-AlwaysChallengeForCredential (Optional)	When specified, instructs the coordinator to disallow any connection that is not accompanied by credentials. For PowerShell clients, this means that the Connect-CAClient command will not connect without the use of the -Credential parameter.
-AllowActiveDirectoryCertificateAuthentication (Optional)	When specified, instructs the coordinator to allow certificate authentication via a web client. This switch has no meaning for the Win32 client.
-AllowWindowsFormsAuthentication (Optional)	When specified, instructs the coordinator to accept default username/password style of credentials.
-AuthenticationOptions (Optional)	This parameter allows the caller to pass directly the result of the Get-CAAuthenticationOptions without having to break down the options into their constituent flag values.