Understanding datapaths
A datapath is a series of names, keywords, attributes, and wildcards that describe the path to the element in the JSON schema to be able to access or retrieve that element's value from associated action results, custom function results, or artifacts.
A datapath is described using this format:
<type>:<path.to.value_name>
Example of a datapath for an artifact attribute:
artifact:*.ip
Artifacts are indexed by their common event format (CEF) data so only CEF data is available to use in datapaths. You cannot access other fields such as label
or description
.
Example of a datapath for action results:
action_result:data.*.longitude
The Splunk Phantom Playbook API uses a variety of datapaths.
Use the following table to learn more about some of the important datapaths used in Splunk Phantom, 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 |
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 |
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 |
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 by name. Example: my_custom_function:custom_function:ip |
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 |
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 that point to a list of values
When you are publishing a list as the output of a custom function, it is best to produce a list of dictionaries so that a simple datapath can be used to index into the list or iterate over all items in the list. For example, the following custom function produces four numbers as output:
def primes_under_ten(): import json from phantom.rules import debug # Custom code return [{"result": number} for number in numbers]
Because the output is returned as a list of dictionaries, you can use the following datapath to see the entire list:
primes_under_ten_1:custom_function_result.data.*.number
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 } ]
Understanding artifacts | Understanding apps and assets |
This documentation applies to the following versions of Splunk® Phantom (Legacy): 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7
Feedback submitted, thanks!