Command-Line Utilities

Deep Security Agent

Vulnerability Protection Agent

dsa_control

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 heartbeat port (default 4120).
• -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:4118/'
• -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.
• -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 Vulnerability ProtectionDeep Security 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 Vulnerability ProtectionDeep Security Manager (or one of its Manager Nodes) can send instructions to and communicate with the Agent.

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

Vulnerability ProtectionDeep Security 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 a Vulnerability ProtectionDeep Security installation and you want to write a script to automate the activation process.

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

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

where:

• -a is the command to activate the Agent , and
• dsm://managerurl:4120/ is the parameter that points the Agent to the Vulnerability ProtectionDeep Security Manager. ("managerurl" is the URL of the Vulnerability ProtectionDeep Security Manager, and "4120" is the default Agent-to-Manager communication port.)

The Manager URL 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 Vulnerability ProtectionDeep Security Manager through a proxy server.

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

1. In the Vulnerability ProtectionDeep 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 Vulnerability ProtectionDeep Security Manager through a proxy server:

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 Vulnerability ProtectionDeep 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 Vulnerability ProtectionDeep Security 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 Vulnerability ProtectionDeep Security 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.

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 Vulnerability ProtectionDeep Security 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

Vulnerability Protection Manager

dsm_cvp_c

Usage

dsm_cvp_c -action actionname