Command-line basics

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.

Agent URL. Defaults to:

https://localhost:<port>/

where <port> is the manager's listening port number.

The authentication password that you might have configured in Deep Security Manager previously. See Configure self-protection through Deep Security Manager 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 *

Enable the 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 on Windows. This is a Windows-only feature.

Although dsa_control lets you enable self-protection, it does not allow you to configure an associated authentication password. You need Deep Security Manager for that. See Configure self-protection through Deep Security Manager for details. Once configured, the password must be entered at the command line using the -p or --passwd= option.

In Deep Security 9.0 and earlier, this option was -H <num>, --harden=<num>

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.

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.

Used in conjunction with the -y 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 -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 that 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.

See also the -u option.

For more information, see Connect to Deep Security Manager via proxy.

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

See also the -w option.

For more information, see Connect to Deep Security Relays via proxy.

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

Boolean.

Cancels an on-demand ("manual") scan that is currently occurring on the computer.

Boolean.

Initiates an on-demand ("manual") anti-malware scan on the computer.

String.

Sets the computer's description. Maximum length 2000 characters.

String.

Sets the display name shown in parentheses next to the hostname on Computers. Maximum length 2000 characters.

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.

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.

Integer.

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.

Boolean.

Initiates an integrity scan on the computer.

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

A policy assigned by an event-based task overrides a policy assigned during agent-initiated activation.

Integer.

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

This does not affect relay groups assigned during event-based tasks. Use either this option or event-based tasks, not both.

Integer.

Integer.

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.

Boolean.

Initiate a recommendation scan on the computer.

Boolean.

Instructs Deep Security Manager to perform a security update.

When using the UpdateComponent parameter on Deep Security Agent 12.0 or later, make sure the Deep Security Relay is also at version 12.0 or later. Learn more.

Boolean.

Rebuilds the Integrity Monitoring baseline on the computer.

Boolean.

Instructs Deep Security Manager to perform a "Send Policy" operation.

Authentication password used with the optional agent self-protection feature. Required if you specified a password when enabling self-protection.

For some query-commands, authentication can be bypassed directly, in which case password is not required.

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
• “GetProxyInfo”: to query proxy information of all proxy types

1. Wild card pattern to filter result. Optional.

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

1. As an option to print more detailed content.

Example:
dsa_query -c GetProxyInfo details=true

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"

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"

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"

Add an Azure endpoint to the allowed endpoint list. This command requires an ENDPOINT parameter that must be specified in the format https://<fqdn>. The allowed endpoint list is used to validate endpoints that are specified when adding an Azure account to Deep Security Manager. If you do not specify any endpoints, then only the default built-in endpoints are allowed.

For more on adding an Azure account, see Add a Microsoft Azure account to Deep Security.

Related dsm_c options:

listazureendpoint and removeazureendpoint

Change a setting.

You must back up your deployment before running the command. Do not use this command unless you understand the effects of the setting. Misconfigurations can make your service unavailable or your data unreadable. Usually, you only use this command if requested by your technical support provider telling you which setting NAME to change. Sometimes this command is required during regular use, in which case the setting is described in that section of the documentation, such as masterkey.

Create a diagnostic package for the system.

If needed, you can Increase verbose diagnostic package process memory.

List all allowed Azure endpoints.

Related dsm_c options:

addazureendpoint and removeazureendpoint

Generate, import, export, or use a custom master key to encrypt the:

• database password
• keystore password
• personal data

If a custom master key is not configured, Deep Security uses a hard-coded seed.

If you already configured a master key during a new install, the installer has completed this setup for you. If you skipped master key creation, and want to configure one now, start with the commands in step 1. Enter all commands in order. To generate a new master key, start with the commands in step 1 and enter all commands in order.

If you configured the master key during an upgrade, back up your database and properties files, and then start with the commands in step 4.

1. dsm_c -action masterkey -subaction [generatekmskey -arn AWSARN | generatelocalkey] — Generate the master key using either the Amazon Resource Name (ARN) of a Key Management System (KMS) key, or a local environment variable named LOCAL_KEY_SECRET. If using the local environment variable on a multi-node Deep Security Manager, it must be configured on all nodes at the system-level (not user-level), and must include, at a minimum:

   • a capital letter
   • a lower cased letter
   • a number
   • a special character
   • 8-64 characters

   Permissions and reliable network access to KMS or LOCAL_KEY_SECRET are required by Deep Security Manager if you configure the master key. The manager uses them to encrypt and decrypt the master key during use. If they temporarily cannot be reached, Deep Security Manager is unable to decrypt required data and the service is unavailable. Symptoms can include intermittent event logs and alerts for restart failures and various other errors.

2. dsm_c -action masterkey -subaction export -file FILEPATH — Export the master key to a password-encrypted file for backup. You will be prompted for the password.

   You must back up the master key by exporting it to a safe location. If the master key is lost or destroyed and you do not have a backup, all encrypted data becomes unreadable. If that happens, you must reinstall Deep Security Manager, all relays, and all agents. If the key is stolen, security of your Deep Security deployment is compromised. Some compliance regulations such as General Data Protection Regulation (GDPR) in Europe may require you by law to notify law enforcement of personal data breaches within 72 hours, and noncompliance can result in fines. Consult your lawyer for more information.

   To verify your backup for disaster recovery, you can test it by importing the master key:

   dsm_c -action masterkey -subaction [importkmskey -file FILEPATH -arn AWSARN | importlocalkey -file FILEPATH] — Import a backup of the master key. This can be useful either for disaster recovery of a corrupted key, or to migrate the master key to another KMS. Before you run this command, you must delete the existing master key from the primary tenant (T0) database.

   For example, you might enter the SQL command:

   delete from systemsettings where uniquekey = 'settings.configuration.keyEncryptingKey'

3. dsm_c -action masterkey -subaction encryptproperties — Use the master key to encrypt keystore and database passwords in dsm.properties and configuration.properties. You must restart Deep Security Manager for this setting to take effect.

4. dsm_c -action masterkey -subaction encrypttenantkey -tenantid [all | TENANTNUM] — If you have a multi-tenant deployment, use the master key to encrypt existing tenant key seeds. Tenant key seeds derive subkeys that you can use in the next step. You can execute this command multiple times (this does not apply additional layers of encryption to an already encrypted seed).

   Optionally, to apply encryption only to new tenants while slowly rolling out to each existing tenant, you can start by executing the following command:

   dsm_c -action changesetting -name settings.configuration.encryptTenantKeyForNewTenants -value true

   If you only have one (primary) tenant in the environment, tenantid can be either all or 0.

5. dsm_c -action masterkey -subaction encryptpii -tenantid [all | TENANTNUM] — If you have a multi-tenant deployment, use each tenant's key to encrypt their administrators' and contacts' personal data in the database. If you only have one (primary) tenant in the environment, tenantid can be either all or 0.
6. dsm_c -action masterkey -subaction encryptdsmprivatekey -tenantid [all | TENANTNUM] — Use the master key to encrypt the private key used for activation and other agent-manager communications via SSL/TLS. If you only have one (primary) tenant in the environment, tenantid can be either all or 0.
7. dsm_c -action masterkey -subaction isconfigured — Check to see whether or not the master key was created.

Remove an Azure endpoint from allowed endpoint list.

You can only remove endpoints added using the dsm_c -action addazureendpoint command. Default built-in endpoints cannot be removed.

Related dsm_c options:

addazureendpoint and listazureendpoint

Remove a trusted certificate.

dsm_c -action upgradetasks [-listtasksets] [-listtasks -taskset UPGRADE_TASK_SET [-force]] [-tenantlist] [-tenantsummary] [-run -taskset UPGRADE_TASK_SET [-force] [-filter REGULAR_EXPRESSION]] [-showrollbackinfo -task TASKNAME] [-purgehistory [-task TASKNAME]] [-showhistory [-task TASKNAME]] [-tenantname TENANTNAME | -tenantid TENANTID]

• [-listtasksets]: List sets of tasks for the system as a whole or the tenant specified by -tenantname.
• [-listtasks -taskset UPGRADE_TASK_SET [-force]]: List the modifications to run. Include -force to list all tasks.
• [-tenantlist]: Shows the version of outstanding upgrade actions for the specified tenant.
• [-tenantsummary]: Shows a summary of the tenants that are not up to date.
• [-run -taskset UPGRADE_TASK_SET [-force] [-filter REGX]]: Run the upgrade actions for each tenant. Include -force to run all tasks even if they have already been done. Include -filter to limit the actions to a regular expression.
• [-showrollbackinfo -task TASKNAME]: Shows rollback information for the specified task. One tenant or all tenants can be shown.
• [-purgehistory [-task TASKNAME]]: Purge the history for the tenant specified and the task specified. If no tenant or task is specified, all items are matched.
• [-showhistory [-task TASKNAME]]: Show the history for the tenant specified and the task specified. If no tenant or task specified, all items are matched.