Chat now with support
Chat with Support

Change Auditor 7.0.3 - PowerShell Command User Guide

Gathering Change Auditor system information

You can gather Change Auditor system information to help you to manage your installation components.

Use this command to retrieve coordinator-specific (as opposed to installation-wide) status information from the connected coordinator such as coordinator name, status, deployment name, version, connected agents, connected legacy agents, connected clients, client port, total events, and buffered events which may be different on each coordinator.

Get-CACoordinator $connection

Use this command to gather information about all the coordinators in a Change Auditor installation.

Get-CACoordinators -Connection $connection

Use this command to retrieve installation-specific (as opposed to coordinator-specific) status information including the name of the installation, database server, and database and the database size.

Get-CAInstallation -Connection $connection

Use this command to view information on all available (and optionally uninstalled) agents.

-Connection

A connection obtained by using the Connect-CAClient command.

-IncludeUninstalled (Optional)

Adds uninstalled agents to the list of agents returned from this command.

Get-CAAgents -Connection $connection -IncludeUninstalled

Deploying Change Auditor agents

The following commands are available to manage your agent deployments.

Use this command to install an agent.

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

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

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

-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

Use this command to uninstall an agent.

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

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

Use this command to upgrade an agent.

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

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

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

-Connection

A connection obtained by using the Connect-CAClient command.

-Agents

Agents obtained from a previous call to Get-CAAgents.

Update-CAAgentConfigurations -Connection $connection -Agents $agent

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

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

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

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

-AgentInfo

The PSCAAgentInfo retrieved from the Get-CAAgents command.

Get-CAAgentSubsystems -AgentInfo $agentinfo

Use this command to enable a template.

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

Enable-CAAgentTemplate -Connection $connection -Template $template

Use this command to disable a template.

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

Disable-CAAgentTemplate -Connection $connection -Template $template

Use this command to remove a template.

 

-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

Use this command to create an agent configuration.

-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

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

-Connection

A connection obtained by using the Connect-CAClient command.

Example: See a list of all agent configurations

Get-CAConfigurations -Connection $connection

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

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

-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

Use this command to remove an existing agent configuration.

-Connection

A connection obtained by using the Connect-CAClient command.

-Configuration

The name of the configuration to remove.

Example: Remove an agent

Remove-CAConfiguration -Connection $connection -Configuration $configuration

Managing auditing templates

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

-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

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

-Connection

A connection obtained by using the Connect-CAClient command.

Example: Get a list of all templates in the installation

Get-CAConfigurationTemplates -Connection $connection

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

-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

 

Use this command to remove templates from a configuration.

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

The following commands are available to manage searches:

Use this command to run a search.

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

$connection = Connect-CAClient -InstallationName 'DEFAULT"

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

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

 

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

-Connection

A connection obtained by using the Connect-CAClient command.

Get-CASearches $connection

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

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.

-Connection

A connection obtained by using the Connect-CAClient command.

- Search

The search info object obtained from the Get-CASearches command.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

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

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

Use this command to update the name, default folder, or limit of a public or private search from the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-Search

The search info object obtained from the Get-CASearches command.

-Name (Optional)

An optional parameter specifying a new name for the search.

-DefaultFolderPath (Optional)

An optional parameter specifying a new default folder path for the search.

-Limit (Optional)

An optional parameter specifying a new limit for the search.

-PassThru (Optional)

A switch that specifies to return the updated search after the command runs.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

$search = Get-CASearches $connection | ?{$_.Name –eq “All Owner Mailbox Events”}

Set-CASearchProperties $connection –Name “Display my owner mailbox events” -PassThru

Use this command to copy a search in the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-Search

The search info object obtained from the Get-CASearches command.

-IsPublic (Optional)

An optional switch that specifies if the search is public. The default is private.

-UserSid

An optional parameter that is used (when –IsPublic is not used) to specify the SID of the user that owns the directory where the copy of the search is placed.

-Path

A parameter that specifies a path where the copy is to be placed. The default is the root folder of the user/public folder specified with
–UserSid /-IsPublic.

-Name (Optional)

An optional parameter that specifies a new name for the copy of the search.

-PassThru (Optional)

A switch that specifies to return the updated search after the command runs.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

$search = Get-CASearches $connection | ? {$_.Name –eq “New Search for Employee”}

Copy-CASearch –Connection $connection –Search $search –UserSid S-1-5-21-3623811015-3361044348-30300820-1013 –Path Private\Searches\New –Name “All My Events” -PassThru

Use this command to create a search in the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-XmlSearchDefinition

An XML string or object that represents a search definition.

-IsPublic

A switch that specifies if the search is public. The default is private.

-UserSid

A parameter that is used (when –IsPublic is not used) to specify the SID of the user who owns the new search.

-Path

A parameter that specifies a path where the new search will be placed. The default is the root folder of the user/public folder specified with –UserSid /-IsPublic.

-Name

A parameter that specifies a new name for the search.

-PassThru (Optional)

A switch that specifies to return the new search after the command runs.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

$searchDefinition = Get-Content C:\Users\Admin\Documents\MySearchDefinition.xml

Add-CASearch –Connection $connection –XmlSearchDefinition $searchDefinition
–IsPublic –Path Shared\AllSearches\New –Name “All events in the past 23 hours”
-PassThru

Use this command to move a search from one folder path to another in the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-IsPublic

A switch that specifies if the search is public. The default is private.

-UserSid

A parameter that is used (when –IsPublic is not used) to specify the SID of the user who owns the new search.

-Path

A parameter that specifies the path where the search will be placed. The default is the root folder of the user/public folder specified with –UserSid /-IsPublic.

-Search

The search info object obtained from the Get-CASearches command.

-PassThru (Optional)

A switch that specifies to return the updated search after the command runs.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

$search = Get-CASearches $connection | ? {$_.Name –eq “All AD Queries in the last 30 days”}

Move-CASearch $connection –Search $search –UserSid S-1-5-21-3623811015-3361044348-30300820-1013 –Path “Shared\Skype”

Use this command to remove a public or private search from the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-Search

The search info object obtained from the Get-CASearches command.

-Force (Optional)

A parameter that removes the prompt before a search is removed.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

$search = Get-CASearches $connection | ? {$_.Name –eq “All Exchange Admin Events”}

Remove-CASearch $connection –Search $search

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

$search = Get-CASearches $connection | ? {$_.OwnerSid –eq “S-1-5-21-3623811015-3361044348-30300820-1013”} | ? {$_.FolderPath –eq “Security\Internal\Searches”} | ? {$_.Name –eq “All Search Events”}

Remove-CASearch $connection –Search $search

Use this command to create a search folder in the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-IsPublic

A switch that specifies if the search is public. The default is private.

-UserSid

A parameter that is used (when –IsPublic is not used) to specify the SID of the user who owns the new folder.

-Path

A parameter that specifies the path to create. The default is the root folder of the user/public folder specified with –UserSid /-IsPublic.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

Add-CASearchFolder –Connection $connection –IsPublic –Path Shared\Searches\New

Use this command to remove a public or private folder from the installation.

-Connection

A connection obtained by using the Connect-CAClient command.

-IsPublic

A switch that specifies the folder being removed is public.

-UserSid

A parameter that is used if –IsPublic is not specified to speci-fy the SID of the user that owns the private folder being removed.

-Path

A parameter that specifies the path to the folder to remove. The default is the root folder of the user/public folder specified with
–UserSid /-IsPublic.

-Force (Optional)

An optional parameter that removes the prompt before a search is removed.

$connection = Connect-CAClient –InstallationName ‘DEFAULT’

Remove-CASearchFolder $connection –IsPublic –Path Shared\Miscellaneous\OldSearches

Related Documents