Command-line basics | TrendAI™

You can use the local command-line interface (CLI) to command both agents and Server & Workload Protection to perform many actions. The CLI can also configure some settings, and to display system resource usage.

You can also automate many of the CLI commands using the Server & Workload Protection API. For more information, see First Steps Toward Server & Workload Protection Automation.

The following are the CLI commands:

dsa_control
dsa_query
dsa_scan

dsa_control

You can use dsa_control to configure some agent settings, and to manually trigger some actions such as activation, anti-malware scans, and baseline rebuilds.

On Windows, when self-protection is enabled, local users cannot uninstall, update, stop, or otherwise control the agent. They must also supply the authentication password when running CLI commands.

On macOS, when self-protection is enabled, local users cannot uninstall, modify, stop, or otherwise control the agent. They must also supply the authentication password when running CLI commands.

dsa_control only supports English strings. Unicode is not supported.

To use dsa_control:

Procedure

On Windows:
1. Open a Command Prompt as Administrator.
2. Change to the agent's installation directory. For example: cd C:\Program Files\Trend Micro\Deep Security Agent\
3. Run dsa_control, as follows: dsa_control <option> where <option> is replaced with one of the options described in dsa_control options.
On Linux:
- sudo /opt/ds_agent/dsa_control <option> where <option> is replaced with one of the options described in dsa_control options.
On macOS:
1. Open a Terminal window as an Administrator.
2. Change to the agent's installation directory. For example: cd /Library/Application Support/com.trendmicro.DSAgent
3. Run dsa_control, as follows: dsa_control <option> where <option> is replaced with one of the options described in dsa_control options.

dsa_control options

dsa_control [-a <str>] [-b] [-c <str>] [-d] [-g <str>] [-s <num>] [-m] [-p <str>]
                     [-r] [-R <str>] [-t <num>] [-u <str>:<str>] [-w <str>:<str>] [-x dsm_proxy://<str>]
                     [-y relay_proxy://<str>] [--buildBaseline] [--scanForChanges] [Additional keyword:value
                     data to send to Server & Workload Protection during activation or heartbeat...]

Parameter	Description
`-a <str>, --activate=<str>`	Activate agent with manager at the specified URL in this format: `dsm://<host>:<port>/` where: `<host>` could be either the manager's fully qualified domain name (FQDN), IPv4 address, or IPv6 address `<port>` is the manager's listening port number Optionally, after the argument, you can also specify some settings such as the description to send during activation. See Agent-initiated heartbeat command ("dsa_control -m"). They must be entered as key:value pairs (with a colon as a separator). There is no limit to the number of key:value pairs that you can enter, but the key:value pairs must be separated from each other by a space. Quotation marks around the key:value pair are required if it includes spaces or special characters.
`-b, --bundle`	Create an update bundle. Not supported on macOS
`-c <str>, --cert=<str>`	Identify the certificate file. Not supported on macOS.
`-d, --diag`	Generate an agent package. For more detailed instructions, see Create an agent diagnostic package via CLI on a protected computer.
`-g <str>, --agent=<str>`	Agent URL. Defaults to `https://localhost:<port>/` where `<port>` is the manager's listening port number. Not supported on macOS.
`-m, --heartbeat`	Force the agent to contact the manager now.
`-p <str>` or `--passwd=<str>`	Authentication password that you might have configured in Server & Workload Protection previously. See Configure self-protection through Workload Security for details. If configured, the password must be included with all dsa_control commands except `dsa_control -a`, `dsa_control -x`, and `dsa_control -y`. Example: `dsa_control -m -p MyPa$w0rd` If you type the password directly into the command line, it is displayed on the screen. To hide the password with asterisks () while you type, enter the interactive form of the command, `-p \`, which prompts you for the password. Example: `dsa_control -m -p *`
`-r, --reset`	Reset the agent's configuration. This will remove the activation information from the agent and deactivate it.
`-R <str>, --restore=<str>`	Restore a quarantined file. On Windows, you can also restore cleaned and deleted files.
`-s <num>, --selfprotect=<num>`	Enable agent self-protection (1: enable, 0: disable). Self-protection prevents local end-users from uninstalling, stopping, or otherwise controlling the agent. For details, see Enable or disable agent self-protection. Note that although dsa_control lets you enable self-protection, it does not let you configure an associated authentication password. You need Server & Workload Protection for that. See Configure self-protection through Workload Security for details. Once configured, the password will need to be entered at the command line using the `-p` or `--passwd=` option.
`-t <num>, --retries=<num>`	If dsa_control cannot contact the agent service to carry out accompanying instructions, this parameter instructs dsa_control to retry `<num>` number of times. There is a 1 second pause between retries. Not supported on macOS.
`-u <user>:<password>`	Used in conjunction with the `-x` option to specify the proxy's username and password, if the proxy requires authentication. Separate the username and password by a colon (:). For example, `# ./dsa_control -x dsm_proxy://<str> -u <new username>:<new password>`. To remove the username and password, type an empty string (""). For example, `# ./dsa_control -x dsm_proxy://<str> -u <existing username>:""`. If you only want to update the proxy's password without changing the proxy's username, you can use the `-u` option without `-x`. For example, `# ./dsa_control -u <existing username>:<new password>`. Basic authentication only. Digest and NTLM are not supported. Note: Using `dsa_control -u` only applies to the agent's local configuration. No security policy is changed on the manager as a result of running this command.
`-w <user>:<password>`	Used in conjunction with the `-y` option to specify the proxy's user name and password, if the proxy requires authentication. Separate the username and password by a colon (:). For example, `# ./dsa_control -y relay_proxy://<str> -w <new username>:<new password>`. To remove the username and password, type an empty string (""). For example, `# ./dsa_control -y relay_proxy://<str> -w <existing username>:""`. If you only want to update the proxy's password without changing the proxy's username, you can use the `-w` option without `-y`. For example, `# ./dsa_control -w <existing username>:<new password>`. Basic authentication only. Digest and NTLM are not supported. Note: Using `dsa_control -w` only applies to the agent's local configuration. No security policy is changed on the manager as a result of running this command.
`-x dsm_proxy://<str>:<num>`	Configure a proxy between the agent and manager. Provide the proxy's IPv4/IPv6 address or FQDN and port number, separated by a colon (:). Square brackets must surround IPv6 addresses. For example: `dsa_control -x "dsm_proxy://[fe80::340a:7671:64e7:14cc]:808/"`. To remove the address, instead of a URL, type an empty string (""). See also the -u option. For more information, see Connect to Server & Workload Protection via proxy. Note: Using `dsa_control -x` only applies to the agent's local configuration. No security policy is changed on the manager as a result of running this command.
`-y relay_proxy://<str>:<num>`	Configure a proxy between an agent and relay. Provide the proxy's IP address or FQDN and port number, separated by a colon (:). Square brackets must surround IPv6 addresses. For example: `dsa_control -y "relay_proxy://[fe80::340a:7671:64e7:14cc]:808/"`. To remove the address, instead of a URL, type an empty string (""). See also the -w option. For more information, see Connect to relays via proxy. Note: Using `dsa_control -y` only applies to the agent's local configuration. No security policy is changed on the manager as a result of running this command.
`--buildBaseline`	Build the baseline for Integrity Monitoring. Not supported on macOS.
`--scanForChanges`	Scan for changes for Integrity Monitoring. Not supported on macOS.
`--max-dsm-retries`	Number of times to retry an activation. Valid values are 0 to 100, inclusive. The default value is 30.
`--dsm-retry-interval`	Approximate delay in seconds between retrying activations. Valid values are 1 to 3600, inclusive. The default value is 300.
`--autoDetectOSProxy`	A flag to enable/disable auto-detect OS proxy. The flag is controlled by agent configuration in C1WS. Values are 1: Enable, 0: Disable.
`--osProxyResolveTimeout`	The timeout values of the proxy resolver, which can be set in seconds, can be set by dsa_control --osProxyResolveTimeout=<resolveTimeout>;<connectTimeout>;<sendTimeout>;<receiveTimeout>. Note they are separated by semicolons and each timeout value ranges from 10 to 180.
`--pacproxy`	Configures a Proxy Auto-Configuration (PAC) server to resolve the corresponding proxy for the agent. Provide the PAC server's IP address or FQDN, port number, and path of the PAC file. For example: `http://<Host>:<Port>/<PAC file>`To clear the PAC proxy setting, type an empty string (""). The command must assign a certain component type, for example: Set a PAC server for resolving proxy to communicate between Manager `> dsa_control --pacproxy http://pac.example/proxy.pac manager` Set a PAC server for resolving proxy to communicate between Relay `> dsa_control --pacproxy http://pac.example/proxy.pac relay` Set both of the above commands at once: `> dsa_control --pacproxy http://pac.example/proxy.pac manager relay` Clear existing settings:`> dsa_control --pacproxyunpw "" manager relay` For more information, see Connect to relays via proxy. Using dsa_control --pacproxy only applies to the agent's local configuration. No security policy is changed on the manager as a result of running this command. This parameter is supported by the Deep Security Agent for Windows and Linux platforms only.
`--pacproxyunpw`	Used in conjunction with the `--pacproxy` option. It specifies the PAC resolved proxy's user name and password, if the proxy requires authentication. Separate the username and password with a colon (:).To clear the username and password, type an empty string ("").The command must assign a certain component type, for example:Set a PAC server for resolving proxy to communicate between Manager`> dsa_control --pacproxyunpw <username>:<password> manager`Set a PAC server for resolving proxy to communicate between Relay`> dsa_control --pacproxyunpw <username>:<password> relay`Set both of the above commands at once:`> dsa_control --pacproxyunpw <username>:<password> manager relay`Clear existing settings:`> dsa_control --pacproxyunpw "" manager relay`To update the proxy's password without changing the proxy's username, use the `--pacproxyunpw` option without `--pacproxy`:`> dsa_control --pacproxyunpw <existing username>:<new password>`. This parameter is supported by Deep Security Agent for Windows and Linux platforms only. This parameter provides basic authentication only. It does not support Digest and NTLM. Using `dsa_control --pacproxyunpw` only applies to the agent's local configuration. No security policy is changed on the manager as a result of running this command.

Agent-initiated activation ("dsa_control -a")

Enabling agent-initiated activation (AIA) can prevent communication issues between the manager and agents, and simplify agent deployment when used with deployment scripts.

For instructions on how to configure AIA and use deployments scripts to activate agents, see Activate and protect agents using agent-initiated activation and communication.

The command takes the following form:

dsa_control -a dsm://<host>:<port>/

where

<host> could be either the manager's fully qualified domain name (FQDN), IPv4 address, or IPv6 address.
<port> is the agent-to-manager communication port number 443).

For example:

dsa_control -a dsm://dsm.example.com:4120/ hostname:www12 "description:Long Description
                     With Spaces"

dsa_control -a dsm://fe80::ad4a:af37:17cf:8937:4120

Agent-initiated heartbeat command ("dsa_control -m")

You can force the agent to immediately send a heartbeat to the manager.

Like activation, the heartbeat command can also send settings to the manager during the connection.

Parameter	Description	Example	Use during Activation	Use during Heartbeat
`AntiMalwareCancelManualScan`	Boolean. Cancels an on-demand ("manual") scan that is currently occurring on the computer.	`"AntiMalwareCancelManualScan:true"`	no	yes
`AntiMalwareManualScan`	Boolean. Initiates an on-demand ("manual") anti-malware scan on the computer.	`"AntiMalwareManualScan:true"`	no	yes
`description`	String. Sets the computer's description. Maximum length 2000 characters.	`"description:Extra information about the host"`	yes	yes
`displayname`	String. Sets the display name shown in parentheses next to the hostname on Computers. Maximum length 2000 characters.	`"displayname:the_name"`	yes	yes
`externalid`	Integer. Sets the `externalid` value. This value can be used to uniquely identify an agent. The value can be accessed using the legacy SOAP web service API.	`"externalid:123"`	yes	yes
`group`	String. Sets which group the computer belongs to on Computers. Maximum length 254 characters per group name per hierarchy level. The forward slash ("/") indicates a group hierarchy. The `group` parameter can read or create a hierarchy of groups. This parameter can only be used to add computers to standard groups under the main Computers root branch. It cannot be used to add computers to groups belonging to directories (Microsoft Active Directory), VMware vCenters, or cloud provider accounts.	`"group:Zone A web servers"`	yes	yes
`groupid`	Integer.	`"groupid:33"`	yes	yes
`hostname`	String. Maximum length 254 characters. The hostname can specify an IP address, hostname or FQDN that the manager can use to connect to the agent.	`"hostname:www1"`	yes	no
`IntegrityScan`	Boolean. Initiates an integrity scan on the computer.	`"IntegrityScan:true"`	no	yes
`policy`	String. Maximum length 254 characters. The policy name is a case-insensitive match to the policy list. If the policy is not found, no policy will be assigned. A policy assigned by an event-based task will override a policy assigned during agent-initiated activation.	`"policy:Policy Name"`	yes	yes
`policyid`	Integer.	`"policyid:12"`	yes	yes
`relaygroup`	String. Links the computer to a specific relay group. Maximum length 254 characters. The relay group name is a case-insensitive match to existing relay group names. If the relay group is not found, the default relay group will be used. This does not affect relay groups assigned during event-based tasks. Use either this option or event-based tasks, not both.	`"relaygroup:Custom Relay Group"`	yes	yes
`relaygroupid`	Integer.	`"relaygroupid:123"`	yes	yes
`relayid`	Integer.	`"relayid:123"`	yes	yes
`tenantID` and `token`	String. If using agent-initiated activation as a tenant, both `tenantID` and `token` are required. The `tenantID` and `token` can be obtained from the deployment script generation tool.	`"tenantID:12651ADC-D4D5"` and `"token:8601626D-56EE"`	yes	yes
`RecommendationScan`	Boolean. Initiate a recommendation scan on the computer.	`"RecommendationScan:true"`	no	yes
`UpdateComponent`	Boolean. Instructs Server & Workload Protection to perform a security update. When using the `UpdateComponent` parameter on version 12.0+ agents, make sure the relay is also at version 12.0 or later. Learn more.	`"UpdateComponent:true"`	no	yes
`RebuildBaseline`	Boolean. Rebuilds the Integrity Monitoring baseline on the computer.	`"RebuildBaseline:true"`	no	yes
`UpdateConfiguration`	Boolean. Instructs Server & Workload Protection to perform a "Send Policy" operation.	`"UpdateConfiguration:true"`	no	yes

Activate an agent

To activate an agent from the command line, you need to know the tenant ID and password. You can get them from the deployment script.

Procedure

In the top right corner of Server & Workload Protection, click Administration → Updates → Software → Local → Generate Deployment Scripts.
Select your platform.
Select Activate Agent automatically after installation.
In the deployment script, locate the strings for tenantID and token.

Windows

In PowerShell:

& $Env:ProgramFiles"\Trend Micro\Deep Security Agent\dsa_control" -a <manager URL>
                     <tenant ID> <token>

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -a
                     <manager URL> <tenant ID> <token>

Linux

/opt/ds_agent/dsa_control -a <manager URL> <tenant ID> <token>

macOS

cd /Library/Application Support/com.trendmicro.DSAgent/

sudo ./dsa_control -a <manager URL> <tenant ID> <token>

Force the agent to contact the manager

Windows

In PowerShell:

& "\Program Files\Trend Micro\Deep Security Agent\dsa_control" -m

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -m

Linux

/opt/ds_agent/dsa_control -m

macOS

cd /Library/Application Support/com.trendmicro.DSAgent/

sudo ./dsa_control -m

Initiate a manual anti-malware scan

Windows

Procedure

Open a command prompt (cmd.exe) as Administrator.
Enter these commands:

cd C:\Program Files\Trend Micro\Deep Security Agent\

dsa_control -m "AntiMalwareManualScan:true"

Linux

/opt/ds_agent/dsa_control -m "AntiMalwareManualScan:true"

macOS

Not supported.

Create a diagnostic package

If you need to troubleshoot an agent issue, your support provider might ask you to create and send a diagnostic package from the computer. For more detailed instructions, see Create an agent diagnostic package via CLI on a protected computer.

You can produce a diagnostic package for an agent computer through Server & Workload Protection but if the agent computer is configured to use Agent/Appliance Initiated communication, then the manager cannot collect all the required logs. So when Technical Support asks for a diagnostic package, you need to run the command directly on the agent computer.

Reset the agent

This command removes the activation information from the target agent and deactivate it.

Windows

In PowerShell:

& "\Program Files\Trend Micro\Deep Security Agent\dsa_control" -r

In cmd.exe:

C:\Windows\system32>"\Program Files\Trend Micro\Deep Security Agent\dsa_control" -r

Linux

/opt/ds_agent/dsa_control -r

macOS

cd /Library/Application Support/com.trendmicro.DSAgent/

sudo ./dsa_control -r

dsa_query

Not supported on macOS.

You can use the dsa_query command to display agent information.

dsa_query options

dsa_query [-c <str>] [-p <str>] [-r <str]

Parameter	Description
`-p,--passwd <string>`	Authentication password used with the optional agent self-protection feature. Required if you specified a password when enabling self-protection. Note that for some query-commands, authentication can be bypassed directly, in such case, password is not required.
`-c,--cmd <string>`	Execute query-command against the agent. The following commands are supported: `"GetHostInfo"`: to query which identity is returned to the manager during a heartbeat `"GetAgentStatus"`: to query which protection modules are enabled, the status of Anti-Malware or Integrity Monitoring scans in progress, and other miscellaneous information `"GetComponentInfo"`: to query version information of anti-malware patterns and engines `"GetPluginVersion"`: to query version information of the agent and protection modules
`-r,--raw <string>`	Returns the same query-command information as `"-c"` but in raw data format for third party software interpretation.
`pattern`	Wild card pattern

dsa_scan

If you have Administrator privileges on Windows or root access rights on Linux, you can use the dsa_scan command to execute a scan task with specified files or directories, including subdirectories.

dsa_scan allows for concurrent execution of up to ten Deep Security Agent instances.

This command ignores the agent's current scan policy on inclusions and exclusions settings (Policy → Anti-Malware → Inclusion → Manual and Policy → Anti-Malware → Exclusions → Manual).

To use dsa_scan:

Procedure

On Windows:
1. Open the Command Prompt as an Administrator.
2. Change to the agent's installation directory: cd C:\Program Files\Trend Micro\Deep Security Agent\
3. Run the dsa_scan command: dsa_scan <option> where <option> is one or more options described in dsa_scan options.
On Linux, execute the following command:
- sudo /opt/ds_agent/dsa_scan <option> where <option> is one or more options described in dsa_scan options.

The dsa_scan command is not supported on macOS.

dsa_scan options

dsa_scan [--target <str>] [--action <str>] [--log <str>]

Parameter	Description
`--target`	File paths or directories with the delimiter " \| " to separate the input file absolute paths and directories. Example file path and directories: `"c:\user data\|c:\app\config.exe\|c:\workapps"` Example command: `dsa_scan --target "c:\user data\|c:\app\config.exe\|c:\workapps"`
`--action`	Optional Supported actions are `pass`, `delete`, `quarantine`. The current agent scan actions of Manual Scan Configuration are applied if the parameter action is not supplied. Example command: `dsa_scan --action delete --target "c:\user data\|c:\app\config.exe"`
`--log`	Optional The absolute file path of an output log file. If this option is not supplied, the scan result outputs to the command-line console. Example output file: `"c:\temp\scan.log"` Example command: `dsa_scan --target "c:\users\" --log "c:\temp\scan.log"`
`--scanLargeFile`	Optional Enable scan of large files. When large files containing viruses are detected, the scan returns [Infected] and pass action. Note that large files included in the compressed files cannot be scanned. Example command: `dsa_scan --target "c:\user data\|c:\app\config.exe" --scanLargeFile`

dsa_scan output

The following table describes the scan status labels that you would encounter after executing the dsa_scan command:

Label	Description
Skipped	The scan file size limit was reached.
Infected	The file was detected by the scan engine and the action had been taken.
Warning	The file was detected by the scan engine but it encountered issues on the action taken. Check the error code.

The following is an example scan output:

DSA on-demand scan utility

System date/time: 2023/10/12 16:04:10

trace id: 7acf6855-8547-46fc-a58f-9218d108e727

Scanning...

[Skipped] Path: /home/user1/Documents/oversize.zip

[Skipped] Path: /home/user1/Documents/xxx.big

[Infected] Path: /home/user1/Documents/readme, Action: Passed, Infected Name: EICAR, QuarantineID: 0, Error code: 0

[Infected] Path: /home/user1/Documents/sales.doc, Action: Cleaned, Infected Name: BRAIN.A, QuarantineID: 0, Error code: 0

[Warning] Path: /home/user1/Documents/po.ppt, Action: Quarantine, Infected Name: RANSOM.A, QuarantineID: 0, Error code: 5

[Infected] Path: /home/user1/Documents/shipment.zip(po.exe), Action: Deleted, Infected Name: BLKFRI.A, QuarantineID: 0, Error code: 0

25 files scanned, 2 skipped in 10 seconds.

4 files out of 25 were infected.

End of Scan.

Scan exit codes

The dsa_scan command exit codes indicate either the scan success or failure.

Success exit codes

The success exit code indicates the dsa_scan utility completed the scan tasks without detecting any issues or viruses or skipping files, as per the following table:

Exit code	Description	Resolution
0	Scan completed and no malware found.	Scan task completed without malware found.
1	Scan completed with at least one malware found.	Check lines labeled as Infected and Warning in the output.
2	Scan completed, no malware found but some files skipped.	Check lines labeled as Skipped in the output.
3	Scan completed, but at least malware found and some files skipped.	Check lines labeled as Infected, Warning, and Skipped in the output.

Fatal exit codes

If the dsa_scan utility encountered any fatal errors, the dsa_scan broke the scan task and exited with an error code, as per the following table:

Exit code	Description	Resolution
246	The argument string is too long.	The string size limit is 2048 characters. Shorten the target parameter and try again.
247	The Security Platform is shutting down.	The agent is stopping. Try again later.
248	Too many instances.	There cannot be more than ten concurrent `dsa_scan` running instances. Reduce the number of instances.
249	No permission.	The command requires root on Linux and Administrator on Windows. Enable Allow the Agent to Trigger or Cancel a Manual Scan on the scan policy.
250	Manual Scan Configuration is not set.	Configure the Manual Scan setting on the scan policy.
251	AM feature is not enabled.	Enable the AM feature on the scan policy.
252	The platform is not supported.	The `dsa_scan` is not supported on the current OS platform.
253	The agent is not running.	Deep Security Agent is not running. Enable the agent or contact the administrator.
254	Invalid parameters.	The input parameters are incorrect.
255	Unexpected error.	Try again later. If the issue persists, contact the administrator.