Command-line basics

You can use the local command-line interface (CLI) to order agents and Workload Security to perform actions. In addition, the CLI can be used to configure some settings and display system resource usage.

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

dsa_control

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

Note the following:

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

On Windows:

• Open a Command Prompt as an Administrator.
• Change to the agent's installation directory:
  cd C:\Program Files\Trend Micro\Deep Security Agent\
• Run the dsa_control command:
  dsa_control <option>
  where <option> is replaced with options described in dsa_control options.

On Linux:

• Execute the following command:

sudo /opt/ds_agent/dsa_control <option>
where <option> is replaced with options described in dsa_control options.

On macOS:

• Open a Terminal window as an Administrator.
• Change to the agent's installation directory:
  cd "/Library/Application Support/com.trendmicro.DSAgent"
• Run the dsa_control command:
  dsa_control <option>
  where <option> is replaced with 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 Workload Security during activation or heartbeat...]

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

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

Activate an agent

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

1. In the top right of Workload Security, click Support > Deployment Scripts.
2. Select your platform.
3. Select Activate Agent automatically after installation.
4. 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

1. Open the command prompt (cmd.exe) as an Administrator.

2. Enter the following 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 details, see Create an agent diagnostic package via CLI on a protected computer.

You can produce a diagnostic package for an agent computer through Workload Security but if the agent computer is configured to use Agent / Appliance Initiated communication, then the manager cannot collect all the required logs. Therefore, 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

You can use the dsa_query command to display agent information.

Note that this command is not supported by macOS.

dsa_query options

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

Check CPU usage and RAM usage

Windows

Use the Task Manager or procmon.

Linux

top

Check that ds_agent processes or services are running

Windows

Use the Task Manager or procmon.

Linux

ps -ef|grep ds_agent

Restart an agent on Linux

service ds_agent restart

or

/etc/init.d/ds_agent restart

or

systemctl restart ds_agent

Some actions require either a -tenantname parameter or a -tenantid parameter. If execution problems occur when you use the tenant name, try the command using the associated tenant ID.

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.

Up to ten dsa_scan commands can be concurrently executed on one Deep Security Agent instance.

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:

On Windows:

• Open the Command Prompt as an Administrator.
• Change to the agent's installation directory:
  cd C:\Program Files\Trend Micro\Deep Security Agent\
• 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>]

dsa_scan output{#Scanoutput}

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

The following is an example scan output:

C1WS 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, Malware Name: EICAR, QuarantineID: 0, Error code: 0
[Infected] Path: /home/user1/Documents/sales.doc, Action: Cleaned, Malware Name: BRAIN.A, QuarantineID: 0, Error code: 0
[Warning] Path: /home/user1/Documents/po.ppt, Action: Quarantine, Malware Name: RANSOM.A, QuarantineID: 0, Error code: 5
[Infected] Path: /home/user1/Documents/shipment.zip(po.exe), Action: Deleted, Spyware 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{#Exitcodes}

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

Success exit codes

The success exit code is displayed when the dsa_scan utility completed the scan tasks without any issues detected or with a virus found or having skipped some files, as per the following table:

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: