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.