Interact with the Splunk SOAR Automation Broker

The Splunk SOAR Automation Broker is delivered as and runs inside of a Docker container. You may use either Docker or Podman to run and manage the Automation Broker's container.

Find the Splunk SOAR Automation Broker container name or ID

On the container host, as a user with permissions to run docker commands, use the docker ps or podman pscommand to list running containers.

Example:

docker ps 

CONTAINER ID   IMAGE                            COMMAND                  CREATED         STATUS         PORTS     NAMES
9b774867e500   automation_broker:4.12.0.53159   "/bin/sh -c ./pkgs/e…"   4 minutes ago   Up 4 minutes             quirky_keller

If no containers are running the output will be empty.

docker ps 

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Show all the containers whether running or stopped by using the -a or --all argument.

Compare the output to the list of connected brokers in Splunk SOAR (Cloud) or Splunk SOAR (On-premises). You can see the list of running, connected brokers from the Home menu, under Administration then Product Settings then Automation Broker to identify a specific broker.

Most docker and podman commands accept either the container ID or the container name as parameters.

Start, stop, or restart the Splunk SOAR Automation Broker container

Each of these commands required access to the container host, and a user account with Docker permissions.

You can start the Splunk SOAR Automation Broker container manually if it has been stopped, or the host has been rebooted.

docker start <container ID>

podman start <container ID>

If you want to restart a container for any reason, use the docker restart or podman restartcommand. By default, Docker only gives 10 seconds for shutdown, so use -t 60 to allow enough time for the Automation Broker to cancel running actions.

docker restart -t 60 <container ID>

podman restart -t 60 <container ID>

To manually stop a container, use the docker stop or podman stopcommand. By default, Docker only gives 10 seconds for shutdown, so use -t 60 to allow enough time for the Automation Broker to cancel running actions.

docker stop -t 60 <container ID>

podman stop -t 60 <container ID>

Automation Broker's automatic pre-check and post checks

The automation broker runs several checks when the docker container is started to make sure it is ready to pair. The same tests are run every minute on a running automation broker.

• User test, checks to see if the user is the root user or is running with root permissions.
• Volume test, checks to see:
  • that the volume has at least 1GB of free space.
  • if the permissions for sensitive files such as the encryption key and the file containing the API token incorrectly set to world readable.
• Proxy test. If an http or https proxy is detected:
  • does an nslookup to make sure the dns information is correct.
  • does a simple, authenticated https curl request through the proxy to check for a response.
• SOAR API test:
  • an unauthenticated REST call to ensure the instance is up and responding.
  • an authenticated REST call to ensure the instance is up and responding.

If these tests fail, the Splunk SOAR Automation Broker updates the user with an error message and troubleshooting suggestions.

After the first three minutes after the docker container for the automation broker is started and every five minutes after that, a Docker healthcheck is run. If this test fails three successive times, the container is marked as unhealthy. The container is not stopped or restarted, only marked as unhealthy.

To see the health status information log for the automation broker run the command:

• For Docker:

  docker inspect --format "{{index (index .State.Health.Log) $[$(docker inspect --format '{{len .State.Health.Log}}' <container_id>)-1]}}" <container_id>

• For Podman:

  podman inspect --format "{{index (index .State.Health.Log) $[$(docker inspect --format '{{len .State.Health.Log}}' <container_id>)-1]}}" <container_id>

Connect to and run commands on the Splunk SOAR Automation Broker container

There are two ways to connect to the Splunk SOAR Automation Broker docker container while it is running.

Use "docker exec" connect to and run commands

1. On the Docker host, get the ID of the docker container by listing the running containers.
   

   docker ps

   podman ps

2. On the container host, use the docker or podman exec command to connect to the container and open an interactive bash shell.
   

   docker exec -it <container ID> bash

   podman exec -it <container ID> bash

Use "docker attach" to attach your terminal to the container

1. On the container host, get the ID of the container by listing the running containers.
   

   docker ps

   podman ps

2. On the container host, use the docker or podman attach command to connect your terminal to the container.
   

   docker attach <container ID> 

   podman attach <container ID> 

You can disconnect from the container using the CTRL+p CTRL+q sequence.

See also

• Documentation on the Docker website, https://www.docker.com.
• Documentation on the Podman website, https://podman.io.