Splunk® Automation Broker

Set Up and Manage the Splunk SOAR Automation Broker

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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 one of the following containerization solutions:

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 or Podman version requirements

If you are using Docker, you must use a supported version of Docker. Docker versions 20.10.2 and later are supported. If you are using Podman, you must use a version that supports Docker Compose. Podman versions 4.1.0 and later are supported.

Operating system requirements

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

  • If you are using CentOS use CentOS 7.2009 or later.
  • If you are using Ubuntu use version 14.04.6 LTS or later.
  • If your organization must comply with FIPS requirements, you must use a version of Red Hat Enterprise Linux, CentOS, or Amazon Linux that supports FIPS mode. See FIPS compliance later in this topic.

Hardware requirements

To run the Splunk SOAR Automation Broker, your Docker or Podman 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

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.

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

If you need the Splunk SOAR Automation Broker to run in FIPS mode, your containerization solution, either Docker or Podman, must be running on an operating system that supports 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

Docker only offers s390x (IBM Z) packages for RHEL 7 and 8. You may be be able to use the CentOS packages on RHEL. See https://docs.docker.com/engine/install/rhel/ for more information.

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

Installation prerequisites

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

  • Your host must be running Docker or Podman and Docker Compose in order to support the container for the Splunk SOAR Automation Broker. Search for "Download and Install" on the Docker website or "Get Started" on the Podman 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. Do this even if your organization uses Podman.
  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 or Podman host.
  4. On your Docker or Podman 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 or Podman 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 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.

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

  6. (Conditional) Because Podman does not support the watchtower feature, if you are using Podman you must remove or comment out the portion of the docker-compose.yml file that refers to the watchtower feature.
    Remove these lines from the docker-compose.yml file: 
            labels:
            com.centurylinklabs.watchtower.enable: "true"
            com.centurylinklabs.watchtower.lifecycle.pre-check: "/splunk/broker/bin/pre-check.sh"
            com.centurylinklabs.watchtower.lifecycle.pre-update: "/splunk/broker/bin/pre-update.sh"
            com.centurylinklabs.watchtower.lifecycle.post-update: "/splunk/broker/bin/post-update.sh"
            com.centurylinklabs.watchtower.lifecycle.post-check: "/splunk/broker/bin/post-check.sh"

    watchtower:
        image: containrrr/watchtower
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            - WATCHTOWER_LIFECYCLE_HOOKS=true
            # This environment variable will force watchtower to only
            # watch containers with com.centurylinklabs.watchtower.enable
            # label set to true
            - WATCHTOWER_LABEL_ENABLE=true
        command: --interval 600
  7. 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.
  8. 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>
    If you are using Podman, the use the Podman logs command instead.
    podman logs <container ID>
  9. Copy the key and provide it to the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator.
    ********************************************
Automation Broker Encryption Key:
ENCRYPTIONKEYISVISIBLEHERE
********************************************
  10. 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.

  11. (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.
      For Docker: docker ps
      For Podman: podman ps
    2. Stop the Splunk SOAR Automation Broker container.
      For Docker: docker stop <container_name>
      For Podman: podman stop <container_pid>
    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, login and get the Splunk SOAR Automation Broker Docker image from the Splunk SOAR Free Trial page.
  2. If you cannot access the Splunk SOAR Free Trial page, 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 or Podman repository by pulling it from Docker Hub.
      For Docker: docker pull phantomsaas/automation_broker:<version>
      For Podman: podman 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 or Podman save command. Search for 'docker save' on Docker Docs or 'podman save' on Podman Docs for more information.
      For Docker: docker save -o <path/to/file/<filename-version>.tar phantomsaas/automation_broker:<version>
      For Podman: podman save -o <path/to/file/<filename-version>.tar phantomsaas/automation_broker:<version>
  3. Copy the file to the Docker or Podman host where you intend to run the Splunk SOAR Automation Broker.
  4. On the Docker or Podman 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 or podman load command. Search for 'docker load' on Docker Docs or 'podman load' on Podman Docs for more information.
    For Docker: docker load -i <path/to/file/<filename-version>.tar
    For Podman: podman load -i <path/to/file/<filename-version>.tar
  5. Create a directory on the container 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 or Podman 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 or Podman command to start the Splunk SOAR Automation Broker in detached mode. Make sure to specify your data directory for persistent data.
    For Docker: docker run --env PHANTOM_BASE_URL=<PHANTOM_BASE_URL> -v <path/to/your/data_directory>:/splunk_data
    -d phantomsaas/automation_broker:<version>
    For Podman: podman 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 or podman logs command to see the startup output of the Splunk SOAR Automation Broker, including an encryption key.
    For Docker: 
    docker logs <container ID>
    For Podman: 
    podman logs <container PID>
  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.
      For Docker: docker psFor Podman: podman ps
    2. Stop the Splunk Automation Broker container.
      For Docker: docker stop <container_name>
      For Podman: podman stop <container_PID>
    3. Launch a new container. Include any environment variables as needed.
      For Docker: docker run --env PHANTOM_BASE_URL=<PHANTOM_BASE_URL> -v <path/to/your/data_directory>:/splunk_data
      -d phantomsaas/automation_broker:<version>
      For Podman: podman 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 or Podman logs command to see the log output for the Splunk SOAR Automation Broker container: 
    docker logs <container ID>
    podman 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.
Last modified on 19 July, 2023
PREVIOUS
About Splunk SOAR Automation Broker 		  NEXT
Interact with the Splunk SOAR Automation Broker

This documentation applies to the following versions of Splunk® Automation Broker: current

Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters