Change Auditor 7.1.1 - PowerShell Command User Guide


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-IncludeUninstalled (Optional)	Adds uninstalled agents to the list of agents returned from this command.

Example: Viewing all available and unistalled agents within a specific installation

Get-CAAgents -Connection $connection -IncludeUninstalled

Deploying Change Auditor agents

The following commands are available to manage your agent deployments.


	NOTE: You must be a member of the Administrators role to use these commands. NOTE: Any changes affecting configuration are audited with internal events.

•

•

•

•

•

Update-CAAgentConfigurations

•

Set-CAAgentConfiguration

•

Get-CAAgentSubsystems

•

Enable-CAAgentTemplate

•

Disable-CAAgentTemplate

•

Remove-CAAgentTemplate

•

New-CAConfiguration

•

Get-CAConfigurations

•

Set-CAConfiguration

•

Remove-CAConfiguration

Install-CAAgent

Use this command to install an agent.

Table 12. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-MachineName	The fully qualified name of a target computer.
-Credential	Credentials used to access the target computer.
-OperationTime (Optional)	Specifies when to perform this operation. NOTE: If this is not specified, it defaults to the current time.

Example: Install an agent

Install-CAAgent -Connection $connection -MachineName "ComputerName.DomainName.com" -Credential $credential -OperationTime “01/01/2020 12:00:00”

Ping-CAAgent

Use this command to ensure that the coordinator and agent can communicate using WCF framework.

Table 13. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-AgentInfo	The PSCAAgentInfo retrieved from the Get-CAAgents command.

Example: Test the communication between an agent and coordinator

Ping-CAAgent -Connection $connection -AgentInfo $agentinfo

Uninstall-CAAgent

Use this command to uninstall an agent.

Table 14. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-MachineName	The fully qualified name of the target computer.
-Credential	Credentials used to access the target computer.
-OperationTime (Optional)	Specifies when to perform this operation. NOTE: If this is not specified, it defaults to the current time.

Example: Uninstall an agent

Uninstall-CAAgent -Connection $connection -MachineName "ComputerName.DomainName.com" -Credential $credential -OperationTime “01/01/2020 12:00:00”

Update-CAAgent

Use this command to upgrade an agent.

Table 15. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Agent	Agents obtained from a previous call to Get-CAAgents.
-Credential	Credentials used to access the target computer.
-OperationTime (Optional)	Specifies when to perform this operation. NOTE: If this is not specified, it defaults to the current time.

Example: Upgrade an agent

Update-CAAgent -Connection $connection -Agent $agent -Credential $credential

Update-CAAgentConfigurations

Use this command to update the agent configuration to ensure that the agent is using the most up-to-date configuration.

Table 16. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Agents	Agents obtained from a previous call to Get-CAAgents.

Example: Update an agent configuration

Update-CAAgentConfigurations -Connection $connection -Agents $agent

Set-CAAgentConfiguration

Use this command to assign an auditing configuration to an agent.

Table 17. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Agents	Agents obtained from a previous call to Get-CAAgents.
-Configuration	The configuration obtained by a previous call to Get-CAConfigurations.

Example: Update an agent configuration

Set-CAAgentConfiguration -Connection $connection -Agents $agent -Configuration
$configuration

Get-CAAgentSubsystems

Use this command to see the list of subsystems included in an agent‘s configuration.

Table 18. Available parameters


Parameter	Description
-AgentInfo	The PSCAAgentInfo retrieved from the Get-CAAgents command.

Example: See a list of all subsystems included in an agent‘s configuration

Get-CAAgentSubsystems -AgentInfo $agentinfo

Enable-CAAgentTemplate

Use this command to enable a template.


	NOTE: Currently, this is only supported for FluidFS, Azure AD, and Office 365.

Table 19. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	The template to modify.
-Credential (This is only required for the FluidFS module. It is optional for all others.)	Credentials associated with the target agent and template. These vary depending on the type of template.

Example: Enable a template

Enable-CAAgentTemplate -Connection $connection -Template $template

Disable-CAAgentTemplate

Use this command to disable a template.


	NOTE: Currently, this is only supported for FluidFS, Azure AD, and Office 365.

Table 20. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	The template to modify.
-Credential (This is only required for the FluidFS module. It is optional for all others.).	Credentials associated with the target agent and template. These vary depending on the type of template.

Example: Disable a template

Disable-CAAgentTemplate -Connection $connection -Template $template

Remove-CAAgentTemplate

Use this command to remove a template.


	NOTE: Currently, this is only supported for FluidFS, Azure AD, and Office 365.

Table 21. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Template	The template to remove.
-Credential (This is only required for the FluidFS module. It is optional for all others.)	Credentials associated with the target agent and template. These vary depending on the type of template.

Example: Remove a template

Remove-CAAgentTemplate -Connection $connection -Template $template -credential $credential

New-CAConfiguration

Use this command to create an agent configuration.

Table 22. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-ConfigurationName	The name of the agent configuration to create.

Example: Create an agent configuration

New-CAConfiguration -Connection $connection -ConfigurationName $configurationName

Get-CAConfigurations

Use this command to get list of all agent configurations for a deployment.

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

Example: See a list of all agent configurations

Get-CAConfigurations -Connection $connection

Set-CAConfiguration

Use this command to change the agents port used for the coordinator to communicate with the agent and to configure a proxy server.


	NOTE: If you change the agent port number, you must also create a firewall exception for the new port number on your agent computers.


	NOTE: If your organization uses a proxy server to connect to the internet, you must configure the proxy parameters to audit Azure Active Directory and Office 365 targets. If your proxy server requires authentication, you must also set the credentials using the -ProxyCredential parameter.

Table 24. Available parameters


Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Configuration	The configuration on which to set the port on.
-Port	The port the agent starts its service on for coordinator and agent communication.
-ProxyServer	The fully qualified domain name, down-level name, or IPv4 address of the proxy server. NOTE: To clear the proxy configuration and set the proxy settings back to the default values, specify an empty value for this parameter.
-ProxyPort	The port on which to communicate with the proxy server. (Default is 8080).
-ProxyCredential	The credentials used to authenticate with the proxy server.
-ClearProxyCredential	Specify this parameter to clear the credentials for the proxy server authentication.

Example: Update the port used to communicate with the agent

Set-CAConfiguration –Connection $connection –Configuration $configurationObject –Port $port

Example: Update the configuration to allow for cloud-based auditing

Set-CAConfiguration -Connection $connection -Configuration $config -ProxyServer "ServerName" -ProxyPort 8080

Remove-CAConfiguration

Use this command to remove an existing agent configuration.

Table 25. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Configuration	The name of the configuration to remove. NOTE: You cannot delete the default configuration template.

Example: Remove an agent

Remove-CAConfiguration -Connection $connection -Configuration $configuration

Managing auditing templates

•

Add-CATemplateToConfiguration

•

Get-CAConfigurationTemplates

•

Get-CATemplatesInConfiguration

•

Remove-CATemplatesFromConfiguration

Add-CATemplateToConfiguration

Use this command to assign an auditing template to a Change Auditor configuration.

Table 26. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Configuration	The configuration to which to add a template. Use Get-CAConfigurations to obtain the configuration object.
-Templates	The templates to apply to the configuration. Use Get-CAConfigurationTemplates to obtain the templates.

Example: Assign a template to a configuration

Add-CATemplateToConfiguration -Connection $connection -Configuration $configuration -Templates $templates

Get-CAConfigurationTemplates

Use this command to get a list of all templates in the installation.

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

Example: Get a list of all templates in the installation

Get-CAConfigurationTemplates -Connection $connection

Get-CATemplatesInConfiguration

Use this command to get a list of the templates that are assigned to a configuration.

Table 28. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Configuration	Use Get-CAConfigurations to obtain the configuration object.

Example: Get a list of all templates assigned to a configuration

Get-CATemplatesInConfiguration -Connection $connection -Configuration $configuration

Remove-CATemplatesFromConfiguration

Use this command to remove templates from a configuration.

Table 29. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Configuration	The configuration from which to remove a template. Use Get-CAConfigurations to obtain the configuration object.
-Templates	The templates to remove from the configuration. Use Get-CAConfigurationTemplates to obtain the templates.

Example: Remove a template from a configuration

Remove-CATemplatesFromConfiguration -Connection $connection -Connection $connection
-Configuration $configuration

Working with searches

Searches (both built-in and private) allow you to view valuable information based on activity captured by Change Auditor.

When using the commands, consider the following:

•

You cannot create multiple folders with the same name in the same directory.

•

Microsoft folder naming standards are upheld and restrict folder names to a length between 1 and 4000 characters.

•

You cannot create multiple searches with the same name in the same directory.

•

The commands generate audit events when a folder that contains public searches is deleted.

•

Administrators have full access to all the search commands.

•

Operators access inlcudes the following:

Full access for:

•

Invoke-CASearch

•

Get-CASearches

•

Get-CASearchDefinition

Restricted access to private searches and folders for:

•

Set-CASearchProperties

•

•

•

•

•

•

Remove-CASearchFolder

The following commands are available to manage searches:

•

Invoke-CASearch

•

Get-CASearches

•

Get-CASearchDefinition

•

Set-CASearchProperties

•

•

•

•

•

•

Remove-CASearchFolder

Invoke-CASearch

Use this command to run a search.

Table 30. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Search	The search to run. Use Get-CASearches to find the PSCASearchInfo object required to identify the search.
-StartTime (Optional)	The start time for the events that will be retrieved. By default this is the start time defined in the search.
-EndTime (Optional)	The end time for the events that will be retrieved. By default this is the start time defined in the search.
-Limit (Optional)	The maximum number of records to retrieve and display. By default this is the limit defined in the search.

Example: Running a search and limit the display to 10 events

$connection = Connect-CAClient -InstallationName 'DEFAULT"

$search = Get-CASearches $connection | ? {$_.Name -eq "All Events"}

Invoke-CASearch -Connection $connection -Search $search -limit 10

Get-CASearches

Use this command to view information on all available searches and identify a search info object that is required for some other commands.

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

Example: Viewing all available searches within a specific installation

Get-CASearches $connection

Example: Viewing a specific search

Get-CASearches $connection | ? {$_.Name -eq "All AD Queries in the last 30 days"}

Get-CASearchDefinition

Use this command to obtain the search definition from an existing search. The search definition is XML that can be modified and used to create a search.

Table 32. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
- Search	The search info object obtained from the Get-CASearches command.

Example: Getting the definition of a search with the name “All Events” and writing it to a file at the directory “C:\definitions\All Events.xml”

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

[xml]$xmlString = Get-CASearches $connection | ? {$_.Name –eq “All Events”} | Get-CASearchDefinition $connection

$xmlString.Save(“C:\definitions\All Events.xml”)

Set-CASearchProperties

Use this command to update the search name, default folder, set the limit of a public or private search, or the path and subsystem for an imported .csv file of a list of directory objects.

Table 33. Available parameters
Parameter	Description
-Connection	A connection obtained by using the Connect-CAClient command.
-Search	The search info object obtained from the Get-CASearches command.
-Name	Specifies a new name for the search.
-DefaultFolderPath	Specifies a new default folder path for the search.
-Limit	Specifies a new limit for the search.
-PassThru (Optional)	A switch that specifies to return the updated search after the command runs.
-Subsytem	The subsystem to update. The ability to import a .csv file with a list of objects is available for Active Directory, Exchange, and Group Policy.
-Path	Path to the .csv file to import.