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

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.

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.

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.

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.

finalize()

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

get_action_identifier()

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

get_action_results()

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

get_app_config()

Returns the app configuration dictionary.

get_app_id()

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

get_app_json()

Returns the complete app JSON as a dictionary.

get_app_run_id()

Returns the current app run id.

get_asset_id()

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

get_ca_bundle()

Returns the current CA bundle file.

get_config()

Returns the current connector run configuration dictionary.

get_connector_id()

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

get_container_id()

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

get_container_info(container_id=None)

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

get_current_param()

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

get_product_installation_id()

Returns the unique ID of the product installation.

get_product_version()

Returns the version of .

get_state()

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

get_state_file_path()

Gets the full current state file path.

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.

get_status()

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

get_status_message()

Gets the current status message of the connector run.

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.

handle_cancel()

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

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.

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().

is_action_cancelled()

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

is_fail()

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

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'.

is_success()

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

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.

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.

save_artifact(artifact)

Save an artifact to .

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.

save_artifacts(artifacts)

Save a list of artifacts to .

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.

save_container(container)

Save a container and artifacts to .

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 , 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

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.

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.

get_data()

Gets the current data list.

get_data_size()

Gets the current data list size.

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.

get_debug_data()

Gets the current debug data list.

get_debug_data_size()

Gets the current debug data list size.

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.

get_extra_data()

Gets the current extra data list.

get_extra_data_size()

Gets the current extra data list size.

update_extra_data(item)

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

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.

append_to_message(message_str)

Appends the text to the message

Parameter	Required	Description
message	required	The string to append to the existing message.

get_dict()

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

get_message()

Gets the current action result message.

get_param()

Gets the current parameter dictionary.

get_status()

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

get_summary()

Returns the current summary dictionary.

is_fail()

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

is_success()

Returns 'True' if the ActionResult status is success.

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.

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.

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.

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.

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.

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.

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 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.

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.

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.

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()).

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:

from phantom import vault

Import the Vault class APIs - for create_attachment, get_vault_tmp_dir:

from phantom.vault import Vault

Add a file to the vault:

# 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:

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

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:

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

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.

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().