Splunk® Phantom

Python Playbook API Reference for Splunk Phantom

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Vault automation API

The Splunk Phantom 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.

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

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 Splunk Phantom file system. Write this file to /opt/phantom/vault/tmp/ directory before calling this API.
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.

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

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="/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, 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",
            "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
    },
....
....
]
Last modified on 03 December, 2020
PREVIOUS
Session automation API
  NEXT
Network automation API

This documentation applies to the following versions of Splunk® Phantom: 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters