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.
- Install the Splunk SOAR Automation Broker container.
- 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 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.
- Log in to either your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance.
- From the Home menu, select Administration then Product Settings then 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 host.
- 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.
- This directory must be accessible to the UID and GID of the accounts that run Automation Broker.
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.
- 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 want to change the user that runs the automation broker, specify the UID and GUID of the user account that will run the automation broker on the
PUID=
andPGID=
entires. - (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. - Set the
- Launch the Splunk SOAR Automation Broker container.
docker compose up -d
For older releases 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>
- 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.
docker ps
- Stop the Splunk SOAR Automation Broker container.
docker stop <container_name>
- 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.
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 then 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 logs command to see the log output for the Splunk SOAR Automation Broker container:
docker 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 then Product Settings then select Automation Broker.
- Locate the Splunk SOAR Automation Broker configuration that you added and confirm that the broker status is Active.
Prepare to install the Splunk SOAR Automation Broker | Install Splunk Automation Broker on a Podman host |
This documentation applies to the following versions of Splunk® Automation Broker: current
Feedback submitted, thanks!