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

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

add_action_result(action_result)

Parameter	Required	Description
action_result	Required	The ActionResult object to add to the connector run.

append_to_message

Appends a string to the current result message.

append_to_message(message)

Parameter	Required	Description
message	Required	The string that is to be appended to the existing message.

debug_print

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

debug_print(tag, dump_object='')

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

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/. Refrain from using this API to dump an error that is handled by the App. By default the log level of the platform is set to ERROR.

error_print(tag, dump_object='')

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 once all the elements in the parameter list are processed.

finalize()

get_action_identifier

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

get_action_identifier()

get_action_results

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

get_action_results()

get_app_config

Returns the app configuration dictionary.

get_app_config()

get_app_id

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

get_app_id()

get_app_json

Returns the complete app JSON as a dictionary.

get_app_json()

get_app_run_id

Returns the current app run id.

get_app_run_id()

get_asset_id

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

get_asset_id()

get_ca_bundle

Returns the current CA bundle file.

get_ca_bundle()

get_config

Returns the current connector run configuration dictionary.

get_config()

get_connector_id

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

get_connector_id()

get_container_id

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

get_container_id()

get_container_info

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

get_container_info(container_id=None)

get_current_param

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

get_current_param()

get_product_installation_id

Returns the unique ID of the product installation.

get_product_installation_id()

get_product_version

Returns the version of .

get_product_version()

get_state

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

get_state()

get_state_file_path

Get the full current state file path.

get_state_file_path()

get_state_dir

Used for apps that must create files to access during action executions. It can use the state directory returned by this API to store such files.

get_state_dir()

get_status

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

get_status()

get_status_message

Gets the current status message of the connector run.

get_status_message()

handle_action

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

handle_action(param)

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

handle_cancel()

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

handle_exception(exception)

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

initialize()

is_action_cancelled

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

is_action_cancelled()

is_fail

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

is_fail()

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

is_poll_now()

is_success

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

is_success()

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, this returns None.

load_state()

remove_action_result

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

remove_action_result(action_result)

Parameter	Required	Description
action_result	Required	The ActionResult object that is to be removed from the connector run.

save_artifact

Saves an artifact to .

save_artifact(artifact)

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

Saves a list of artifacts to .

save_artifacts(artifacts)

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

Saves a container and artifacts to .

save_container(container)

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.

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

Saves a list of containers to the phantom platform.

save_containers(containers)

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.

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

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

save_progress(progress_str_const, *unnamed_format_args, **named_format_args)

Parameter	Required	Description
progress_str_const	Optional	The progress message to send to the Splunk Phantom 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

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.

save_state(state_dict)

Parameter	Required	Description
state_dict	Required	The dictionary to write to the state file.

send_progress

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.

send_progress(progress_str_const, *unnamed_format_args, **named_format_args)

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

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.

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

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

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.

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

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

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

set_validator(contains, validator)

Returns the following tuple:

Parameter	Description
status	phantom.APP_SUCCESS or phantom.APP_ERROR.
message	Status message.

validate_parameters

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.

validate_parameters(param)

update_summary

Updates the connector run summary dictionary with the passed dictionary.

update_summary(summary)

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

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

add_data(item)

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

Extends the data list with elements in the item list.

update_data(item)

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

get_data_size

Gets the current data list size.

get_data_size()

add_debug_data

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.

add_debug_data(item)

get_debug_data

Gets the current debug data list.

get_debug_data()

get_debug_data_size

Gets the current debug data list size.

get_debug_data_size()

add_extra_data

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.

add_extra_data(item)

get_extra_data

Gets the current extra data list.

get_extra_data()

get_extra_data_size

Gets the current extra data list size.

get_extra_data_size()

update_extra_data

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

update_extra_data(item)

add_exception_details

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.

add_exception_details(exception)

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

Appends provided text to the message.

append_to_message(message_str)

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

get_message

Gets the current action result message.

get_message()

get_param

Gets the current parameter dictionary.

get_param()

get_status

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

get_status()

get_summary

Returns the current summary dictionary.

get_summary()

is_fail

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

is_fail()

is_success

Returns 'True' if the ActionResult status is success.

is_success()

set_status

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 an exception is not to be used. status_code has to be phantom.APP_SUCCESS or phantom.APP_ERROR. Returns the status_code set.

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

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

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

set_param(param_dict)

Parameter	Required	Description
param_dict	required	The Python dictionary that overwrites the current parameter.

update_param

Updates the parameter dictionary with 'param_dict'.

update_param(param_dict)

Parameter	Required	Description
param_dict	Required	The Python dictionary that is to be updated into the current parameter.

set_summary

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

set_summary(summary)

Parameter	Required	Description
summary	Required	The Python dictionary that overwrites the current summary.

update_summary

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

update_summary(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 API is defined as a class method of the Vault class within the phantom.vault module.

get_vault_tmp_dir()

Returns the path to the vault's temporary file directory. You must add files here before calling vault_add.

get_vault_tmp_dir()

Usage example

from phantom import vault

# python3-specific syntax
file_path = f"{vault.get_vault_tmp_dir()}/hello.txt"

vault_add

Attaches a file to a container.

vault_add(container=None, file_location=None, file_name=None, metadata=None, trace=False):

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

Usage example

from phantom import 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)

vault_delete

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.

vault_delete(vault_id=None, file_name=None, container_id=None, remove_all=False, trace=False):

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.

Usage example

from phantom import vault

# Delete all files within a specific container
success, message, vault_id = vault.vault_delete(
    vault_id=None,
    file_name=None,
    container_id=55,
    remove_all=True,
    trace=False
)

assert(success)

vault_info

Returns a tuple, consisting 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.

vault_info(vault_id=None, file_name=None, container_id=None, trace=False)

Parameter	Required?	Description
vault_id	Optional	The sha1 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().
trace	Optional	Set to 'True' to return debug information.

Usage example

from pprint import pprint
from phantom import vault

# Get vault information for a particular document
success, message, info = vault.vault_info(
    vault_id=vault_id,
    container_id=container['id'],
    trace=True
)

assert(success)
print(info)

Output

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

Vault.create_attachment

The create_attachment API is defined as a class method of the Vault class within the phantom.vault module.

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 accepts file_contents instead of a file_location.

Vault.create_attachment(file_contents, container_id, file_name=None, metadata=None)

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

Usage example

from phantom.vault import Vault 

# Create an attachment in container 42 called hello.text that contains the words 'Hello World'
# Note that create_attachment is a class method of Vault
resp = Vault.create_attachment(
    file_contents="Hello World",
    container_id="42",
    file_name="hello.txt"
)
assert(resp.get("succeeded"))

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