Pair Splunk Enterprise Security with Splunk SOAR

For automation functionality that lets users run actions, run playbooks, and review automation history in Splunk Enterprise Security, pair your Splunk Enterprise Security instance with your Splunk SOAR instance.

This article contains sections specifically for Splunk SOAR (Cloud) and Splunk SOAR (On-premises). If a section is not labeled, it pertains to either deployment type.

Note:

Before you begin, check the Splunk SOAR Compatibility matrix to make sure your versions of Splunk Enterprise Security and Splunk SOAR are compatible.

Note: Splunk SOAR users whose roles are mapped in Splunk Enterprise Security can no longer use LDAP to log into Splunk SOAR after SOAR is paired with Splunk Enterprise Security. Those mapped users must log in using the Login with Splunk link and their Splunk credentials. The username is the same. All other Splunk SOAR users can log into SOAR with LDAP, as usual.

Licensing

Enterprise Security Premier Edition

Cloud deployments:

No action is required on your part. Continue to the next section, Prepare to pair.

On-premises deployments:

On Splunk SOAR, add the Splunk SOAR license included with Enterprise Security Premier Edition. For details, see Install a license in Splunk SOAR (On-premises).

On Splunk Enterprise Security, install the following licenses in the license manager that has the Enterprise Security search head in the same deployment, where the search head is a license peer.

  • Splunk Enterprise Platform license

  • Enterprise Security Premier license

To install each license, follow these steps:

  1. Log into Splunk Web.
  2. Navigate to Settings > Network > Licensing.
  3. Select Add license.
  4. Specify the license using one of these methods:
    • Select Choose file and navigate to your license file, then select it
    • Select and copy the license XML, then paste the text of your license file into the provided field.
  5. Select Install. Splunk Enterprise installs your license.
  6. If this is the first Enterprise license that you are installing, you will be prompted to restart Splunk Enterprise services.

  7. Repeat these steps for each license.

Note: If you install a Dev/Test license with an Enterprise license, the Enterprise license file will be overwritten.

Other deployments

Follow the instructions for the appropriate Splunk SOAR deployment.

Both Splunk SOAR (Cloud) and Splunk SOAR (On-premises)

Splunk SOAR automatically pulls a license from your available Splunk SOAR seat licenses when a Splunk Enterprise Security user interacts with Splunk SOAR automation. Be sure that you have enough available Splunk SOAR seat licenses for Splunk Enterprise Security users who will have a Splunk SOAR role. For details on licensing, see View your Splunk SOAR (Cloud) license.

Splunk SOAR (On-premises) only

In addition to reviewing the previous section, check that your Splunk SOAR (On-premises) license meets these two criteria, so you can pair with Splunk Enterprise Security:

  • valid

  • not a community license

Prepare to pair

Address these points in Splunk Enterprise Security, Splunk Enterprise/Splunk Cloud Platform, and Splunk SOAR before you begin pairing.

Note: The following sections are based on your deployment, including hybrid and clustered deployments. Not all sections apply to all deployments.

1. In Splunk Enterprise Security

Note: To see the pairing page and perform pairing or unpairing, you must have all 3 of the following capabilities, regardless of your Splunk deployment type:

  • admin_all_objects

  • es_soar_settings_admin

  • soar_user

  • Obtain the host name for your Splunk Enterprise Security instance and have it nearby.
  • Configure roles that you want to map to Splunk SOAR roles to inherit the soar_user capability. This process is required for Splunk Enterprise Security roles to appear in the Role mapping page at the end of the pairing process.
    1. In Splunk Enterprise or Splunk Cloud Platform: Open the Settings menu. In the Users and Authentication section, select Roles.
    2. On the Roles page, select the desired role, for example ess_analyst.
    3. On the Edit Role ess_analyst page, select the Capabilities tab. Select the checkbox for the soar_user capability, then select Save.
    4. Repeat this process for any additional roles, such as ess_user.

  • If your Splunk Enterprise Security (ES) instance is deployed in a clustered environment and you are pairing with Splunk SOAR (On-premises), prepare and upload the Splunk SOAR certificate bundle one time to Enterprise Security. The certificate bundle is automatically distributed throughout the cluster. For details, see section 4. Splunk SOAR (On-premises) certificate and clustering considerations later in this article.

2. In Splunk Enterprise or Splunk Cloud Platform

Ports: Ensure that Splunk Cloud Platform and Splunk SOAR can communicate with each other, including having all required Enterprise Security ports open. By default, open Enterprise Security port 8089.

Allow lists: Check to see if the Splunk SOAR IP address is already included in the Splunk Cloud Platform IP allow list in each of these sections:

  • Search head API access: for all stacks
  • IDM API: only for HIPAA or PCI compliance stacks
  • Search head UI access: only for HIPAA or PCI compliance stacks

If needed, add the Splunk SOAR IP address to each of these sections. For details, see Configure IP allow lists for Splunk Cloud Platform in the Admin Config Service Manual.

3. In Splunk SOAR (Cloud or On-premises)

A. Contact your Splunk SOAR administrator for the following information:

  • Obtain the following information about your Splunk SOAR instance and have it nearby:
    • Host name or IP address, including the port number if you are not using port 443, the default HTTPS port (For example, https://my-soar.com:1234/)
    • Login credentials (username and password)

    For SOAR (On-premises) clustered environments:If you are pairing with a Splunk SOAR (On-premises) cluster, be sure to pair with the SOAR load balancer or DNS.

    For SOAR (On-premises) warm standby pairs: If available, pair using a load balancer address, or a URL with DNS failover configured. If you do not have access to those types of configurations in your deployment, use the IP address of the current primary system.

    Note: If you pair with an IP address, you must manually pair Splunk Enterprise Security with your warm standby SOAR system before failing over to your standby system.
  • Verify the following criteria with your Splunk SOAR administrator:
    • The Splunk Enterprise Security IP address is on the Splunk SOAR allow list, if the allow list is specified
    • The Splunk SOAR port, specified with the host name earlier in this section, is open. For hybrid pairing, ensure the port is opened to the Splunk Enterprise Security cloud instance.

    • The Splunk SOAR SSL certificate is valid and configured.

B. Check connection before pairing with Splunk SOAR (On-premises)​

Confirm that Enterprise Security can initiate a TCP connection for REST calls to the SOAR port you noted in the previous section. By default, this SOAR port is 443. The following are samples of commands you might use from a command line interface (CLI):

openssl s_client -connect <hostname>:<port>

Nmap -p <port ip>

4. Splunk SOAR (On-premises) certificate and clustering considerations

If Splunk SOAR (On-premises) uses a TLS certificate issued by a private Certificate Authority (CA), upload the CA certificate bundle through the Splunk Enterprise Security pairing interface. This applies when pairing with either Splunk Enterprise Security (On-premises) or Splunk Enterprise Security (Cloud), including hybrid deployments.

Note:

If the SOAR TLS certificate is signed by a public CA trusted by Splunk Enterprise Security, you do not need to upload a certificate bundle. Proceed to the next section.

Prepare the certificate to use when pairing

Prepare one PEM-formatted file containing the root CA certificate and any intermediate CA certificates needed to validate the SOAR TLS certificate. Each certificate must include its complete -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- block.

A self-signed certificate must meet CA certificate requirements.
  • Have a .pem extension and be no larger than 256 KB.
  • Contain only CA certificates with the Basic Constraints extension set to CA:TRUE.
  • Contain certificates that are currently valid.
  • Exclude private keys, standalone public keys, and server certificates that are not CA certificates.

For a clustered SOAR deployment, include the CA certificates needed to validate the TLS certificate presented by the SOAR load balancer or other endpoint used for pairing.

Initial pairing upload

Follow the instructions in the Perform pairing article, uploading the PEM file in the Private CA certificates (Conditional) field.

Post-pairing upload: Add or replace a certificate bundle after pairing.

If you have already paired with Splunk Enterprise Security and need to add or replace a certificate, be aware of these important considerations:

  • Uploading a new file replaces the entire existing bundle. Make sure that your replacement file includes every CA certificate that you still need.

  • Replace the bundle before any of its certificates expire.

To add or replace an existing certificate after you have already paired, return to Configurations > Splunk SOAR > Pairing and upload your PEM file. If a bundle is already configured, select Replace file.

Splunk Enterprise Security validates the replacement bundle and tests it against the paired SOAR instance before saving it.

Certificates on Splunk Enterprise Security search head clusters

Splunk Enterprise Security automatically replicates the uploaded certificate bundle across search head cluster members. Upload the bundle one time through the pairing interface. You do not need to install the file manually or distribute it through the cluster deployer.

Here is a sample command you might use from a command line interface (CLI):

Splunk SOAR (On-premises) clustering considerations

In addition to clustering information in other sections of this Prepare to Pair article, note the following special considerations when pairing Splunk Enterprise Security with a clustered Splunk SOAR (On-premises) environment.

Warm standby

Failover status and actions are based on how you set up pairing between the Splunk SOAR cluster and Splunk Enterprise Security:

  • If you set up pairing using a load balancer or a URL with automatic DNS failover configured, there is no effect on on your pairing status when changing the primary and standby designations of your Splunk SOAR systems.

  • If you set up pairing using your primary system's IP address, action is required. Before you manually switch to your standby instance, you must change pairing with Splunk Enterprise Security to use the IP address of the Splunk SOAR warm standby instance.

    Note: If you do not establish pairing between your standby SOAR instance and Splunk Enterprise Security before you switch over to the standby SOAR instance, you might not be able to unpair from Splunk Enterprise Security.

    You must re-establish pairing any time the primary or standby designations change between your two Splunk SOAR instances.

Backup and restore

Pairing might be affected based on your backup and restore point in Splunk SOAR (On-premises), whether your backup is from a restore point that was created before or after you paired with Splunk Enterprise Security.

  • Restore point created after pairing: No need to pair again.

  • Restore point created before pairing: Re-establish pairing, following directions in this chapter.

For additional information on clustering in Splunk SOAR (On-premises), see the following articles:

Perform pairing

To pair Splunk Enterprise Security with Splunk SOAR, follow these steps:

  1. Log into Splunk Enterprise Security with the sc_admin role. From the Configurations page, select Splunk SOAR, then Pairing.
  2. Select Start pairing.
  3. On the Pairing and testing page, enter the information for your Splunk SOAR administrative account that you obtained from the Splunk SOAR administrator.

    Note: The credentials you provide are used only during the pairing process. They are not stored here. Pairing is not affected by password changes or password rotation.
    The following credentials are required:
    • Base URL, in the format https://example.soar.splunkcloud.com for SOAR (Cloud) or servernodeexample.myorg.com for SOAR (On-premises)
    • An administrator account username and password

    For SOAR (On-premises) clustered environments: If you are pairing with a Splunk SOAR (On-premises) cluster, be sure to pair with the SOAR load balancer or DNS.

    For SOAR (On-premises) warm standby pairs: If available, pair using a load balancer address, or a URL with DNS failover configured. If you do not have access to those types of configurations in your deployment, use the IP address of the current primary system.

    Note: If you pair with an IP address, you must manually pair Splunk Enterprise Security with your warm standby SOAR system before failing over to your standby system.
  4. Review the displayed Splunk Enterprise Security instance.
    • If the displayed Splunk Enterprise Security URL is correct, move on to the next step.
    • If your Splunk Enterprise Security host name is a URL, replace the displayed host name with the actual URL of your Splunk Enterprise Security deployment, in the format https://example.splunkcloud.com. If you make a mistake, select Reset to see the suggested URL again.
  5. (Conditional) If you are pairing with Splunk SOAR (On-premises) and are using certificates, add the certificate PEM file. For details on preparing certificates, see 4. Splunk SOAR (On-premises) certificate and clustering considerations.
  6. Select Next to test the connection between Splunk Enterprise Security and Splunk SOAR.
    • If the connection is successful: The next step, Role mapping, appears. Proceed to Step 6 in this section.
    • If there is an issue: Read the message provided and address the issue. Then select Next to test the connection again. Possible issues include:
      • Your Splunk SOAR version is not compatible with this version of Splunk Enterprise Security. Contact your Splunk SOAR administrator about upgrading your Splunk SOAR deployment.
      • The credentials you entered are not correct. Contact your Splunk SOAR administrator to verify the Splunk SOAR credentials.
      • The Splunk Enterprise Security IP address is not included in the Splunk SOAR allow list. For Splunk SOAR (Cloud), ask your Splunk SOAR (Cloud) administrator to contact Splunk Support to update the allow list.
      • The Splunk SOAR IP address is not included in the Splunk stack allow list. Contact your Splunk administrator.
  7. On the Role mapping page, map a Splunk platform role, like ess_analyst, to the Splunk SOAR role Incident Commander.
  8. If you are primarily using Splunk SOAR for Splunk Enterprise Security findings and investigations, configure these basic role mappings:
    Splunk Enterprise Security Role Splunk SOAR Role
    mc_admin Automation engineer
    ess_analyst Incident commander
    ess_user Observer
    If you have existing Splunk SOAR use cases and data before ever pairing with Splunk Enterprise Security, you might want to create custom roles with more limited access to your Splunk SOAR data. Follow the steps in the next section of this article, Map custom roles.
  9. Select Finish pairing.
  10. On the Pairing page, confirm that the message states that Splunk Enterprise Security is paired with Splunk SOAR.

Pairing log file

If you are having difficulties with pairing, check the mc_es_soar_pairing.log file by using the following SPL command in the Splunk Search app:

index=_internal source=*mc_es_soar_pairing.log

Verify pairing Splunk Enterprise Security with Splunk SOAR

To verify that Splunk Enterprise Security is paired with Splunk SOAR, follow these steps:

  1. Log into Splunk Enterprise Security. From the Configurations page, select Splunk SOAR, then Pairing.
  2. On the Pairing page, confirm that:
    • the first message states that Splunk Enterprise Security is paired with Splunk SOAR
    • the Configuration details section includes a list of role mappings

Unpair Splunk Enterprise Security from Splunk SOAR

You might want to unpair Splunk Enterprise Security from Splunk SOAR if you are switching out or performing maintenance on your Splunk SOAR server.

Note:

Unpairing affects people who are using Splunk Enterprise Security; users will not be able to run actions, run playbooks, or review automation history.

Unpairing deletes any certificates you might have used. Save copies of your certificates if you might need to pair again.

Unpairing does not delete existing playbooks in Splunk SOAR.

To unpair Splunk Enterprise Security from Splunk SOAR, follow these steps:

  1. Log into Splunk Enterprise Security. From the Configurations page, select Splunk SOAR, then Pairing.
  2. On the Pairing page, select Unpair. When prompted, select Unpair to confirm that you want to unpair.
    Wait for the unpairing process to complete.

The Pairing page displays.

Troubleshooting unpairing

If you are not sure that unpairing was successful, check your Splunk SOAR instance that you tried to unpair.

Note: You do not need to log into Splunk SOAR. You do not need Splunk SOAR login credentials for this procedure.

To see if your Splunk SOAR instance is unpaired, follow these steps:

  1. Navigate to the URL for your Splunk SOAR instance.

  2. On the login page, see if there is a Login with Splunk button.

    • If no Login with Splunk button is present, the instance is unpaired successfully.

    • In the unlikely event that a Login with Splunk button is present, the instance is still paired with your Enterprise Security stack. Contact your Splunk SOAR administrator to manually reset the SOAR instance.

Pairing and Splunk App for SOAR Export

There is no need to stop Splunk App for SOAR Export saved searches.

After pairing, you might choose to replace the saved search functionality with automation triggers. For details, see Create and export data models and saved searches to send to Splunk SOAR in the Splunk App for SOAR Export documentation.

Map Custom Roles

Map custom roles

This section is intended only for users who did not perform the basic role mapping during the pairing process

Note: Use care when deleting role mappings. Your Enterprise Security and Splunk SOAR instances will become unpaired if you do not have at least one Splunk Enterprise Security role mapped to a Splunk SOAR role.

Mapped roles can view all of your Splunk SOAR data. If your Splunk SOAR deployment already has a lot of existing use cases and data, you might want to restrict which roles can see your Splunk SOAR information. In this case, you can create custom roles that can see only the Splunk Enterprise Security data within your Splunk SOAR deployment.

To create custom Splunk SOAR roles to map to your Splunk Enterprise Security roles, follow these steps after you have successfully completed the pairing process described earlier in this article.

  1. Log into Splunk SOAR using the admin role you mapped during the pairing process.
  2. In the Home menu, select Administration, then User Management, then Roles & Permissions.
  3. Select + Role to create a new role. You will repeat this process for each role you want to add.
  4. Specify a role name and, optionally, a role description.
  5. Select the Basic permissions and Label permissions tabs and assign permissions based on the type of role you want to add. This table describes three types of roles you might want to use with Splunk Enterprise Security, in increasing level of permissions. Differences from one row to the next are shown in bold.
    Role type Basic permissions tab settings Label permissions tab settings
    View-only analyst
    Can view automation    		 Apps: View
    Assets: View
    Events: View
    Custom Lists: View
    Playbooks: View
    Users & Roles: View
    		es_soar_integration: View
    Automation analyst
    Can view automation, run actions, run playbooks, and respond to prompts.    		 Apps: View
    Assets: View
    Events: Edit
    Custom Lists: View
    Playbooks: Execute
    Users & Roles: View
    		es_soar_integration: Edit
    Playbook author
    Can view, run, create, and delete playbooks    		 Apps: View
    Assets: View
    Events: Edit
    Custom Lists: View
    Playbooks: Delete, Edit, Edit Code
    Users & Roles: View    		 es_soar_integration: Edit
  6. Select Create Role.
  7. To create additional roles, return to step 3 and repeat the process.
  8. Now you will map these roles to Splunk Enterprise Security roles.
    In Splunk Enterprise Security: From the Configure menu, select Splunk SOAR. On the Splunk SOAR configuration page, select Pairing.
  9. Select Edit Role Mapping. Map each new role you just created in Splunk SOAR to a Splunk Enterprise Security role. This table provides role mapping suggestions.
    Splunk Enterprise Security Role Splunk SOAR Role
    ess_user View-only analyst
    ess_analyst Automation analyst
    mc_admin Automation engineer
  10. Select Save.
  11. Confirm that your roles are mapped correctly.

See also

For Splunk SOAR (Cloud):

For Splunk SOAR (On-premises):

Version compatibility

For details on which versions of Splunk SOAR are compatible with this version of Splunk Enterprise Security, see Compatibility matrix in the Splunk Enterprise Security Release Notes.

Using Splunk SOAR with Splunk Enterprise Security

For details on how to use Splunk SOAR functionality with Splunk Enterprise Security, see Integration of Splunk SOAR with Splunk Enterprise Security later in this manual.