After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
Vault automation API
The Automation API allows security operations teams to develop detailed and precise automation strategies. Playbooks can serve many purposes, ranging from automating minimal investigative tasks that can speed up analysis to large-scale responses to a security breach. The following APIs are supported to leverage the capabilities of vault automation using playbooks.
Vault background
The Vault is used to store container attachments, also known as artifacts. Users can access the vault using the vault playbook API, described here, or by directly uploading attachments to a container. The vault accepts files of all types and sizes. Vault files are stored on your drive under PHANTOM_HOME/vault/
. Files are renamed using sha1 hashes and are saved to the database.
Vault files are duplicated to all SOAR instances in a clustered environment. When a container is deleted, all container attachments are removed and all vault files associated with the attachments are deleted from your PHANTOM_HOME/vault/
directory. In a warm standby situation, the vault directory is synced from the primary instance to the warm backup through Rsync. See Rsync in the Administer manual.
To access the vault through the visual playbook editor, use custom code. For details on custom code, see Add custom code to your playbook with the code block in the Build Playbooks with the Playbook Editor manual.
vault_add
Use the vault_add API to attach a file to a container by adding it to the vault. This API returns a success flag, any response message, and the vault ID of the vault file.
The vault_add API is supported from within a custom function.
phantom.vault_add(container=None, file_location=None, file_name=None, metadata=None, trace=False)
Parameter | Required? | Type | Description |
---|---|---|---|
container | Optional | Integer or dictionary | The container to act on. This parameter can either be a numerical ID or a container object. If no container is provided, the currently running container is used. |
file_location | Required | String | This parameter is the location of the file on the file system. Write this file to <$PHANTOM_HOME>/vault/tmp directory before calling this API. Temporary files are automatically removed after the file is added to the vault.
|
file_name | Optional | String | A custom file name. This parameter shows up as the file name in the container's vault files list. |
metadata | Optional | Dictionary | Metadata about the file. Currently the only user-supplied attribute that is used is "contains", which specifies what kind of information is available. For example, the metadata={"contains":["pe file"]} syntax tells the system the file is a Windows PE file, which enables actions such as "detonate file".
|
trace | Optional | Boolean | Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output. |
Create a file and add it to the vault
To create a file under /opt/phantom/vault/tmp
, follow these steps:
- SSH into your instance.
- Navigate to the vault tmp directory by running
cd /opt/phantom/vault/tmp
. - Create a file that you want to add to the vault. For example, create
touch myfile
.
Once you have created a file, you can add it to the vault from the playbook using the following example code snippet.
phantom.vault_add() API.
import phantom.rules as phantom import json def on_start(container): return def on_finish(container, summary): phantom.debug('phantom.vault_add start') success, message, vault_id = phantom.vault_add( file_location="<$PHANTOM_HOME>/vault/tmp/myfile", # note: this file must exist on the system for this operation to succeed file_name="notepad.exe", metadata={"contains": ["PE File"]} ) phantom.debug( 'phantom.vault_add results: success: {}, message: {}, vault_id: {}'\ .format(success, message, vault_id) ) return
vault_delete
Use the vault_delete API to remove a file from the vault. This API returns a tuple of a success flag, any response message, and the list of deleted file names.
The vault_delete API is supported from within a custom function.
phantom.vault_delete(vault_id=None, file_name=None, container_id=None, remove_all=False, trace=False)
Parameter | Required? | Type | Description |
---|---|---|---|
vault_id | Optional, unless the file_name is not provided |
String | The alphanumeric file hash of the vault file, such as 41c4e1e9abe08b218f5ea60d8ae41a5f523e7534 .
|
file_name | Optional, unless the vault_id is not provided. |
String | Name of the file to delete. |
container_id | Optional | Integer | 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 | Boolean | If multiple items are found with the same identifier, set this parameter to True to remove all. If multiple files are found and this parameter is set to False, an error is returned. |
trace | Optional | Boolean | Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output. |
For this API, you need to give the automation user permissions to delete containers.
This sample uses the vault_delete() API.
import phantom.rules as phantom def on_start(container): phantom.debug('phantom.vault_delete start') success, message, deleted_files = phantom.vault_delete( vault_id='41c4e1e9abe08b218f5ea60d8ae41a5f523e7534', remove_all=False ) phantom.debug( 'phantom.vault_delete results: success: {}, message: {}, deleted_files: {}'\ .format(success, message, deleted_files) ) return
vault_info
The vault_info API returns a tuple of a success flag, any response messages, and information for all vault items that match either of the input parameters. If neither of the parameters are specified, an empty list is returned.
The vault_info API is supported from within a custom function.
phantom.vault_info(vault_id=None, file_name=None, container_id=None, trace=False)
Parameter | Required? | Type | Description |
---|---|---|---|
vault_id | Optional | String | The alphanumeric file hash of the vault file, such as 41c4e1e9abe08b218f5ea60d8ae41a5f523e7534 .
|
file_name | Optional | String | The file name of the vault file. |
container_id | Optional | Integer | 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 | Boolean | Trace is a flag related to the level of logging. If trace is on (True), more logging is enabled. When set to True, more detailed output is displayed in debug output. |
Example request
This sample uses the phantom.vault_info() API.
import phantom.rules as phantom def on_start(container): phantom.debug('phantom.vault_info start') success, message, info = phantom.vault_info( vault_id='41c4e1e9abe08b218f5ea60d8ae41a5f523e7534', container_id=1 ) phantom.debug( 'phantom.vault_info results: success: {}, message: {}, info: {}'\ .format(success, message, info) ) return
Example response
The following is an example of what the API returns within the third tuple member.
[ { "container": "Incident # 1", "name": "ping.exe", "aka": [ "ping.exe" ], "metadata": { "contains": [ "pe file" ], "sha256": "14262982a64551fde126339b22b993b6e4aed520e53dd882e67d887b6b66f942", "sha1": "41c4e1e9abe08b218f5ea60d8ae41a5f523e7534" }, "id": 3, "container_id": 1, "create_time": "37 minutes ago", "vault_id": "41c4e1e9abe08b218f5ea60d8ae41a5f523e7534", "user": "", "vault_document": 3, "hash": "41c4e1e9abe08b218f5ea60d8ae41a5f523e7534", "path": "/opt/phantom/vault/41/c4/41c4e1e9abe08b218f5ea60d8ae41a5f523e7534", "size": 16896 }, .... .... ]
Session automation API | Network automation API |
This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6, 5.4.0, 5.5.0, 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.2.1, 6.2.2, 6.3.0
Feedback submitted, thanks!