Configuring Integration Connections in Incident Playbook Command Tasks
Overview
When configuring integration command tasks in Incident Playbooks, the API connection used to communicate with the third-party platform must be specified. Connections must be built before using them for an integration command task. This can be configured by navigating to Configuration > Integrations > [Select Integration] > Connections. After creating connections for third-party integrations, you may use them when configuring integration commands in Incident Playbooks. There are three options you can select connections for integration command tasks in incident playbooks: By Connection Name, By Site, and By Category.
Select Connection by Name/Site
The By Connection Name option selects one specific connection based on the configured connection name set up for the third-party integration tool. On the other hand, the By Site option selects one specific connection configured and shared to different sites (e.g. Shared to Internal Sites and Shared to Client Sites).
Dynamically Select Connection (By Connection Name)
This option allows you to dynamically select which connection to you based on a defined Jinja2 (Jinja2 is a web template engine for the Python programming language) logic. To enable this option, select Dynamically select connection from the drop-down menu. A box will appear below the drop-down menu. Click on the ellipsis located in the upper right corner of the box. This will open the built-in Data Formatter. Here, you can input the logic on how the command task will dynamically select connections. For example, you can configure a logic that will select a connection based on the site the Incident Playbook is running on. The sample Python script of the example logic is provided below.
Sample Jinja2 Script for Dynamically Selecting Connections
The Python script defines the following logic and steps for the command task to dynamically select connections:
Find the Site that the previous command in the Incident Playbook ran on.
If the name of the Site identified is “SentinelOne Site” use the connection “VirusTotal_1”. Likewise, If the name of the Site is “Security Operations” use the connection “VirusTotal_2”
If the connection name is found, the command will use the corresponding connection. Otherwise, the command will return the “Invalid connector name. A valid connector name should be one from the connection dropdown list” error message.
{% set site = PlaybookData | jsonpath('$.DataSource.incident.OwnerSite') %}
{% if site == "SentinelOne Site" %}
{{"VirusTotal_1"}}
{% endif %}
{% if site == "Security Operations" %}
{{"VirusTotal_2"}}
{% endif %}
Reader Note
The Allowed Values button shows a list of the connection values that are valid.
Select Connection by Category
This option is primarily intended for Managed Security Service Provider (MSSP) playbooks and D3's out-of-the-box playbooks. These often include a codeless playbook nested within them that contains parallel command tasks of different integrations from the same category, such as "Check IP Reputation".
The key function of this feature is to allow the playbook to execute only those parallel tasks that share a common connection name, contingent upon whether the integration for these tasks has a valid connection with the common name in your SOAR environment. Tasks without valid connections will remain in an "N/A" state and will not produce errors. This increases the playbook's adaptability and its capability to manage connections that are not available.
Dynamically Select Connection (By Category)
Similar to Select Connection by Category, the Dynamically Select Connection option allows the insertion of additional Jinja logic to accommodate a variety of use cases. One typical example is the mapping of different client sites to distinct connection names (see example in the Dynamically Select Connection (By Name) section above).
Reader Note
If no functional connection is found for any of the integration commands using the specified common connection name, the task will not generate an error; instead, it will remain in a N/A state.