Vault automation API

Splunk Phantom's 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 response to a security breach. The following APIs are supported to leverage the capabilities of the platform using Playbooks.

The Splunk Phantom web interface in release 4.5 and later refers to the vault as Files. The automation API uses vault.

vault_info

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

Returns a tuple of a success flag (bool), any response message (str), and information for all vault items that match either of the input parameters (list of dicts). If neither of the parameters are specified, an empty list is returned.

Parameter	Required?	Type	Description
vault_id	Optional	str	The alphanumeric file hash of the vault file, such as 41c4e1e9abe08b218f5ea60d8ae41a5f523e7534.
file_name	Optional	str	The filename of the vault file.
container_id	Optional	int	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().
trace	Optional	bool	When set to True, more detailed output will be displayed in debug output.

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

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",
            "md5": "5fb30fe90736c7fc77de637021b1ce7c",
            "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
    },
....
....
]

vault_add

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

Attach a file to a container by adding it to the vault. This API returns a success flag (bool), any response message (str), and the vault_id (str, alphanumeric file hash) of the vault file.

Parameter	Required?	Type	Description
container	Optional	int or dict	The container to act on, can either be a numerical id or a container object. If no container is provided, the currently running container will be used.
file_location	Required	str	This is the location of the file on the Phantom file system. The file should be written to /opt/phantom/vault/tmp/ directory before calling this API.
file_name	Optional	str	A custom file name. This will show up as the file name in the container's vault files list.
metadata	Optional	dict	Metadata about the file. Currently the only user-supplied attribute that will be used is "contains" which specifies what kind of information is available. (e.g. metadata={"contains":["pe file"]} tells the system the file is a Windows PE file which will enable actions such as "detonate file".)
trace	Optional	bool	When set to True, more detailed output will be displayed in debug output.

The following is an example code snippet that can be used to add a file to the vault from the playbook

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="/opt/phantom/vault/tmp/myfile",
        file_name="notepad.exe",
        metadata={"contains": ["PE File"]}
    )

    phantom.debug(
        'phantom.vault_add results: success: {}, message: {}, vault_id: {}'\
        .format(success, messsage, vault_id)
    )

    return

vault_delete

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

Remove a file from the vault. This API returns a tuple of a success flag (bool), any response message (str), and the list of deleted file names (list of str).

Parameter	Required?	Type	Description
vault_id	Optional, unless no file_name is provided	str	The alphanumeric file hash of the vault file, such as 41c4e1e9abe08b218f5ea60d8ae41a5f523e7534.
file_name	Optional, unless no vault_id is provided.	str	Name of the file to delete.
container_id	Optional	int	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().
remove_all	Optional	bool	If multiple items are found with the same identifier set this to True to remove all. If multiple files are found and this is False, an error will be returned.
trace	Optional	bool	When set to True, more detailed output will be displayed in debug output.

NOTE: For this API you will need to give the automation user permissions to delete containers.

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