App authoring API

Splunk Phantom's app authoring API can help you write applications that interact with external devices and create structured results that are then passed onto the Splunk Phantom core to be displayed in the UI and consumed by Splunk Phantom Playbooks. The complete set of APIs can be logically broken up into the following:

• BaseConnector
• ActionResult
• Vault

BaseConnector

add_action_result(action_result)

Add 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 that is to be appended 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/. 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.

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.

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_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 Splunk Phantom product installation.

get_product_version()

Returns the version of the Splunk Phantom product.

get_state()

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

get_state_file_path()

Get the full current state file path.

get_state_dir()

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

get_status()

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

get_status_message()

Get 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. This is called if the action was 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. This 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()

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

remove_action_result(action_result)

Remove 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 the Splunk Phantom platform.

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 to learn how to set the run_automation key in the artifact dictionary.

save_artifacts(artifacts)

Save a list of artifacts to the Splunk Phantom platform.

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 to learn how to set the run_automation key in the artifact dictionary.

save_container(container)

Save a container and artifacts to the Splunk Phantom platform.

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

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 Phantom core, which is saved in persistent storage.

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

Write 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 Phantom 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 Phantom 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 Phantom 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)

Set 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

In Splunk Phantom, playbooks marked as active are automatically run when a container is added or updated. The addition of an artifact to a container is considered updating a container.

The container and artifact dictionaries support a key named run_automation. When this 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, so as to run the playbook once per container when all the artifacts are ingested. These APIs are recommended over save_artifact.

The save_artifact API sets the run_automation key to 'False' if not set.

ActionResult

add_data(item)

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

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

Get the current data list.

get_data_size()

Get the current data list size.

add_debug_data(item)

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

Get the current debug data list.

get_debug_data_size()

Get the current debug data list size.

add_extra_data(item)

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

Get the current extra data list.

get_extra_data_size()

Get the current extra data list size.

update_extra_data(item)

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

add_exception_details(exception)

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

Append the text to the message

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

get_dict()

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

get_message()

Get the current action result message.

get_param()

Get the current parameter dictionary.

get_status()

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

get_summary()

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

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

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)

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

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

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

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

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

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

Create a file with the specified contents, and add that to the vault. Returns the object added. Other than accepting file_contents instead of a file_location, this API is the same as vault_add.

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

get_vault_tmp_dir()

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

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.

Usage examples

Import the vault APIs:

from phantom 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']}]

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