Install Splunk Automation Broker on a Docker host

Use the Splunk SOAR Automation Broker to run actions from Splunk SOAR (Cloud) in your on-premises environment. 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.

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 the Splunk SOAR Automation Broker container.
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 the Splunk SOAR Automation Broker container

Before you can install the Splunk SOAR Automation Broker container on your host, you must install and configure Docker and Docker Compose. See Prepare to install the Splunk SOAR Automation Broker in this manual.

It is better to install your containerization solution on a separate virtual machine or separate physical hardware from your Splunk SOAR (On-premises) deployment.

If your Docker host cannot use Docker Hub to retrieve container images, please follow the instructions in the topic Install Splunk Automation Broker when you cannot use DockerHub in this manual.

Once Docker and Docker Compose have been installed on your Docker host, install the Splunk SOAR Automation Broker container.

1. Log in to either your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance.
   1. From the Home menu, select Administration then Product Settings then Automation Broker.
   2. Either download or copy and paste the sample configuration file. Save it as 'docker-compose.yml'.
2. Copy the docker-compose.yml file to your Docker host.
3. 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 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 between Automation Brokers.

4. 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.

5. Launch the Splunk SOAR Automation Broker container.
   docker compose up -d
   For older releases of Docker, you may need to use the command docker-compose up -d.
6. 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>

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

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

8. 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.

9. (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 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.

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 then 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 then Product Settings then select Automation Broker.
2. Locate the Splunk SOAR Automation Broker configuration that you added and confirm that the broker status is Active.