Splunk® SOAR (On-premises)

Python Playbook API Reference for Splunk SOAR (On-premises)

The classic playbook editor will be deprecated in early 2025. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:

Understanding datapaths

Playbooks work with data values from the playbook's container, its artifact CEF values, the results of an action or playbook that was previously run, or static data. You specify this data using datapaths within most playbook blocks.

For details on how users pick datapaths in the Visual Playbook Editor, see Specify data in your playbook.

Datapath structure

Datapaths have the same general structure, shown in the figure below and described here. Datapaths with CEF fields are described in the next section, Datapaths and CEF fields.
Screenshot image showing elements of the datapath, described more in the text.

  • The name before the last colon describes the data's location. Examples include: artifact, custom_function, playbook_input, and an action block name like run_query_1. The datapath might contain multiple names before the last colon, that indicate block names in your playbook.
  • Everything after the last colon is the JSON-compatible structure for the data's location.
    • Periods (.) denote moving down a layer into the data structure.
    • Asterisks (*) denote arrays or lists. If the data is not an array or a list, there is no asterisk.

The example shown in the attached figure has the following specific structure:

  • artifact denotes the object where the data is located
  • The asterisk (*) denotes that you are iterating through all artifacts, rather than just one.
  • The period (.) moves you down one layer.
  • severity is the data for the artifact's security code.

attempts to access the value at that location and return a list of values based on how many artifacts it searched. If that data path is empty, returns a list of None values.

Datapaths and CEF fields

Common Event Format (CEF) fields are a system of key-value pairs with data about artifacts. For details about CEF fields, see Create custom CEF fields in .

Datapaths with CEF fields are similar to other datapaths described in the previous section, but they include cef within the datapath and usually have at least two period separators.
Screenshot image showing elements of the datapath, described more in the text.
The example shown in the figure has the following specific structure:

  • artifact denotes the object where the data is located
  • The asterisk (*) denotes that you are iterating through all artifacts, rather than just one.
  • The first period (.) moves you down one layer.
  • cef is the cef key, denoting a CEF field.
  • The second period (.) moves you down another layer into the data.
  • sourceHostName is the key for the source's host name.

Important datapaths in the Playbook API

The Playbook API uses a variety of datapaths. The following table lists some of the important datapaths used in , including their classification, description, and which APIs support them:

Datapath Classification Description API support
artifact: unnamed artifact Refers to a field in the artifact. Begins with artifact:
Example:
artifact:*.cef.bytesIn
condition, collect2, prompt
action-name:artifact: named artifact Refers to a field in the artifact that uses one or more Common Event Format (CEF) fields as an input parameter of an action. In the phantom.act() API, the auto-generated code uses the hidden parameter context that helps identify which artifact is used to run the action. The context parameter attaches a reference to the artifact that can then later be retrieved from the results. Each instance of context has a unique GUID and an optional parent_action. For example, geolocate_ip_1:artifact implies an artifact_id whose field is used as an input parameter for a particular action.
Example:
geolocate_ip_1:artifact:*.cef.bytesIn
condition, collect2, prompt
filtered_artifact: filtered artifact Refers to a field in the artifact that was filtered from a previous decision block.
Example:
filtered_artifact:*.cef.bytesIn
condition, collect2
action_result action result Refers to a field in the action result object. The condition API expects the action_results parameter to provide the action result list object. This object is the same object that is passed into the function by the results parameter or obtained by the phantom.get_action_results() API.
Example:
action_result.parameter.ip
condition, collect2
action_name:action_result. action result Refers to a field in the action result object of an action called with a name parameter. This field can be any of the actions that are run in the path that leads to this action.
Example:
geolocate_ip_1:action_result.parameter.ip
condition, collect2
action_name:filtered-action_result. filtered action result Refers to a field in the action result object of a named action that has been filtered. The phantom.condition() statement returns action_result objects or artifact IDs that match the condition. The field requires that the filtered results be provided as the parameters.
Example:
geolocate_ip_1:filtered-action_result.parameter.ip
condition, collect2
container named artifact Refers to every attribute about the container that a playbook is run against.
Example:
container:custom_fields.disposition
condition, collect2, prompt
custom_function_result custom function result Refers to a field in the custom function result object. The condition API expects the custom_function_result parameter to provide the action result list object. This is the same object that is passed into the function through the results parameter or obtained from the phantom.get_action_results() API.
Example:
custom_function_result.success
condition, collect2
named_custom_function_result named custom function result Refers to a field in the named_custom_function_result object of a custom function called with a name parameter. This field can be any of the custom functions that may have been executed in the path that leads to this action.
Example:
normalize_ip_1:custom_function_result.success
condition, collect2
named_filtered_custom_function_result filtered custom function result Refers to a field in the named_filtered_custom_function_result object of a named custom function that has been filtered. A phantom.condition() statement returns those custom_function_result objects or artifact IDs that match the condition. When this type of datapath is used, it requires that the filtered results be provided as the parameter.
Example:
normalize_ip_1:filtered-custom_function_result.success
condition, collect2
legacy_custom_function_result legacy custom function result References legacy, playbook-specific and custom functions (from the classic playbook editor) by name.
Example:
my_custom_function:custom_function:ip

The classic playbook editor will be deprecated soon, in 2024. For information on converting your playbooks, see Convert classic playbooks to modern playbooks.

condition, collect2
named_artifact named artifact Reference artifacts by action name. This datapath is valid only if the artifact is used as an input to the action.
Example:
geolocate_ip_1:artifact:*.cef.bytesIn
condition, collect2
named_playbook_result_action named playbook action result Looks up the playbook by name, and then finds the action.
Example:
pb1:playbook_results:geo1:action_result.parameter.ip
condition, collect2
named_playbook_custom_function named playbook custom function result Datapaths of this classification reference a custom function result from a sub-playbook.
Example:
pb1:playbook_results:geo1:custom_function_result.success
condition, collect2
named_playbook_result_header named playbook result Specifies the named playbook result header. Once you have the result header, the datapath specifies the named playbook, and then indicates which custom function to look up.
Example:
pb1:playbook_results:geo1:message
condition, collect2
formatted_data formatted data This datapath ends with :formatted_data. The name of the format block is used to look up the formatted data.
Example:
my_key:formatted_data
condition, collect2
playbook:launching_user dynamic user name or id Refers to the user who launched the current playbook run, by name or by their id. Helpful for sending a prompt to the user running the playbook. For playbooks launched by automation, the result is automation. Examples:
playbook:launching_user.id,
playbook:launching_user.name
condition, collect2
result_header result header Result headers are top-level keys that come out of the datapath results. Result headers can be named or unnamed. You can also get result headers from actions, custom functions, child playbooks or action or child playbook results where the results are actions or custom functions.
Example:
action_1:message
condition, collect2
none none This datapath is a null value.
Example:
none
condition
string string This datapath is any string value. Use the condition API to compare dynamic values to a constant value. If myaction:status=="success", then you can pass in the string "success". When strings are entered into the VPE configuration panel, any quotes that you use are considered string characters.
Example:
192.0.2.0
condition
numeric number This datapath is represented by any numbers.
Example:
145.1833
condition

Datapaths and lists of values

You can create a list as a custom function output.
For example, the following custom function creates a list of IP strings.

for item in input_string:
        ip_rex = re.findall('(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)', item)
        for ip in set(ip_rex):
            ip_list.append(ip)
                
for ip in set(ip_list):
    outputs.append({"ipv4": str(ip)})

Use the following datapath to see the entire list:

regex_extract_ipv4_1:custom_function_result.data.ipv4

For existing custom functions from previous versions of , where list output was not available
You can update an existing custom function that only has an item output to have list output. For instructions, see Add custom code to your playbook with a custom function. Note that when you change the output data type, you must update the datapath, removing the asterisk (*), when using the list output.

Literal values in condition and collect2

Literal values are treated differently in the condition and collect2 APIs. When calling thecondition API, literal values are treated as such. But, when you call collect2, literal values are treated as result headers. Result headers correspond to top-level keys in the action results object.

You can remove any ambiguity by prefacing your result header with the action, custom function, or child playbook. For example, instead of using the data path summary use the data path geolocate_ip_1:summary.

The following example shows an action result. In this action result, the keys that are considered result headers are status, data, message, parameter, and summary:

       [
            {
                "asset_id": 63,
                "status": "success",
                "name": "geolocate_ip_1",
                "app": "MaxMind",
                "action_results": [
                    {
                        "status": "success",
                        "data": [
                            {
                                "state_name": "Victoria",
                                "latitude": -37.7,
                                "country_iso_code": "AU",
                                "time_zone": "Australia/Melbourne",
                                "longitude": 145.1833,
                                "state_iso_code": "VIC",
                                "city_name": "Research",
                                "country_name": "Australia",
                                "continent_name": "Oceania",
                                "postal_code": "3095"
                            }
                        ],
                        "message": "City: Research, State: VIC,
                                    Country: Australia",
                        "parameter": {
                            "ip": "1.1.1.1",
                            "context": {
                                "guid": "f42fd73f-...-8194aaa9bc11",
                                "artifact_id": 0,
                                "parent_action_run": []
                            }
                        },
                        "summary": {
                            "city": "Research",
                            "state": "VIC",
                            "country": "Australia"
                        }
                    }
                ],
                "app_id": 83,
                "summary": {
                    "total_objects": 1,
                    "total_objects_successful": 1
                },
                "asset": "maxmind",
                "action": "geolocate ip",
                "message": "'geolocate_ip_1' on asset 'maxmind': 1
                            action succeeded. (1)For Parameter:
                            {\"ip\":\"1.1.1.1\"} Message: \"City:
                            Research, State: VIC, Country: Australia\"",
                "app_run_id": 51,
                "action_run_id": 11
            }
      ]
Last modified on 02 December, 2023
Understanding artifacts   Understanding apps and assets

This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.2.1, 6.2.2


Was this topic useful?







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