App authoring API

Use the Splunk SOAR app authoring API to write applications that interact with external devices and create structured results, which are then passed onto the Splunk SOAR core to be displayed in the SOAR UI and consumed by SOAR playbooks. The complete set of APIs can be logically divided into the following groups:

  • BaseConnector
  • ActionResult
  • Vault

BaseConnector

CODE 
add_action_result(action_result)

Adds an ActionResult object into the connector run result. Returns the object added.

Parameter Required Description
action_result Required The ActionResult object to add to the connector run.
CODE 
append_to_message(message)

Appends a string to the current result message.

Parameter Required Description
message Required The string to append to the existing message.
CODE 
debug_print(tag, dump_object='')

Dumps a pretty printed version of the 'dump_object' in the <syslog>/phantom/spawn.log file, where <syslog> typically is /var/log/.

Parameter Required Description
tag Required The string that is prefixed before the dump_object is dumped.
dump_object Optional The dump_object to dump. If the object is a list, dictionary and so on it is automatically pretty printed.
CODE 
error_print(tag, dump_object='')

Dumps an ERROR as a pretty printed version of the 'dump_object' in the <syslog>/phantom/spawn.log file, where <syslog> typically is /var/log/. Do not use this API to dump an error that is handled by the App. By default, the log level of the platform is set to ERROR.

Parameter Required Description
tag Required The string that is prefixed before the dump_object is dumped.
dump_object Optional The dump_object to dump. If the object is a list, dictionary and so on it is automatically pretty printed.
CODE 
finalize()

Optional function that can be implemented by the AppConnector. Called by the BaseConnector after all the elements in the parameter list are processed.

CODE 
get_action_identifier()

Returns the action identifier that the AppConnector is supposed to run.

CODE 
get_action_results()

Returns the list of ActionResult objects added to the connector run.

CODE 
get_app_config()

Returns the app configuration dictionary.

CODE 
get_app_id()

Returns the appid of the app that was specified in the app JSON.

CODE 
get_app_json()

Returns the complete app JSON as a dictionary.

CODE 
get_app_run_id()

Returns the current app run id.

CODE 
get_asset_id()

Returns the current asset ID passed in the connector run action JSON.

CODE 
get_ca_bundle()

Returns the current CA bundle file.

CODE 
get_config()

Returns the current connector run configuration dictionary.

CODE 
get_connector_id()

Returns the appid of the app that was specified in the app JSON.

CODE 
get_container_id()

Returns the current container ID passed in the connector run action JSON.

CODE 
get_container_info(container_id=None)

Returns info about the container. If container_id is not passed, returns info about the current container.

CODE 
get_current_param()

Returns the current parameter dictionary that the app is working on.

CODE 
get_product_installation_id()

Returns the unique ID of the Splunk SOAR (On-premises) product installation.

CODE 
get_product_version()

Returns the version of Splunk SOAR (On-premises).

CODE 
get_state()

Gets the current state dictionary of the asset. Will return None if load_state() has not been previously called.

CODE 
get_state_file_path()

Gets the full current state file path.

CODE 
get_state_dir()

An app might require the state directory to create files to access during action executions. It can use the state directory returned by this API to store such files.

CODE 
get_status()

Gets the current status of the connector run. Returns either phantom.APP_SUCCESS or phantom.APP_ERROR.

CODE 
get_status_message()

Gets the current status message of the connector run.

CODE 
handle_action(param)

Every AppConnector is required to implement this function. It is called for every parameter dictionary in the parameter list.

Parameter Required Description
param Required The current parameter dictionary that needs to be acted on.
CODE 
handle_cancel()

Optional function that can be implemented by the AppConnector. It is called if the action is cancelled.

CODE 
handle_exception(exception)

Optional function that can be implemented by the AppConnector. Called if the BaseConnector::_handle_action function code throws an exception that is not handled.

Parameter Required Description
exception Required The Python exception object.
CODE 
initialize()

Optional function that can be implemented by the AppConnector. It is called once before starting the parameter list iteration, for example, before the first call to AppConnector::handle_action().

CODE 
is_action_cancelled()

Returns 'True' if the connector run was cancelled. Otherwise, it returns as 'False'.

CODE 
is_fail()

Returns 'True' if the status of the connector run result is failure. Otherwise, it returns as 'False'.

CODE 
is_poll_now()

The on_poll action is called during Poll Now and scheduled polling. Returns 'True' if the current on_poll is run through the Poll Now button. Otherwise, it returns as 'False'.

CODE 
is_success()

Returns 'True' if the status of the Connector Run result is success. Otherwise, it returns as 'False'.

CODE 
load_state()

Loads the current state file into the state dictionary. If a state file does not exist, it creates one with the app_version field. This returns the state dictionary. If an error occurs, it returns None.

CODE 
remove_action_result(action_result)

Removes an ActionResult object from the connector run result. Returns the removed object.

Parameter Required Description
action_result Required The ActionResult object that is to be removed from the connector run.
CODE 
save_artifact(artifact)

Save an artifact to Splunk SOAR (On-premises).

Parameter Required Description
artifact Required Dictionary containing information about an artifact.

Returns the following tuple

Parameter Description
status phantom.APP_SUCCESS or phantom.APP_ERROR.
message Status message.
id Saved artifact ID if success.

Save artifacts more efficiently with the save_container API, since a single function call can add a container and all its artifacts.

See Active playbooks at the end of this section to learn how to set the run_automation key in the artifact dictionary.

CODE 
save_artifacts(artifacts)

Save a list of artifacts to Splunk SOAR (On-premises).

Parameter Required Description
artifacts Required A list of dictionaries that each contain artifact data. Don't set the run_automation key for the any artifacts, because the API will automatically set this value to 'False' for all but the last artifact in the list to start any active playbooks after the last artifact is ingested.

Returns the following tuple:

Parameter Description
status phantom.APP_SUCCESS or phantom.APP_ERROR.
message Status message.
id_list List of saved artifact IDs if successful; none otherwise.

Save artifacts more efficiently with the save_container API, since a single function call can add a container and all its artifacts.

See Active playbooks at the end of this section to learn how to set the run_automation key in the artifact dictionary.

CODE 
save_container(container)

Save a container and artifacts to Splunk SOAR (On-premises).

Parameter Required Description
container Required Dictionary containing info about a container. To ingest a container and artifacts in a single call, add a key called artifacts to the container dictionary. This key contains a list of dictionaries, each item in the list representing a single artifact. Don't set the run_automation key for the container or artifacts. The API will automatically set this value to 'False' for all but the last artifact in the list to start any active playbooks after the last artifact is ingested.
fail_on_duplicate Optional Affects behavior when attempting to save a container that is an exact duplicate of an existing container.
  • When True, returns phantom.APP_ERROR
  • When False or not provided, returns phantom.APP_SUCCESS

Returns the following tuple

Parameter Description
status phantom.APP_SUCCESS or phantom.APP_ERROR.
message Status message.
id Saved container ID if success, none otherwise.

See Active playbooks at the end of this section to learn how to set the run_automation key in the container dictionary.

CODE 
save_containers(containers)
Save a list of containers to the phantom platform.
Parameter Required Description
containers Required A list of dictionaries that each contain information about a container. Each dictionary follows the same rules as the input to save_container.
fail_on_duplicate Optional Affects behavior when attempting to save a container that is an exact duplicate of an existing container and no other containers in the group were successfully saved.
  • When True, returns phantom.APP_ERROR
  • When False or not provided, returns phantom.APP_SUCCESS
Returns the following tuple:
Parameter Description
status phantom.APP_SUCCESS or phantom.APP_ERROR. This is successful when at least one container is successfully created.
message Status message
container_responses A list of responses for each container. There will be one response for each container in the input list. This is a dictionary with the following keys: success (phantom.APP_SUCCESS or phantom.APP_ERROR), message, and id.

This is the most performant API to use during ingestion, as you can create all the artifacts and containers at once.

As long as at least one container is successfully added, the status is success. During ingestion, BaseConnector automatically keeps track of how many containers and artifacts are successfully added, though if you do want to know more about an individual failure you need to iterate over the list in the response and check the message.

CODE 
save_progress(progress_str_const, *unnamed_format_args, **named_format_args)

This function sends a progress message to the Splunk SOAR core, which is saved in persistent storage.

Parameter Required Description
progress_str_const Optional The progress message to send to the Splunk SOAR core. Typically, this is a short description of the current task.
unnamed_format_args Optional The various parameters that need to be formatted into the progress_str_config string.
named_format_args Optional The various parameters that need to be formatted into the progress_str_config string.
CODE 
save_state(state_dict)

Writes a given dictionary to a state file that can be loaded during future app runs. This is especially crucial with ingestion apps. The saved state is unique per asset. An app_version field will be added to the dictionary before saving.

Parameter Required Description
state_dict Required The dictionary to write to the state file.
CODE 
send_progress(progress_str_const, *unnamed_format_args, **named_format_args)

This function sends a progress message to the Splunk SOAR core. It is written to persistent storage, but is overwritten by the message that comes in through the next send_progress call. Use this function to send messages that need not be stored over a period of time like percent completion messages while downloading a file.

Parameter Required Description
progress_str_const Optional The progress message to send to the Splunk SOAR core. Typically, this is a short description of the current task being carried out.
unnamed_format_args Optional The various parameters that need to be formatted into the progress_str_config string.
named_format_args Optional The various parameters that need to be formatted into the progress_str_config string.
CODE 
set_status(status_code, status_message='', exception=None, *unnamed_format_args, **named_format_args)

Sets the status of the connector run result, phantom.APP_SUCCESS or phantom.APP_ERROR. Optionally, you can set the message. If an exception object is specified, it is recorded in the connector run result. It will replace any status and message previously saved in the object. Returns the status_code set.

Parameter Required Description
status_code Required The status to set of the connector run. It is either phantom.APP_SUCCESS or phantom.APP_ERROR.
status_message Optional The message to set. Typically, this is a short description of the error or success.
exception Optional The Python exception object that has occurred. BaseConnector will convert this exception object to string format and append to the message.
unnamed_format_args Optional The various parameters that need to be formatted into the status_message string.
named_format_args Optional The various parameters that need to be formatted into the status_message string.
CODE 
set_status_save_progress(status_code, status_message='', exception=None, *unnamed_format_args, **named_format_args)

Helper function that sets the status of the connector run. This needs to be phantom.APP_SUCCESS or phantom.APP_ERROR. This function sends a persistent progress message to the Splunk SOAR Core in a single call. Returns the status_code set.

Parameter Required Description
status_code Required The status to set of the connector run. It is either phantom.APP_SUCCESS or phantom.APP_ERROR.
status_message Optional The message to set. Typically, this is a short description of the error or success.
exception Optional The Python exception object that has occurred. BaseConnector will convert this exception object to string format and append it to the message.
unnamed_format_args Optional The various parameters that need to be formatted into the status_message string.
named_format_args Optional The various parameters that need to be formatted into the status_message string.
CODE 
set_validator(contains, validator)

Sets the validator of a particular contains, this is set for the current connector run only. Call this from the initialize function.

Returns the following tuple:

Parameter Description
status phantom.APP_SUCCESS or phantom.APP_ERROR.
message Status message.
CODE 
validate_parameters(param)

BaseConnector uses this function to validate the current parameter dictionary based on the contains of the parameter. The AppConnector can override it to specify its own validations.

CODE 
update_summary(summary)

Update the connector run summary dictionary with the passed dictionary.

Parameter Required Description
summary Required The Python dictionary that needs to be updated to the current connector run summary.

Active playbooks

This section provides additional information for save_artifact, save_artifacts, and save_container, described earlier.

In Splunk SOAR (On-premises), playbooks marked as active are automatically run when a container is added or updated. Adding any artifact to a container is considered updating the container.

The container and artifact dictionaries support a key named run_automation. When this key is set to 'True' active playbooks are run. For best results, set run_automation to 'True' only for the last artifact of the container.

The save_container and save_artifacts APIs set the run_automation key to 'False' for all except the last artifact, to run the playbook once per container after all artifacts are ingested. Based on this behavior, using the save_container and save_artifacts APIs is preferable to using the save_artifact API, which sets the run_automation key to 'False' if not already set.

ActionResult

CODE 
add_data(item)

Adds a data item as a dictionary to the list. Returns the item added.

Parameter Required Description
item required This is a dictionary that needs to be added as a new element to the current data list.
CODE 
update_data(item)

Extends the data list with elements in the item list.

Parameter Required Description
item required This is a list of items that needs to be added to the current data list.
CODE 
get_data()

Gets the current data list.

CODE 
get_data_size()

Gets the current data list size.

CODE 
add_debug_data(item)

Adds a debug data item to the list. The item will be converted to a string object through the str(...) call before it is added to the list. This list is dumped in the spawn.log file if the action result fails.

CODE 
get_debug_data()

Gets the current debug data list.

CODE 
get_debug_data_size()

Gets the current debug data list size.

CODE 
add_extra_data(item)

Adds an extra data item as a dictionary to the list.

Extra data is different from data that is added through the add_data(...) API. Apps can add data as extra data if the data is huge and none of it is rendered. Typically, this is something that needs to be recorded and can potentially be used from a playbook, but not rendered. Returns the item added.

CODE 
get_extra_data()

Gets the current extra data list.

CODE 
get_extra_data_size()

Gets the current extra data list size.

CODE 
update_extra_data(item)

Extends the extra data list with elements in the item list.

CODE 
add_exception_details(exception)

Adds details of an exception into the action result. These details are appended to the message in the resultant dictionary. Returns the current status code of the object.

Parameter Required Description
exception optional The Python exception object that has occurred. ActionResult will convert this exception object to string format and append it to the message.
CODE 
append_to_message(message_str)

Appends the text to the message

Parameter Required Description
message required The string to append to the existing message.
CODE 
get_dict()

Creates a dictionary from the current state of the object. This is usually called from BaseConnector.

CODE 
get_message()

Gets the current action result message.

CODE 
get_param()

Gets the current parameter dictionary.

CODE 
get_status()

Gets the current result. It returns either phantom.APP_SUCCESS or phantom.APP_ERROR.

CODE 
get_summary()

Returns the current summary dictionary.

CODE 
is_fail()

Returns 'True' if the ActionResult status is a failure.

CODE 
is_success()

Returns 'True' if the ActionResult status is success.

CODE 
set_status(status_code, status_message='', exception=None, *unnamed_format_args, **named_format_args)

Sets the status of a result. To call this function with unnamed format arguments, pass a message. Pass "" as the status_message, if you want to set an exception parameter instead of a message. Pass 'None' if you do not want to use an exception. status_code has to be phantom.APP_SUCCESS or phantom.APP_ERROR. Returns the status_code set.

Parameter Required Description
status_code Required The status of the connector run. It is either phantom.APP_SUCCESS or phantom.APP_ERROR.
status_message Optional The message to set. Typically, this is a short description of the error or success.
exception optional The Python exception object that has occurred. BaseConnector will convert this exception object to string format and append it to the message.
unnamed_format_args Optional The various parameters that need to be formatted into the status_message string.
named_format_args Optional The various parameters that need to be formatted into the status_message string.
CODE 
set_param(param_dict)

Sets the parameter dictionary with the passed param_dict. This overwrites the current parameter dictionary.

Parameter Required Description
param_dict required The Python dictionary that overwrites the current parameter.
CODE 
update_param(param_dict)

Updates the parameter dictionary with 'param_dict'

Parameter Required Description
param_dict Required The Python dictionary that is to be updated into the current parameter.
CODE 
set_summary(summary)

Replaces the summary with the passed summary dictionary. Returns the summary set.

Parameter Required Description
summary Required The Python dictionary that overwrites the current summary.
CODE 
update_summary(summary)

Updates the summary with the passed summary dictionary. Returns the updated summary.

Parameter Required Description
summary required The Python dictionary that updates the current summary.

Vault

During the execution of any action other than test connectivity, the app can add attachments to a container. These files are placed in the vault, which is a location within each container. The app requires the container id to add a file in the vault. The BaseConnector::get_container_id() API can be used to get this information.

Every vault item within a container is denoted by a vault_id.

For additional background information on the Vault API, see Vault automation API in the Python Playbook API Reference for Splunk SOAR (On-premises) manual.

Note: Most vault APIs are defined directly as functions in the phantom.vault module. The create_attachment and get_vault_tmp_dir APIs are defined as class methods of the Vault class within the phantom.vault module.
CODE 
vault_add(container=None, file_location=None, file_name=None, metadata=None, trace=False):

Adds an ActionResult object into the Connector Run result. Returns the object added.

Parameter Required Description
container Required The container to add the attachment to. The return value of BaseConnector::get_container_id() is sufficient.
file_location Required This is the location of the file on the Splunk SOAR (On-premises) file system. The file must be written to the path returned by Vault.get_vault_tmp_dir() before calling this API.
file_name Optional The file name to use.
metadata Optional A dictionary containing metadata information that the app can set about this attachment, dictionary keys that can be set are 'size' in bytes, 'contains' is the contains of the file, 'action' is the action name, returned through the BaseConnector::get_action_name() API) and 'app_run_id', which is the unique ID of this particular app run, returned by BaseConnector::get_app_run_id()).
trace Optional Set to 'True' to return debug information.
CODE 
vault_delete(vault_id=None, file_name=None, container_id=None, remove_all=False, trace=False):

The vault_delete API deletes one or more objects from the vault. Deletes either the "first matching object" or "all matching objects", based on the specified remove_all criterion

Parameter Required? Description
vault_id Optional The sha1 file hash of the vault file contents, such as 41c4e1e9abe08b218f5ea60d8ae41a5f523e7534.
file_name Optional The file name of the vault file.
container_id Optional Container ID to query vault items for. To get the current container_id value from an app that is executing an action, use the return value of BaseConnector::get_container_id().
remove_all Optional Set to 'True' to delete all vault files that meet the provided criteria. Set to 'false' to delete only the first vault file that meets the criteria.
trace Optional Set to 'True' to return debug information.
CODE 
vault_info(vault_id=None, file_name=None, container_id=None, trace=False)

The vault_info API returns a tuple; of a success flag either True or False, any response messages as strings, and information for all vault items that match either of the input parameters as a list. If neither of the parameters are specified, an empty list is returned.

Parameter Required? Description
vault_id Optional The alphanumeric file hash of the vault file, such as 41c4e1e9abe08b218f5ea60d8ae41a5f523e7534.
file_name Optional The file name of the vault file.
container_id Optional Container ID to query vault items for. To get the current container_id value from an app that is executing an action, use the return value of BaseConnector::get_container_id().
trace Optional Set to 'True' to return debug information.
CODE 
Vault.create_attachment(file_contents, container_id, file_name=None, metadata=None)

Creates a file with the specified contents, and add that to the vault. Returns the object added. This API is the same as vault_add, but it accepts file_contents, rather than a file_location,

Parameter Required Description
file_contents required The contents of the file. A temporary file with these contents will be created, which will then be added to the vault.
container_id required This is the container to add the attachment to. The return value of BaseConnector::get_container_id() is sufficient.
file_name optional The file name to use.
metadata optional A dictionary containing metadata information that the app can set about this attachment, dictionary keys that can be set are 'size' in bytes, 'contains' is the contains of the file, 'action' is the action name, returned through the BaseConnector::get_action_name() API) and 'app_run_id', which is the unique ID of this particular app run, returned by BaseConnector::get_app_run_id()).
CODE 
Vault.get_vault_tmp_dir()

Returns the path to the vault's temporary file directory. Files must be added here before calling vault_add.

Usage examples

Import the vault APIs - for vault_add, vault_delete, vault_info:

PYTHON 
from phantom import vault

Import the Vault class APIs - for create_attachment, get_vault_tmp_dir:

PYTHON 
from phantom.vault import Vault

Add a file to the vault:

CODE 
# Container should be a container dict or a container id

success, message, vault_id = vault.vault_add(container=container, file_location='/opt/phantom/somewhere/over/the/rainbow', file_name='Low Latency Expert.docx', metadata=None, trace=False)

assert(success)

Get information about a file in the vault:

JSON 
success, message, info = vault.vault_info(vault_id=vault_id, container_id=container['id'], trace=True):
assert(success)
print(info)

info contains:
[{'id': 8, 'created_via': 'automation', 'container': 'msg', 'task': '', 'create_time': '39 minutes ago', 'name': 'Low Latency Expert.docx', 'user': 'admin', 'vault_document': 8, 'mime_type': 'application/msword', 'hash': '0c96c0561edabf40928e49f0589b9bf41ef70fea', 'vault_id': '0c96c0561edabf40928e49f0589b9bf41ef70fea', 'size': 79822, 'path': '/opt/phantom/vault/0c/96/0c96c0561edabf40928e49f0589b9bf41ef70fea', 'metadata': {'md5': '947e1761e31d16061d696c5d79be465f', 'sha1': '0c96c0561edabf40928e49f0589b9bf41ef70fea', 'sha256': '6e14992c829110e4bb672b7b496620be0b1f6b868e5b84e27e9ad28c33f10aaa'}, 'aka': ['Low Latency Expert.docx'], 'container_id': 5, 'contains': ['doc', 'vault id']}]

Create a file with specified contents and add it to the vault

PYTHON 
from phantom.vault import Vault 
base64_file = b"R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="
file_contents = base64.b64decode(base64_file)
container_id = "1"
resp = Vault.create_attachment(file_contents, container_id)
if resp.get("succeeded"):
   print("succeeded")

Get temporary file directory for the vault:

PYTHON 
from phantom.vault import Vault
vault_tmp_dir = Vault.get_vault_tmp_dir()

Deprecated functions

The following functions are deprecated. Use the equivalent vault class member functions.

Deprecated API Supported API
add_attachment vault_add
get_vault_file vault_info
get_meta_by_hash vault_info
get_file_info vault_info
get_file_path vault_info

Deprecated API definitions

CODE 
get_file_path(vault_id)

Returns the full path of the vault file on the filesystem, given the vault_id. This function replaces the get_vault_file(...) function.

This function has been deprecated. Use vault_info instead.

Parameter Required Description
vault_id required The vault_id of the vault file.
CODE 
get_file_info(vault_id=None, file_name=None, container_id=None)

Returns information on all vault items that match either of the input parameters. This function replaced the get_meta_by_hash(...) function. If neither of the parameters are specified, the return value will be an empty list.

This function has been deprecated. Use vault_info instead.

Parameter Required Description
vault_id required The vault_id of the vault file.
file_name optional The name of the vault file.
container_id optional Container ID to query vault items for. To get the current container_id value from an app which is executing an action, use the return value of BaseConnector::get_container_id().