Command-line utilities

You can instruct Agents and the Deep Security Manager to perform a number of actions from the local command line. This article is meant to be a reference article.

For an article that gives you some basic command-line task instructions, refer to Command-line basics for agent tasks.

-s <num>, --selfprotect=<num> enable self-protection on the Agent by preventing local end-users from uninstalling, updating, stopping, or otherwise controlling the Agent. Command-line instructions must include the authentication password when self-protection is enabled. (1: enable, 0: disable). This is a Windows-only feature.

In this article:

Deep Security Agent

dsa_control examples

You can use dsa_control -m to initiate an anti-malware scan. The following commands will force an immediate heartbeat and let the Manager know to initiate the scan.

In Windows:

  • Open a Command Prompt as Administrator
  • cd C:\Program Files\Trend Micro\Deep Security Agent\
  • dsa_control -m "AntiMalwareManualScan:true"

In Linux:

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

Usage

dsa_control [-a <str>] [-b] [-c <str>] [-d] [-g <str>] [-s <num>] [-m] [-p <str>] [-r] [-R <str>] [-t <num>] [--buildBaseline] [--scanForChanges] [Additional keyword:value data to send to Manager during activation/heartbeat...]

  • -a <str>, --activate=<str> Activate agent with Manager at specified URL. URL format must be 'dsm://hostOrIp:port/' where port is the Manager's discovery and heartbeat port number.
  • -b, --bundle Create update bundle.
  • -c <str>, --cert=<str> Identify the certificate file.
  • -d, --diag Generate an agent diagnostic package.
  • -g <str>, --agent=<str> Agent URL. Defaults to 'https://localhost:port/' where port is the Manager's listening port number.
  • -m, --heartbeat Ask the Agent to contact the Manager now.
  • -p <str>, --passwd=<str> Authentication password. Use "*" to prompt for password.
    Use the "-p" parameter on its own and enter the password immediately following in unobscured text. Use the "-p" parameter followed by a "*" to be prompted for the password after you hit enter. Your typed password will be obscured with "*" as you type.
  • -r, --reset Reset agent configuration.
  • -R <str>, --restore=<str> Restore quarantined file. (Deep Security)
  • -s <num>, --selfprotect=<num> enable self-protection on the Agent by preventing local end-users from uninstalling, stopping, or otherwise controlling the Agent. Command-line instructions must include the authentication password when self-protection is enabled. (1: enable, 0: disable). This is a windows-only feature.
    In Deep Security 9.0 and earlier, this option was -H <num>, --harden=<num>
  • -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 one second pause between retries.
  • --buildBaseline Build baseline for Integrity Monitoring
  • --scanForChanges Scan for changes for Integrity Monitoring

Agent-Initiated Activation ("dsa_control -a")

An Agent installed on a computer needs to be activated before the Manager can assign Rules and Policies to protect the computer. The activation process includes the exchange of unique fingerprints between the Agent and the Manager. This ensures that only one Manager (or one of its Manager Nodes) can send instructions to and communicate with the Agent.

You can manually activate an Agent from the Manager by right-clicking on the computer in the Computers screen and selecting Actions > Activate/Reactivate.

Agents can initiate the activation process using a locally-run command-line tool. This is useful when a large number of computers will be added to an installation and you want to write a script to automate the activation process.

For Agent-Initiated Activation to work, the Allow Agent-Initiated Activation option must be enabled on the Administration > System Settings > Agents tab.

The minimum activation instruction contains the activation command and the Manager's URL (including the port number):

dsa_control -a dsm://[hostname]:[port]/

where:

  • -a is the command to activate the Agent , and
  • dsm://hostname:port/ is the parameter that points the Agent to the Manager. ("hostname" is the Manager's domain name, IP4 address, or IPv6 address, and "port" is the Agent-to-Manager communication port number.) For example:

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

The hostname is the only required parameter for the activation command. Additional parameters are also available (see the table of available parameters below). 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 you can enter but the key:value pairs must be separated from each other by a space. For example:

dsa_control -a dsm://sec-op-john-doe-3:4120/ hostname:ABCwebserver12 "description:Long Description With Spaces"

(Quotation marks are only required if your value includes spaces or special characters.)

Agent-Initiated Activation Over a Private Network Via Proxy

Agents on a private network can perform agent-initiated communication with a Manager through a proxy server.

To allow Agent-Initiated Activation over a private network using a proxy server:

  1. In the Deep Security Manager, go to Administration > System Settings > Agents page.
  2. In the Agent-Initiated Activation area:
    • Select Allow Agent-Initiated Activation.
    • Select Allow Agent to specify hostname.
    • In the If a computer with the same name exists list, select "Activate a new Computer with the same name".
  3. Click Save.

Use the following command-line options to instruct the Agent to communicate with the Manager through a proxy server:

SyntaxNotes
dsa_control -x "dsm_proxy://<proxyURL>/"Sets the address of the proxy server which the Agent uses to communicate with the Manager.
dsa_control -x ""Clears the proxy server address.
dsa_control -u "<username:password>"Sets the proxy username and password.
dsa_control -u ""Clears the proxy username and password.
Examples
dsa_control -x "dsm_proxy://172.21.3.184:808/"Proxy uses IPv4.
dsa_control -x "dsm_proxy://winsrv2k3-0:808/"Proxy uses hostname.
dsa_control -x "dsm_proxy://[fe80::340a:7671:64e7:14cc]:808/"Proxy uses IPv6.
dsa_control -u "root:Passw0rd!"Proxy authentication is "root" and password is "Passw0rd!" (basic authentication only, digest and NTLM are not supported).

When used in the context of Agent-initiated activation, the proxy commands must be issued first, followed by the Agent-initiated activation commands. The following example shows a complete sequence for setting a proxy address, setting proxy credentials, and activating the Agent:

dsa_control -x "dsm_proxy://172.21.3.184:808/"
dsa_control -u "root:Passw0rd!"
dsa_control -a "dsm://seg-dsm-1:4120/"
Required Setting in Deep Security Manager

Agent-Initiated Heartbeat command ("dsa_control -m")

The Agent-Initiated heartbeat command will instruct the Agent to perform an immediate heartbeat operation to the Manager. Although this may be useful on its own, like the activation command above, the heartbeat command can be used to pass along a further set of parameters to the Manager.

The following table lists the parameters that are available to the activation and heartbeat commands. Note that some parameters can only be used with either the activation or heartbeat exclusively.

KeyDescriptionExamplesCan be performed during ActivationCan be performed after activation during HeartbeatValue FormatNotes
description Sets description value. "description:Extra information about the host"yesyesstringMaximum length 2000 characters.
displayname Sets displayname value. (Shown in parentheses next to the hostname.) "displayname:the_name"yesyesstringMaximum length 2000 characters.
externalidSets the externalid value"externalid:123"yesyesintegerThis value can used to uniquely identify an Agent. The value can be accessed using the SOAP Web Service API.
groupSets the computers page Group the computer belongs in. "group:Zone A/Webservers"yesyesstringMaximum 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 (MS Active Directory), VMware vCenters, or Cloud Provider accounts.
groupid

"groupid:33"yesyesinteger

hostname

"hostname:ABWebServer1"yesnostringMaximum length 254 characters.

The hostname can specify an IP address, hostname or FQDN that is best used to contact the computer in the Computers list in the Manager.
policy

"policy:Policy Name"
yesyesstringMaximum 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.
policyid

"policyid:12"yesyesinteger

relaygroupLinks the computer to a specific Relay Group."relaygroup:Custom Relay Group"
yesyesstringMaximum 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.
relaygroupid

"relaygroupid:123"yesyesinteger

relayid

"relayid:123"yesyesinteger

tenantID and tenantPassword

"tenantID:12651ADC-D4D5"

and

"tenantPassword:8601626D-56EE"
yesyesstringIf using Agent-Initiated Activation as a Tenant, both tenantID and tenantPassword are required. The tenantID and tenantPassword can be obtained from the deployment script generation tool.
RecommendationScanInitiate a Recommendation Scan on the computer."RecommendationScan:true"noyesboolean

UpdateComponentInstructs the Deep Security Manager to perform a Security Update operation."UpdateComponent:true"noyesboolean

RebuildBaselineRebuilds the Integrity Monitoring baseline on the computer."RebuildBaseline:true"noyesboolean

UpdateConfigurationInstructs the Deep Security Manager to perform a "Send Policy" operation."UpdateConfiguration:true"noyesboolean

AntiMalwareManualScanInitiates an Anti-Malware Manual Scan on the computer."AntiMalwareManualScan:true"noyesboolean

AntiMalwareCancelManualScanCancels an Anti-Malware Manual Scan currently underway on the computer."AntiMalwareCancelManualScan:true"noyesboolean

IntegrityScanInitiates an Integrity Scan on the computer."IntegrityScan:true"noyesboolean

RebuildBaselineRebuilds the Integrity Monitoring baseline on the computer."RebuildBaseline:true"noyesboolean

dsa_query

The dsa_query tool provides the following information:

  • License-status of each component
  • Scan progress
  • Version information of Security Update components

Usage

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

  • -p,--passwd <string>: authentication password. Required when agent self-protection is enabled.
    For some query-commands, authentication can be bypassed directly, in such case, password is not required.
  • -c,--cmd <string>: execute query-command against ds_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 and other miscellaneous information
    • "GetComponentInfo": query version information of Anti-Malware patterns and engines
  • -r,--raw <string>: returns the same query-command information as "-c" but in raw data format for third party software interpretation.

pattern: wildchar pattern to filter result, optional.

Example:
dsa_query -c "GetComponentInfo" -r "au" "AM*"

Deep Security Manager

Applies to on-premise Deep Security software installations only

dsm_c

Usage

dsm_c -action actionname

Action Name DescriptionUsage
changesettingChange a settingdsm_c -action changesetting -name NAME -value VALUE [-computerid COMPUTERID] [-computername COMPUTERNAME] [-policyid POLICYID] [-policyname POLICYNAME] [-tenantname TENANTNAME]
viewsettingView a setting valuedsm_c -action viewsetting -name NAME [-computerid COMPUTERID] [-computername COMPUTERNAME] [-policyid POLICYID] [-policyname POLICYNAME] [-tenantname TENANTNAME]
createinsertstatementsCreate insert statements (for export to a different database)dsm_c -action createinsertstatements [-file FILEPATH] [-generateDDL] [-databaseType sqlserver|oracle] [-maxresultfromdb count] [-tenantname TENANTNAME]
diagnosticCreate a diagnostic package for the systemdsm_c -action diagnostic
fullaccessGive an administrator the full access roledsm_c -action fullaccess -username USERNAME [-tenantname TENANTNAME]
resetcountersReset counter tables (resets back to an empty statedsm_c -action resetcounters [-tenantname TENANTNAME]
reseteventsReset the events tables (resets back to an empty state)dsm_c -action resetevents -type all|am|wrs|fw|dpi|im|li[-tenantname TENANTNAME]
setportsSet Deep Security Manager port(s)dsm_c -action setports [-managerPort port] [-heartbeatPort port]
trustdirectorycertTrust the certificate of a directorydsm_c -action trustdirectorycert -directoryaddress DIRECTORYADDRESS -directoryport DIRECTORYPORT [-username USERNAME] [-password PASSWORD] [-tenantname TENANTNAME]
unlockoutUnlock a User accountdsm_c -action unlockout -username USERNAME [-newpassword NEWPASSWORD] ,[-tenantname TENANTNAME]
addregionAdd a private cloud provider regiondsm_c -action addregion -region REGION -display DISPLAY -endpoint ENDPOINT
listregionsList private cloud provider regionsdsm_c -action listregions
removeregionRemove a private cloud provider regiondsm_c -action removeregion -region REGION
addcertAdd a trusted certificatedsm_c -action addcert -purpose PURPOSE -cert CERT
listcertsList trusted certificatesdsm_c -action listcerts [-purpose PURPOSE]
removecertRemove a trusted certificatedsm_c -action removecert -id ID