Connections

Overview

A connection is the relationship between the D3 SOAR system and a third-party application. Having an established connection enables you to ingest data from third-party systems, use integration commands, and set up remote commands.

The connections module contains a list of integration connections and webhook keys configured for your user account. This is a centralized location to manage the connections for scalable and ease of deployment. In this module, you can conduct the following tasks:

Manage integration connections and webhook keys to see which have been configured for which clients (for MSSPs). Integration connections and webhook keys are organized in separate tabs.
Integration Connections: You can add, edit and remove integration connections.
- Filter integration connections by sites to see exactly which connections have been configured for which clients (for MSSPs). Use the drop-down menu on the right side of the + Add Integration Connection button to select the desired site.
- Bulk add and edit the Connection used for each Integration (for SOC engineers).
- Monitor the Health Status of all Connections (for all users). The Health Status for Connections can be configured for some connections by activating the Connection Health Check option inside the connection details.
Webhook Keys: You can view and delete configured webhook keys for data ingestion and remote commands.

Integration Connections

The Integration Connections tab offers a comprehensive list of established integration connections available to your user account. These connections are authenticated by user credentials or API keys. Within this tab, you can manage integration connections, such as creating new ones, reviewing the connected sites and associated users, modifying connection configurations, monitoring the connection's health status, and determining its active state.

Adding a Connection

To begin using a System Integration, you have to add an Integration Connection. Not every integration connection will look the same, some may differ based on required parameters. A general The steps are listed below:

Search and select the Integration you want to use from the Integration List.
Click on the + Add Integration Connection button.
The New Connection panel will appear. You can fill in the following Connection Details after selecting an Integration:
1. Connection Name
2. Sites: Set which Site can use this Connection.
  - A connection can be shared between all internal sites and client sites, and used for individual sites.
3. Select the Recipient site for events from connections Shared to Internal Sites
4. Agent Name (Optional): select the Proxy Agent that you have set up previously
5. Description (Optional): add a description of how this Connection should be used
6. Tenant: enable toggle to share connection to a tenant site
7. Active: ensure this checkbox is selected so that the Connection is available for use
8. System: this section contains the parameters that have been predefined by D3 Security specifically for this Integration.
9. Enable Password Vault: select the password vault connection you have set up
10. Connection Health Check: check this box to configure a recurring health check on this Connection
11. Test Connection: click this to verify the account credentials and network connection. Sometimes a Connection failure may indicate that there’s no network connection between the D3 SOAR platform and the third-party tool.
  Note: The latest Test Connection results will display within this window for reference
12. Clone Connection to Site : Select which Sites this Connection should be cloned to
13. User Permission: configure who has access to this Connection
  Note: Sections l and m only show up when editing the Connection.

Alert

If your connection is Shared to Internal Sites, you can configure the Recipient site for events from connections Shared to Internal Sites here as well. Please note that the site selection here will be applied globally – all events ingested through connections that are shared to internal sites will now belong to the newly selected site. If no site is selected, a default, unknown site will be created.

Password Vault

The processes of using password vault (e.g., Hashicorp, CyberArk) for an integration are listed below:

Set up a General Password Vault connection
Set up an Integration Connection (SIEM, Threat Intel or EDR) with Password Vault enabled

Reader Note

D3 SOAR integrates with external credential vaults, which enables you to use them in D3 SOAR without hard coding or exposing the credentials of third-party applications (SIEM, EDR or Threat Intel). The credentials are not stored in D3 SOAR, rather, the integration fetches the credentials from the external vault when called.

Set up a General Password Vault connection

Connections to third-party environments are centrally managed in the Home > Configuration > Connections page

Creating a New Connection

To create a new Connection, click on the + Add Integration Connection button in a selected site.

Reader Note

If a Connection can be globally shared across multiple sites, the Connection can be added in Shared to all sites.

In the New Connection window, you can select “General Password Vault” from the drop down list.

Next, specify a unique Connection Name.

Upon selecting the Integration, the corresponding System Connections Parameters will display.

Connection credentials configuration:
1. Select Authentication Types
2. Enter Key for the Authentication, and its Value
3. If Add to Header is enabled, the key value pair will be automatically added to the header.
4. If Add to Query Params is enabled, the key value pair will be automatically added to the query URL
5. Add Server URL along with the directory of stored password
6. Select GET Method to query password
7. (optional) Header and Body

Test connection
1. Click Test Connection to ensure the authentication to the configured password vault is properly set up

Configure mapping
1. Navigate to Home > Integration > General Password Vault
2. Test command “Fetch Credentials” using the configured connection
3. The password data is stored under $.data in the example of Hashicorp
4. Configure Data JSON Path
  - Enter Root Path of in “Data Json Path” $.data
  - Note: Different password vault could have different root JSON paths. In order to identify the root JSON path of a given password vault, test the “Fetch Credentials” command to check on the response payload for the JSON path structure.
5. Construct Mapping
  - Go the corresponding Integration Home > Configuration > Integrations
  - Click on Connection Parameters
  - Note down the connection parameters needed to be replaced from the password vault, example (username, password, serverurl)
    JSON Keys for mapping match connection parameter (username, password)
  - JSON Value is keys under Data JSON Path ( $.username, $.password)

Reader Note

Mapping format: {"key":"value" }

Key is the Connection Parameter.

Value is the third-party JSON source path.

Set up an Integration Connection

The Integration refers to intended integration such as SIEM, Threat Intel or EDR, to be set up in D3 SOAR.

Follow the similar process of setting up a new integration connection (e.g., Cybereason)

Set up Connection:

Enter the Server URL
Select the Password Vault that has been configured
Test Connection to verify the connection is established to the third-party integration (e.g., Cybereason)

Configuring Access Control

Access the connections user permissions by clicking the share button on the top right of the configurations panel. By default, only the connection creator can have viewing and editing privileges and will assume the owner role.

Viewers—Viewers have no edit permission, and can only view the connection.
Editors—Editors can edit and save the connection.
Owners—The owner(s) of the connection can edit and delete, as well as change the permission of the connection.

If there are overlaps in permission levels, the greatest permission level will be granted. For example, if your user is the owner, but your role is a viewer, the owner's permission will take precedence.

Reader Note

There must be at least one owner for each connection. The last owner cannot be deleted or reassigned to the viewer/editor.

Webhook Keys

The Webhook Keys tab presents a complete list of configured webhook keys available for your account, organized into two categories: Data Ingestion and Remote Command.

A webhook key, also referred to as a webhook token or webhook secret, serves as a unique identifier or authentication code used to secure and authenticate webhook communications between various applications or systems via webhooks. In D3 SOAR, webhooks can be used to ingest data from external systems or remotely trigger commands within D3 SOAR from external systems.

In both of the Data Ingestion and Remote Command subtabs, the API keys are listed with the columns Type, Key Name, Key, Site Name, Assigned User and Creator. The columns are filterable to help you quickly locate a webhook key. Alternatively, you can find keys with the search bar.

Clicking on a key will reveal additional information on the right-hand panel, including its name, creator, and a list of commands that possess access to the key. If the command is associated with an integration, the integration it belongs to will also be displayed. If you are the creator of a key, you can delete the key by clicking on the trash can icon.

Reader Note

Webhook keys can be managed within the Connections module. To create a new webhook key, navigate to the Data Ingestion or Integrations module under Configuration.

For additional details on how to configure a webhook key and the authentication methods available, please refer to this guide Webhook Configuration Guide.