DeepSurface: DeepSurface Commands

Documentation
Installation Guide
Overview
Let DeepSurface Host For You
Getting Started
System Requirements
Self Hosted Quick Start - Installing to Cloud Platforms
Self Hosted - Installation Using an OVA
Registration, Package Installation, and Initialization
First Steps After Initialization of the Console
Deployment Options
Main and Subordinate Consoles
Agent-Based Deployment
User Managed Scan Deployment
Credentialed Scanning Deployment
Mixed Environment
Deployment Tools
Active Directory Group Policy
Microsoft Endpoint Configuration Manager (part of InTune)
Tanium Deploy
HCL BigFix
Ivanti
Virtual Machines
VMWare
Virtual Box
VirtualBox Guest Additions
AWS EC2 (BYOL)
AWS EC2 (Usage Based)
Azure Cloud
Google Cloud
Additional Items to Consider
Main Console Server Certificates
LDAP
TOFU
Clock Sync
DeepSurface Commands
Multiple Vulnerability Sources
API Documentation
User Guide
Reporting
Dashboards
Exports
Risk Insight
Hosts
Patches
Vulnerabilities
Vulnerability Instances
Users
Remediation Workflow Manager
Plans
Settings
Integrations
Workflow
Exporting
Accepted Risk Plans
Accepted Risk Workflow
Explore
Model
Paths
Activity
Tasks
Configuration Alerts
Scan Logs
Notification Settings
Scanning
Status
Agents
User Managed
Credentialed Scanning Settings
Credentials
Scan Groups
General Settings
Cloud Scanning
Network Connectivity
Subordinates
Vulnerability Sources
Setup
Sensitive Assets: Polices
Sensitive Assets: Manual
Admin Settings
SMTP Settings
Certificates
Outbound Proxy
Authentication Providers
Users
Tags
Integrations Guide
Vulnerability Sources
CrowdStrike Spotlight
SentinelOne
Carbon Black Cloud
Microsoft Defender for Endpoint
Wazuh
Lansweeper Cloud
Nessus API
Tenable.io API
Security Center/Tenable.sc API
Rapid7 InsightVM API
Qualys API
Nozomi Guardian
Eclypsium
AWS Inspector
Remediation
Jira Software
Tanium (BETA)
Authentication Providers
LDAP (Active Directory)
SAML (Azure Active Directory)
SAML (Google)
SAML (Okta)
PAM
CyberArk
Delinea (Thycotic)
Microsoft LAPS
Security Guide
Firewall Configuration
Base Network Requirements
Agent Network Requirements
Credentialed Scanning Network Requirements
API Network Requirements
How DeepSurface Scans Work
Domain (LDAP) Scanning
Host Scanning Routine
Reasons for the Administrative Access Requirement
Endpoint Protection Considerations
Other Items
Scope of Data Storage and Retention
IPS/IDS Considerations
Logging
Resetting the DSADMIN password
Product Information
Changelogs
Open source Licenses
End User License Agreement (EULA)

When you SSH into the DeepSurface appliance, there are some helpful security-related commands that can be executed from the command line.

Installation Script Reference

When configuring the DeepSurface VirtualMachine (VM), there are a number of scripts run, including scripts you may want to run manually at some point. Here is documentation of those scripts, which are located in /usr/bin and /usr/sbin.

Note: all scripts must be run as "sudo [scriptname]" Also Note: some of the scripts only apply to OVA VMs (not AWS or Azure VMs). These will be noted.

This document covers the following scripts:

Scripts in /usr/bin

deepsurface-first-login
deepsurface-configure-network
deepsurface-install
deepsurface-manage-users

Scripts in /usr/sbin

deepsurface-register-as-subordinate
deepsurface-manage-certificates

deepsurface-first-login

This script is automatically run the first time you login to the DeepSurface virtual machine. It only applies to OVA VMs. It does the following:

Sets up a new password for the virtual machine admin user (dsadmin)
Restarts the VM network interfaces
Allows you to reconfigure a network interface to be either Automatic (DHCP) or Manual (Static access)

deepsurface-configure-network

This script also only applies to OVA VMs. It is normally called automatically by deepsurface-first-login. It is used to restart the virtual machine network interfaces. It steps through each of the network interfaces and allows you to set its IP address, either automatically (DHCP) or manually with a static IP address.

deepsurface-install

This script is intended to be run once during the initial install/configuration of the DeepSurface Virtual Machine. After this script has been successfully run, future invocations will result in an error such as the one show below.

error

deepsurface-manage-users

Normally, all user management is handled through the DeepSurface web console. You can use this script if for some reason you get locked out.

usage: deepsurface-manage-users [-h] {create, change-password, modify} ...

positional arguments: {create, change-password, modify}

Permitted operations create Add a new user account change-password Reset the password of he specified user modify Modify certain attributes of a user

positional arguments: {key, value, username} key which account attribute to modify, one of [username, given name, family name, authentication provider] value new value of "key" username user account to be modified

optional arguments: -h, --help show this help message

deepsurface-register-as-subordinate

Use this script if you need to re-register a subordinate DeepSurface scanner. For example, you might use this if an IP address changed.

usage: deepsurface-register-as-subordinate [-h] [--debug] [registration_config] [console_server] [console_server_port]

positional arguments: registration_config Registration configuration file path. console_server Host name or IP address of DeepSurface Console server. console_server_port TCP port number of console server websocket service. Default is 44305. If port 44305 is not accessible to your subordinate, consider opening it. It is also possible to use port 443, since the websocket service is also available there, but this requires exposing the full web console UI to more hosts than strictly necessary. Any port can be specified here, which might be helpful if your network is configured to do NAT/port forwarding or something similar, but this isn't common.

optional arguments: -h, --help show this help message and exit --debug Enable verbose output for debugging purposesß

deepsurface-manage-certificates

Use this script to generate or import certificates for use by the DeepSurface Web Management Console when communicating with your (or another administrator's) web browser. (This script is not designed to manage certificates encountered during scanning or any other situation where DeepSurface is acting as an SSL/TLS client.)

Warning: After installing a new certificate, the DeepSurface console will be restarted, which will terminate any jobs currently running, including scans in progress data imports, or analysis jobs.

usage: deepsurface-manage-certificates [-h] [--output-cert-path OUTPUT_CERT_PATH]
                                       [--output-key-path OUTPUT_KEY_PATH]
                                       [-r] [-y] [-n]
                                       {generate,import} ...
positional arguments:{generate,import}
generate             Generates an insecure self-signed certificate (and private key)
                     DeepSurface does this once during the install process so it's
                     unlikely you will have a need for this option.
import               Import a certificate and private key
optional arguments:
-h, --help              show this help message and exit
--output-cert-path      OUTPUT_CERT_PATH destination to save certificate at (default: /etc/deepsurface/certificates/fullchain.pem)
--output-key-path       OUTPUT_KEY_PATH destination to save private key at (default: /etc/deepsurface/certificates/privkey.pem)
-r, --do-not-restart    do not restart DeepSurface after installing certificate
-y, --overwrite         automatically overwrite key and certificate
-n, --do-not-overwrite  never overwrite the key or certificate

Each sub-command also has usage documentation. For instance, by running sudo deepsurface-manage-certificates import -h you'll see something similar to:

usage: deepsurface-manage-certificates import [-h] [--certificate-type CERTIFICATE_TYPE]
                                              [--certificate-format CERTIFICATE_FORMAT] [--key-format KEY_FORMAT]
                                              [--raw-passphrase RAW_PASSPHRASE]
                                              cert_path [key_path]
positional arguments:
cert_path            path to the certificate (.pem, .der, .p7b, .cer, .crt, .der, .pfx)
key_path             path to the PEM/DER private key (.pem, .der)
optional arguments:
-h, --help                                show this help message and exit
--certificate-type CERTIFICATE_TYPE       type of the certificate (PKCS#12, PKCS#7, PEM)
--certificate-format CERTIFICATE_FORMAT   format of the certificate (PEM, DER)
--key-format KEY_FORMAT                   format of private key (PEM, DER)
--raw-passphrase RAW_PASSPHRASE           passphrase to decrypt the PEM private key (deprecated: tool will ask through stdin)

As indicated in the import command's usage statement, several different certificate formats are accepted. For some formats, the server key and certificate are included in the same file, in which case only a single file is specified. In other formats, the two are provided as separate files, in which case the certificate is the first file argument.

The import command should automatically detect the specific certificate type and key format, but if this fails for some reason, you may also attempt to specify these explicitly with the optional arguments.

If the private key is encrypted with a passphrase, you will need to provide this information when prompted.

For background information on HTTPS certificates see the certificate reference page for a brief overview.