DeepSurface: Integrations
DocumentationInstallation 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)
The Remediation > Integrations interface allows you to configure third-party ticketing integrations. Currently DeepSurface supports a direct integration with Atlassian Jira and a generic "Ticketing via Email". To configure either, click the new integration button in the top right to get started.
Atlassian Jira Configurations
To configure DeepSurface to work with Atlassian Jira, you must have the following things prepared:
- An already configured Jira installation (either cloud-based, or on prem)
- Access to a Jira user's credentials that is part of the jira-software-users group
- An already configured Jira project that DeepSurface can export the tickets to.
If you have all of those things ready to go, select the "Atlassian Jira" option from the dropdown and fill out the form. The form is filled out in 2 steps, give this integration a friendly name to remember it by and then enter the url of your organization. If your team uses a cloud-hosted Jira installation, the URL will typically resemble: https://YOUR-COMPANY.atlassian.net/. Proceed to enter the username and API key for the given user and once all fields are completed, you will see a button appear that you can click to fetch the projects. Once clicked, DeepSurface will attempt to call the Jira API and return a list of available projects within your Jira organization. If all information was entered correctly, you should then be able to choose a project from the now visible select field. At this point, your Jira integration is fully configured and you will be able to export tickets from remediation, however we encourage you to optionally now map the DeepSurface users to the Jira users that are part of the integration we just finished configuring. If you choose to, click "Save and Map Users" to be taken to the user mapping interface. Here you will see all of the DeepSurface users in one column, and an empty column on the right for the user they are mapped to. For each DeepSurface user, you can search for a Jira user and select one to map the given user to. Once mapped, DeepSurface can then know who to assign a ticket to as it exports tasks and creates tickets for Jira users. Mappings can be edited or removed at anytime from this interface or from the Setup > Authentication > Users area by clicking on a user and updating a given user on a one-by-one basis.
Ticketing via Email Configurations
If you do not use Jira in your organization, you may want to instead handle ticketing via a centralized email address. DeepSurface plans to support many third party ticketing options in the future, but many either do not have an API or are not on our current roadmap. For this reason, you can configure a ticketing integration that simply sends all tickets to one centralized email address. Configuring this type of integration is very straightforward, simply give this integration a memorable name, fill in the destination email address, and then optionally edit the subject prefix that will be present in the emails that DeepSurface sends out. Important note in order for DeepSurface to send emails, the system must be have SMTP settings correctly configured in the Setup > General Settings > SMTP Settings section.
Below you can see what the main ticketing section would look like if you have a correctly configured Jira and Email integration.
Once at least one ticketing integration has been configured, you will now be able to export remediation tasks as tickets. Before returning, to a remediation plan, however, we are going to look at how you can set an export preference on a per user basis, so that when you go to export a remediation plan, each task can be pre-populated with each preference, making the export process much more straightforward and seemless.
Patching via Tanium
For DeepSurface to work with Tanium, you need your Hostname/Server and a Secret.
Hostname/Server refers to the GraphQL API endpoint provided by Tanium. This needs to be provided by some Tanium representative. It will most likely be similar to the Tanium's Dashboard url.
To get a valid secret, an API-Token needs to be generate. To do this, follow these steps:
- In the left menu, go to Administration and click on "API Tokens" under the Permissions list
- Next, press the "New API Token" button on the right. Fill out the form presented to you and press "Create". Confirm your action by pressing "Yes".
- You should now see a screen displaying your API Token. Be sure to copy this token, because this will be the only time that Tanium will show it to you. Paste the token into the
secretfield in DeepSurface, and save the configuration.
Configuring User export preferences
One powerful feature that DeepSurface offers is the ability to set an export preference for each user in the DeepSurface system. That way, when you go to export tasks from rememdiation, DeepSurface will look at the owner of each task and pre-fill the export destination for each task based on what that owner's export preference is. This can also be updated, removed, or overridden at any time in the process. Once you have at least one properly configured ticketing integration, head to the Setup > Authentication > Users area of the application and edit an existing user that you would like to setup an export preference for. You will notice a field in the left column of the user form called "Preferred Ticketing Integration". This field defaults to "Email me Directly" if left in its default state, any exported tickets for this user (unless overridden during the export process) will go to this user directly, to this user's email address. Of course, if no email address is configured for this user, that will not be possible and one will have to be entered when exporting.
The other options for setting an export preference depend on what ticketing integrations have been configured already. All properly configured integrations will appear as options in the dropdown and you are free to select any that you like for this user. If a "Ticketing via Email" integration is selected, then no further input is needed and the interface will simply display the destination email that tickets will be sent to. If an "Atlassian Jira" integration is selected, then you will have the choice to optionally search for and map this user to a user that exists within the chosen Jira integration.
If you choose to map a user, then the externally mapped user will display on the row for this user in the main Setup > Authentication > Users section.
Now that preferences have been set for each user, the export process (covered in the next section) will be much smoother.