DeepSurface: Users

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)

Navigate to Setup > Authentication > Users. This tab is where you set up web console users and configure their permissions. Note that these user accounts are not granted access to the host itself (e.g. SSH or VM console), as those user accounts are configured separately at the host level.

Users

There are five things you can do here:

  1. Add a new user
  2. Delete a user
  3. Edit a user
  4. Generate or Regenerate an API key to allow a user to authenticate and use the DeepSurface API
  5. Configure a user's email digest notification settings

Adding a New User

Click the big '+ User' sign, and you will see a screen similar to the following.

Users

A description of each of the fields:

Managing Notification Preferences

As previously explained in the documentation for Notification Settings, it is also possible to manage a user's notification settings. To manage email subscriptions, simply click on the bell icon for any user and you should see a form like the following:

Users

toggle any of the digests you would like to subscribe to and manage the frequency. For more information, see the Notification Settings Documentation

Managing User API Credentials

To connect to and use the DeepSurface API you must generate an API Key and API Secret for your user account. You can do this when creating a new user or when editing an existing user's settings.

When you click the Generate API Credentials button, an API Key and API Secret will be generated. Before clicking Save Changes, copy the API Secret to a safe location or to your Password Manager. You will not be able to access this API Secret after the user settings modal closes. You will be able to access the API Key at any time. You will need both the API Key and API Secret to connect to the DeepSurface API.

Users

If you misplace your API Credentials, or simply wish to regenerate them, you may do so by clicking the Generate API Credentials button again and clicking OK when warned that previously generated credentials for the user will be invalidated. A new API Key and API Secret will then be generated and be available for use.

It is important to note that regenerating API Credentials causes existing credentials for a user to be immediately disabled, and any automation tools or scripts that use the DeepSurface API will need to be updated.

DeepSurface API Usage

This page assumes that you can reach your DeepSurface console via https://hostname.

Please refer to the Swagger UI documentation page on your DeepSurface console. If you can reach your DeepSurface console at https://hostname, then you can reach the Swagger UI at https://hostname/api/v1/docs and the accompanying OpenAPI JSON specification at https://hostname/api/v1/openapi.json.

One set of API credentials can be generated per user on the user settings page. The full set of instructions for generating these credentials is present at the top of the https://hostname/api/v1/docs page or explained above.

To authenticate to the API programmatically:

  1. POST https://hostname/api/v1/token/oauth2 with payload username=API_KEY&password=API_SECRET where API_KEY is your API Key and API_SECRET is your API Secret.
  2. If authentication was successful, then the body of the response will be a JSON object that contains a key access_token. Extract the value and attach this to your headers as: Authorization:Bearer ACCESS_TOKEN where ACCESS_TOKEN is the access_token value from the response JSON. Use this header for all subsequent requests.

Example shell script using curl:

ACCESS_TOKEN=$(curl -X POST --data 'username=API_KEY&password=API_SECRET' https://hostname/api/v1/token/oauth2 | python3 -c "import json;import sys;print(json.loads(sys.stdin.read())['access_token'])")
curl -X POST --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Content-Type: application/json' 'https://hostname/api/v1/model/$search' -d '{}'

[
   {
      "created" : 1622234277.25352,
      "id" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
      "identifier" : "observed",
      "label" : "Observed",
      "last_analyzed" : 0,
      "modified" : 1622238770.71588,
      "parent" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
      "risk" : 0
   },
   {
      "created" : 1622234277.25352,
      "id" : "4dd69d13-c9da-4e4f-b039-07c6e2594066",
      "identifier" : "base",
      "label" : "Base",
      "last_analyzed" : 1624731840.36375,
      "modified" : 1624655584.96631,
      "parent" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
      "risk" : 0
   }
]