
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().
PREVIOUS Use the contains parameter to configure contextual actions |
NEXT Use datapaths to present data to the web interface |
This documentation applies to the following versions of Splunk® SOAR (Cloud): current
Feedback submitted, thanks!