Splunk® SOAR (On-premises)

Administer Splunk SOAR (On-premises)

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® SOAR (On-premises). For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

Use Python scripts and the REST API to manage your deployment

Administrators can use scripts and the REST API to manage their deployment.

For example, this script uses the REST API to send an email alert when containers with the specified label and tag combination reach a predefined percentage of the total containers.

This script is provided as an example of one way in which Splunk SOAR (On-premises) administrators can use Python and the REST API to manage their deployment of Splunk SOAR (On-premises). It is provided as an example only and is not guaranteed to work without modification.

import requests
import urllib
import json
​
# Note: this URL only works if port 443 is exposed.
# You may need to add the HTTPS port for your instance,
# or use your cluster's load balancer URL
base_url = "https://127.0.0.1"
​
session = requests.Session()
​
# Note: if your installation uses a self-signed SSL certificate,
# uncomment these lines to disable SSL verification
# requests.packages.urllib3.disable_warnings() 
# session.verify = False
​
# If using basic auth
# session.auth = ("soar_local_admin", "password")
​
# If using an automation user's token
# session.headers.update({"ph-auth-token": "<token>"})
​
# Change these variables as needed to support your usecase
label = "events"
tag = "suspicious"
threshold = 0.1
email = "admin@example.com"
email_asset = "smtp_asset"
​
# Get the total number of closed containers matching your label
response = session.get(
    f"{base_url}/rest/container",
    params={
        "_filter_status": '"closed"',
        "_filter_label": f'"{label}"',
    },
)
response.raise_for_status()
first_container_id = response.json()["data"][0]["id"]
total = response.json()["count"]
​
​
# Get the number of closed containers matching your label
# that are also tagged with your chosen tag
response = session.get(
    f"{base_url}/rest/container",
    params={
        "_filter_status": '"closed"',
        "_filter_label": f'"{label}"',
        "_filter_tags__contains": f'"{tag}',
    }
)
response.raise_for_status()
count = response.json()["count"]
​
​
# Determine if the number of tagged containers is a large enough
# proportion of the total
if float(count) / total < threshold:
    print("Threshold not hit. Taking no action.")
    exit(0)
​
print(f"Hit threshold. Notifying {email}")
​
# Get the specific app which which we would like to send an email
app_id = None
response = session.get(f"{base_url}/rest/build_action")
response.raise_for_status()
assets = response.json()["assets"]
for asset in assets:
    if asset["name"] == email_asset:
        app_id = asset["apps"][0]
​
if app_id is None:
    print(f"Could not find an app with asset {email_asset}!")
    exit(1)
​
# Trigger a "send email" action via the REST API
label_browse_url = f"{base_url}/browse/{urllib.quote(label)}"
action_body = {
    "action": "send email",
    "container_id": first_container_id,
    "name": "notification email",
    "targets": [
        {
            "assets": [email_asset],
            "parameters": [
                {
                    "to": email,
                    "from": "Splunk SOAR Notifications",
                    "subject": "You are opening a lot of alerts",
                    "body": f"Please consider opening fewer alerts. See {label_browse_url}",
                }
            ],
            "app_id": appid
        }
    ],
    "type": "generic",
}
response = session.post(
    f"{base_url}/rest/action_run", json=action_body
)
response.raise_for_status()
print(json.dumps(response.json(), sort_keys=True, indent=4))

Set the desired values for the variables described in the script. This table has some more information on their expected values.

Dictionary entry Values
base_url URL of the instance. Use the loopback address (127.0.0.1) if the script is run on the host, but note that you might need to include your custom HTTPS port, or use your cluster's load balancer URL instead.
auth Ensure to include authentication information in your requests. You can either set the username and password through HTTP basic authentication, or use the authentication token for an automation user. The example script in this topic has commented examples for either authentication method.
label The label name to check.
tag The tag name to check for items with the required label.
threshold A percentage, expressed as a decimal, of containers with the given label and tag that will trigger the alert.
email The email address that receives the alert.
email_asset The name of the SMTP asset name from which the email server configuration is obtained.

On Splunk SOAR (On-premises) 5.0.1 or later releases you must use Python 3 to write your management scripts.

Last modified on 16 November, 2023
PREVIOUS
Use ITSI to monitor the health of your deployment
  NEXT
An overview of the Splunk SOAR (On-premises) clustering feature

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2


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