
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:
- A host running Docker and Docker Compose. For documentation on Docker and Docker Compose, see https://docs.docker.com.
- A host running Podman, and Docker Compose. For documentation on Podman, see https://podman.io/docs.
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:
- 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 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.
- Install and start setting up the Splunk SOAR Automation Broker.
- Register the Splunk SOAR Automation Broker with Splunk SOAR (Cloud) or Splunk SOAR (On-premises).
- Verify that setup and registration are complete.
- 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).
- If it is not already installed, install and configure Docker Compose for your local environment. Do this even if your organization uses Podman.
- For help with installing Docker Compose, see the Docker documentation.
- For help with installing Podman, see the Podman documentation.
- Log in to either your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance.
- From the Home menu, select Administration > Product Settings > Automation Broker.
- Either download or copy and paste the sample configuration file. Save it as 'docker-compose.yml'.
- Copy the docker-compose.yml file to your Docker or Podman host.
- 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.
- 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.- Set the
PHANTOM_BASE_URL
. - Set the path to the data directory on the Docker host's file system that you created earlier:
- </path/to/splunk_data>:/splunk_data
- (Conditional) If you need to use an HTTP proxy server for outgoing HTTP traffic, set the
https_proxy=http
environment variable. - (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
andhttp_proxy
environment variables are case sensitive. Use lowercase letters. - Set the
- (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
- Launch the Splunk SOAR Automation Broker container.
docker compose up -d
For older versions of Docker, you may need to use the commanddocker-compose up -d
. - 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>
- Copy the key and provide it to the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator.
******************************************** Automation Broker Encryption Key: ENCRYPTIONKEYISVISIBLEHERE ********************************************
- 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.
- (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:
- Get the name of your running automation broker by listing running containers.
For Docker:docker ps
For Podman:podman ps
- Stop the Splunk SOAR Automation Broker container.
For Docker:docker stop <container_name>
For Podman:podman stop <container_pid>
- Launch a new container.
docker compose up -d
For older versions of docker, you may need to use the commanddocker-compose up -d
.
- Get the name of your running automation broker by listing running containers.
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.
- If you have access, login and get the Splunk SOAR Automation Broker Docker image from the Splunk SOAR Free Trial page.
- If you cannot access the Splunk SOAR Free Trial page, do the following steps:
- 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.
- 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>
- 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>
- Copy the file to the Docker or Podman host where you intend to run the Splunk SOAR Automation Broker.
- 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
- 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. - 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
andhttp_proxy
environment variables are case sensitive. They must be typed as lowercase letters. - (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.
- 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>
- Copy the key and provide it to the Splunk SOAR administrator.
******************************************** Automation Broker Encryption Key: ENCRYPTIONKEYISVISIBLEHERE ********************************************
- 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.
- (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:
- Get the name of your running automation broker by listing running docker containers.
For Docker:docker ps
For Podman:podman ps
- Stop the Splunk Automation Broker container.
For Docker:docker stop <container_name>
For Podman:podman stop <container_PID>
- 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>
- Get the name of your running automation broker by listing running docker containers.
Register the Splunk SOAR Automation Broker with Splunk SOAR (Cloud) or Splunk SOAR (On-premises)
The Splunk SOAR administrator performs these steps.
- Log in to Splunk SOAR (Cloud) or Splunk SOAR (On-premises).
- In Splunk SOAR, click Home > Administration, then navigate to Product Settings and select Automation Broker.
- Click + Automation Broker.
- 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.
- 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.
- Enter a unique name for the Splunk SOAR Automation Broker to help you identify it. Each Automation Broker must have its own, unique name.
- 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).
- 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>
- 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.
- In Splunk SOAR, select Home and navigate to Administration > Product Settings > Automation Broker.
- Locate the Splunk SOAR Automation Broker configuration that you added and confirm that the broker status is Active.
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
Feedback submitted, thanks!