Install Splunk SOAR Automation Broker

Use the Splunk SOAR Automation Broker to run actions from Splunk SOAR (Cloud) in your on-premises environment. You can also use the Splunk SOAR Automation Broker to connect assets in a complex network to a Splunk SOAR (On-premises) instance. To view a diagram of how the Splunk SOAR Automation Broker works, see About the Splunk SOAR Automation Broker.

System requirements

The Splunk SOAR Automation Broker must be installed on a host running Docker and Docker Compose, a containerization solution. For documentation on Docker and Docker Compose, see https://docs.docker.com.

For security reasons, only allow admin users to access the machine where the Splunk SOAR Automation Broker is installed and make sure to locate this machine behind a firewall.

Docker version requirements

You must use a supported version of Docker. Docker versions 20.10.2 and higher are supported.

Operating system requirements

Docker containers run on a Docker host. Your Docker host can be any operating system supported by Docker.

• If you are using CentOS use CentOS 7.2009 or higher.
• If you are using Ubuntu use version 14.04.6 LTS or higher.

Hardware requirements

To run the Splunk SOAR Automation Broker, your Docker host must have at least:

• 4 CPU cores
• 8GB of RAM
• 20GB or more of available storage

Network Connectivity Requirements

The Splunk SOAR Automation Broker does not require inbound network connections. The Splunk SOAR Automation Broker initiates all communications.

The Splunk SOAR Automation Broker requires outbound/egress connectivity to your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance. The Splunk SOAR Automation Broker must be able to connect to TCP port 443 (HTTPS) on your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance.

TLS Certificates

The Splunk SOAR Automation Broker always validates the TLS certificate received from your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance. If your enterprise is using a TLS intercepting proxy that replaces or modifies such certificates you might need to add the CA certificates for that proxy to the Automation Broker's list of trusted Certificate Authorities. See Add a Certificate Authority to the Splunk SOAR Automation Broker.

FIPS compliance

The Splunk SOAR Automation Broker can be run in FIPS mode, if the underlying operating system is in FIPS mode.

In order for a security application such as to be considered FIPS compliant it must meet the standards specified by the National Institute of Standards and Technology (NIST) in the standard FIPS 140-2.

If you want to run the Splunk SOAR Automation Broker in FIPS mode, you must use a supported operating system in FIPS mode:

• Red Hat Enterprise Linux 7.6 through 7.9
• Red Hat Enterprise Linux 8.0 through 8.7
• CentOS 7.6 through 7.9
• Amazon Linux 2

You can learn more about setting your operating system to use FIPS mode from the operating system vendor's websites:

• RHEL 7.x or CentOS 7.x in the Red Hat Security Guide in Chapter 9.
• RHEL 8.x in the Red Hat Security Guide in Chapter 3.
• Amazon Linux 2 in the AWS Public Sector blog post Enabling FIPS mode in Amazon Linux 2.

Installation prerequisites

Before you install the Splunk SOAR Automation Broker, make sure that you meet the following prerequisites:

• Your host must be running Docker in order to support the container for the Splunk SOAR Automation Broker. Search for "Download and Install" on the Docker website for more information.
• Your user account must be a member of the "docker" permissions group on the docker host. Search for "docker permissions" on the Docker website for more information.
• You must be, or be working with, a Splunk SOAR administrator. This is the person in your organization who is responsible for adding new users and configurations to your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) deployment.
• You need the <PHANTOM_BASE_URL> which is the URL to your Splunk SOAR deployment. Find the <PHANTOM_BASE_URL> in Splunk SOAR at Home > Administration > Company Settings > Info in the Base URL for Splunk SOAR field.
• If you use a proxy server for outgoing traffic, you need the IP address and port for your HTTPS or HTTP proxy server.
• For Splunk SOAR (On-premises) users, do the following steps:
  • Log in as the user account that runs Splunk SOAR (On-premises).
  • Run the following commands:
    

    <PHANTOM_HOME>/bin/phenv python <PHANTOM_HOME>/www/manage.py change_ab_version --no-ab-version 
    <PHANTOM_HOME>/bin/phsvc reload uwsgi

Install and set up the Splunk SOAR Automation Broker

Perform these steps in combination with the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator if you are not the Splunk SOAR administrator.

1. Install and start setting up the Splunk SOAR Automation Broker.
2. Register the Splunk SOAR Automation Broker with Splunk SOAR (Cloud) or Splunk SOAR (On-premises).
3. Verify that setup and registration are complete.
4. Start the Splunk SOAR Automation Broker and verify that the connection is active.

If you get an error such as mkdir: cannot create directory '/splunk_data/broker': Permission denied, verify that the logged-in user has permissions to write to the mounted directory on the host machine. See the manual page for the chmod *nix system utility, man chmod for more information about changing directory permissions.

Install and start setting up the Splunk SOAR Automation Broker

Install the Splunk SOAR Automation Broker on the server and start setting it up to work with Splunk SOAR (Cloud) or Splunk SOAR (On-premises).

1. If it is not already installed, install and configure Docker Compose for your local environment. See the Docker website for more information.
2. Log in to either your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance.
   1. From the Home menu, select Administration > Product Settings > Automation Broker.
   2. Either download or copy and paste the sample configuration file. Save it as 'docker-compose.yml'.
3. Copy the docker-compose.yml file to your docker host.
4. On your Docker host, create a directory for the Splunk SOAR Automation Broker to store persistent data, such as logs and authentication tokens. The rest of this document will call that directory /splunk_data.
   mkdir <data_directory>
   This directory must be on the Docker host's file system, not inside the Docker container. You are responsible for setting the appropriate file system permissions on this directory to prevent unauthorized access.

   If you intend to run multiple Splunk SOAR Automation Brokers each instance of Automation Broker requires its own data directory. Do not share data directories with between Automation Brokers.

5. Edit the docker-compose.yml file to set environment variables as needed. Environment variables are in the environment section. Each environment variable in the file is listed as a comment using a pound sign ( # ). To use an environment variable, remove the pound sign.
   1. Set the PHANTOM_BASE_URL.
   2. Set the path to the data directory on the Docker host's file system that you created earlier:
      - </path/to/splunk_data>:/splunk_data
   3. (Conditional) If you need to use an HTTP proxy server for outgoing HTTP traffic, set the https_proxy=http environment variable.
   4. (Conditional) If you need to use an HTTPS proxy server for outgoing HTTPS traffic, set the https_proxy=https environment variable.

   Both the https_proxy and http_proxy environment variables are case sensitive. Use lowercase letters.

6. Launch the Splunk SOAR Automation Broker container.
   docker compose up -d
   For older versions of docker, you may need to use the command docker-compose up -d.
7. As a user with docker permissions, use the docker logs command to see the startup output of the Splunk SOAR Automation Broker, including the encryption key.
   

   docker logs <container ID>

8. Copy the key and provide it to the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator.
   

   ********************************************
   Automation Broker Encryption Key:
   ENCRYPTIONKEYISVISIBLEHERE
   ********************************************
   

9. The log output also contains a Splunk SOAR Authorization Code. Copy the code and provide it to the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator.
   

   ****************************************************************************************
   Splunk SOAR Authorization Code:
        AUTOGENERATEDCODEISVISIBLEHERE
   Please provide this code to your Splunk SOAR administrator to continue setup.
   ****************************************************************************************
   

   The authorization code expires after 15 minutes.

10. (Conditional) If your authorization code expires before you can use it to authorize your Splunk SOAR Automation Broker, as a user with docker permissions, do the following steps:
    1. Get the name of your running automation broker by listing running docker containers.
       docker ps
    2. Stop the Splunk SOAR Automation Broker container.
       docker stop <container_name>
    3. Launch a new container.
       docker compose up -d
       For older versions of docker, you may need to use the command docker-compose up -d.

How to get the Splunk SOAR Automation Broker if your host cannot connect to Docker Hub

If your Docker host cannot connect to Docker Hub follow these steps to get the Splunk SOAR Automation Broker.

1. If you have access, get the Splunk SOAR Automation Broker Docker image from the Phantom Community Portal.
2. If you cannot access the Phantom Community Portal, do the following steps:
   1. On a system which can reach Docker Hub, find the latest Splunk SOAR Automation Broker image from the following list : Docker Hub. The examples that follow are using the <version> broker image.
   2. Load the Docker image into the local Docker repository by pulling it from Docker Hub.
      docker pull phantomsaas/automation_broker:<version>
      Output that includes the following two lines indicates that the image was downloaded successfully:

      Status: Downloaded newer image for phantomsaas/automation_broker:<version>
      docker.io/phantomsaas/automation_broker:<version>
      

   3. Save the image using the Docker save command. Search for 'docker save' on " Docker Docs for more information.
      docker save -o <path/to/file/<filename-version>.tar phantomsaas/automation_broker:<version>
3. Copy the file to the Docker host where you intend to run the Splunk SOAR Automation Broker.
4. On the Docker host where you intend to run the Splunk SOAR Automation Broker, load the docker image you just copied into the local Docker repository using the docker load command. Search for 'docker load' on " Docker Docs for more information.
   docker load -i <path/to/file/<filename-version>.tar
5. Create a directory on the Docker host for the Splunk Automation Broker to store persistent data, such as logs and authentication tokens:
   mkdir <data_directory>
   This directory is on the Docker host filesystem, not inside the container. You are responsible for setting the appropriate filesystem permissions on this directory to prevent unauthorized access.
6. As a user with docker permissions, run the Docker command to start the Splunk SOAR Automation Broker in detached mode. Make sure to specify your data directory for persistent data.
   docker run --env PHANTOM_BASE_URL=<PHANTOM_BASE_URL> -v <path/to/your/data_directory>:/splunk_data
-d phantomsaas/automation_broker:<version>
   The output is the container ID. You need the container ID later. If you are doing any of the conditional steps that follow, use the --env flags at the beginning of your commands, otherwise they won't take effect.
   • (Conditional) If you need to use a proxy server for outgoing HTTPS traffic, you must specify the proxy as an environment variable in the docker run command.
     --env https_proxy=<PROXY IP ADDRESS>:<PROXY PORT>
   • (Conditional) If you need to use a proxy server for outgoing HTTP traffic, you must specify the proxy as an environment variable in the docker run command.
     --env http_proxy=<PROXY IP ADDRESS>:<PROXY PORT>

   Both the https_proxy and http_proxy environment variables are case sensitive. They must be typed as lowercase letters.

7. As a user with docker permissions, use the docker logs command to see the startup output of the Splunk SOAR Automation Broker, including an encryption key.
   

   docker logs <container ID>

8. Copy the key and provide it to the Splunk SOAR administrator.
   

   ********************************************
   Automation Broker Encryption Key:
   ENCRYPTIONKEYISVISIBLEHERE
   ********************************************
   

9. The log output also contains a Splunk SOAR Authorization Code. Copy the code and provide it to the Splunk SOAR administrator.
   

   ****************************************************************************************
   Splunk SOAR Authorization Code:
        AUTOGENERATEDCODEISVISIBLEHERE
   Please provide this code to your Splunk SOAR administrator to continue setup.
   ****************************************************************************************
   

   The authorization code expires after 15 minutes.

10. (Conditional) If your authorization code expires before you can use it to authorize your Splunk Automation Broker, do the following steps as a user with docker permissions:
    1. Get the name of your running automation broker by listing running docker containers.
       docker ps
    2. Stop the Splunk Automation Broker container.
       docker stop <container_name>
    3. Launch a new container. Include any environment variables as needed.
       docker run --env PHANTOM_BASE_URL=<PHANTOM_BASE_URL> -v <path/to/your/data_directory>:/splunk_data
-d phantomsaas/automation_broker:<version>

Register the Splunk SOAR Automation Broker with Splunk SOAR (Cloud) or Splunk SOAR (On-premises)

The Splunk SOAR administrator performs these steps.

1. Log in to Splunk SOAR (Cloud) or Splunk SOAR (On-premises).
2. In Splunk SOAR, click Home > Administration, then navigate to Product Settings and select Automation Broker.
3. Click + Automation Broker.
4. Paste the encryption key in the Enter encryption key obtained from the Automation Broker field to encrypt the credentials used in the connection to the Splunk SOAR Automation Broker.
5. Take the Splunk SOAR Authorization Code provided by the broker during installation and add it in the Enter authorization code obtained from the Automation Broker field.
6. Enter a unique name for the Splunk SOAR Automation Broker to help you identify it. Each Automation Broker must have its own, unique name.
7. Select Complete to save the configuration.

Verify that setup and registration are complete

Confirm successful setup and registration with Splunk SOAR (Cloud) or Splunk SOAR (On-premises).

1. Use the docker logs command to see the log output for the Splunk SOAR Automation Broker container:
   

   docker logs <container ID>

2. Confirm that a message like the following appears:
   

   Waiting for Splunk SOAR registration......................Successfully paired broker.
   Automation Broker pairing succeeded.

Start the Splunk SOAR Automation Broker and verify that the connection is active

Confirm that the connection between Splunk SOAR (Cloud) or Splunk SOAR (On-premises) and the Splunk SOAR Automation Broker works.

After installing the Splunk SOAR Automation Broker, confirm that the connection is active.

1. In Splunk SOAR, select Home and navigate to Administration > Product Settings > Automation Broker.
2. Locate the Splunk SOAR Automation Broker configuration that you added and confirm that the broker status is Active.