Splunk® Phantom (Legacy)

Python Playbook API Reference for Splunk Phantom

This documentation does not apply to the most recent version of Splunk® Phantom (Legacy). For documentation on the most recent version, go to the latest release.

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

create_container

phantom.create_container(name=None, label=None, container_type='default', 
    template=None, trace=False, tenant_id=1)

This API is used create a new container. It returns a tuple of a success flag (bool), any response message (str), and the numeric ID of the created container (int). If no container was created, the ID returned will be None. Once a container has been created, it is possible to retrieve container data using get_container by passing the created container_id.

Parameter Required? Type Description
name Required str The name for the case.
label Required str The label to apply to the case.
container_type Optional str The type of container to create, either 'default' or 'case'. Default is 'default'.
template Optional int or str Applies to containers of type 'case', indicates the template to use on creation. If container_type is case and no template is provided the default template will be used, if no default template is set an error will be returned.
trace Optional bool When set to True, more detailed output will be displayed in debug output.
tenant_id Optional int or str Phantom tenant ID as per the /rest/tenant API. While this field is optional, it is required if multi-tenancy is enabled.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.create_container start')

    success, message, container_id = phantom.create_container(name='Example Name',
                                                              label='Example Label',
                                                              container_type='case')

    phantom.debug(
        'phantom.create_container results: success: {}, message: {}, container_id: {}'\
        .format(success, message, container_id)
    )

    return

promote

phantom.promote(container=None, template=None, trace=False)

This API is used to promote a container to a case. Once the container has been promoted to a case, it can still be treated just like any other container, therefore, it is possible to retrieve container data using get_container by passing the container id/case id.

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.
template Optional int or str Either a numerical id or the name of the template to use for the case. If no template is provided, the default template will be used, if no default is set, an error will be returned.
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.promote start')

    # success, message = phantom.promote(template='Example Template Name')

    success, message = phantom.promote()

    phantom.debug(
        'phantom.promote results: success: {}, message: {}'\
        .format(success, message)
    )

    return

merge

 phantom.merge(case=None,
              container_id=None,
              artifact_id=None,
              ioc_field=None,
              playbook_run_id=None,
              action_run_id=None,
              vault_id=None,
              trace=False)

This API is used to add items to a case. On completion it returns a tuple of a success flag (boolean) and any response message (str). A case can be treated as if it were a container, as such, it is possible to retrieve case data using get_container by passing in a case id.

Parameter Required? Type Description
case Optional int or dict The case to add items to, can either be a numerical id or a container object. If no case is provided, the currently running container will be used.
container_id Optional int The numerical ID of a container to add. All artifacts, playbook_runs, action_runs, vault items, notes and comments are copied. Mapping entries are created for each item that is copied, and all copied artifacts have their 'in_case' flag set to true on the source artifact. If the container_id has already been added to the case, an error is returned. Any playbook or action runs that are 'running' will not be copied.
artifact_id Optional int The numerical ID of an artifact to add. Copies the artifact to the case, creates a mapping entry and sets the 'in_case' flag to true on the source container. If the artifact_id has already been added to the case, an error is returned.
ioc_field Optional str CEF key of the IOC to add. Requires artifact_id to be specified. Copies a specific IOC from the specified artifact. A new artifact is created in the case containing the selected IOC, and a mapping entry. If the IOC/artifact pair has already been added to the case, an error is returned.
playbook_run_id Optional int The numerical ID of playbook run to add. Copies the playbook run, playbook run logs and all playbook action runs to the case. Mapping entries are created for the playbook runs and action runs. If the playbook run has already been added to the case, an error is returned. Playbook runs that are 'running' cannot be added to a case.
action_run_id Optional int The numerical ID of an action run, which can be retrieved from an action object or by using get_summary which enumerates all the actions that were executed in the playbook. Copies the action run to the case and creates a mapping entry. If the action run has already been added to the case, an error is returned. Action runs that are 'running' cannot be added to a case.
vault_id Optional int The numerical value of the vault file's ID attribute. Copies a file in the vault to the case. If the vault file has already been added, an error is returned.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Specify only ONE item to merge per phantom.merge call, except in the case of an artifact_id and ioc_field. Specifying multiple parameters to merge at once may cause unpredictable results.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.merge start')

    success, message = phantom.merge(artifact_id=1)

    phantom.debug('phantom.merge results: success {}, message: {}'\
                  .format(success, message))

    return

add_artifact

 phantom.add_artifact(container=None, raw_data=None, cef_data=None, label=None, name=None,
    severity=None, identifier=None, artifact_type=None,
    field_mapping=None, trace=False, run_automation=False)

Add a new Artifact to the specified container. On successful artifact creation, this call returns a tuple of a success flag (bool), any response message (str) and the artifact id (int).

Parameter Required? Description
container Optional The container )int or dict) 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.
raw_data Required The raw artifact data that will be stored as-is and accessible from the artifacts. An empty dictionary can be used, see the following example.
cef_data Required The CEF representation of the data in original. CEF fields allow users to access the data more easily via the phantom.collect API in playbooks. An empty dictionary can be used, see the following example.
label Required The label expressing the class of artifact. For example event, netflow, AV Alert, etc.
name Required The name of the artifact.
severity Required The name of severity to which the artifact should be set. Supported values are 'high', 'medium', 'low', or the name of any active severity on the system.
identifier Required The source data identifier for the artifact. Generally this is a unique ID from a data source. A value of None will generate a GUID for the source data identifier.
artifact_type Required The type of the artifact like 'host' or 'network'
field_mapping Optional If CEF field names are not specific enough, the user can use this parameter to specify the contains type for this field. For example, the playbook could add an artifact whose CEF could have a field named 'user_hash'. Now this parameter can help convey to the platform that 'user_hash' is a hash type of field that can then be used to show contextual actions via Investigation. It takes a dictionary with a key of the field name, and a value of a list of contains strings, like this: {'user_hash':['md5']} . This sets user_hash to a contains type of 'md5' and hence any action that supports MD5 as an input parameter will show up in contextual actions.
trace Optional When set to True, more detailed output will be displayed in debug output.
run_automation Optional Default is False. If set to True, causes active playbooks to run when new artifacts are added to the container.

Here is a sample playbook: 

import phantom.rules as phantom
import json
import uuid

def on_start(container):

    artifacts = phantom.collect(container, 'artifacts:*', scope='all')
    phantom.debug(artifacts)

    raw = {}
    cef = {}
    cef['sourceAddress'] = '1.1.1.1'

    success, message, artifact_id = phantom.add_artifact(
        container=container, raw_data=raw, cef_data=cef, label='netflow',
        name='test_event', severity='high',
        identifier=None,
        artifact_type='network')

    phantom.debug('artifact added as id:'+str(artifact_id))

    artifacts = phantom.collect(container, 'artifacts:*', scope='all')
    phantom.debug(artifacts)

    # optionally user can specify a type for custom CEF fields.
    cef['foo'] = 'c8e5728b05c3ac46212c33535b65f183'
    field_mapping = {}
    field_mapping['foo'] = ['md5']

    success, message, artifact_id= phantom.add_artifact(
        container=container, raw_data=raw, cef_data=cef, label='netflow',
        name='test_event', severity='high',
        identifier=None,
        artifact_type='network',
        field_mapping=field_mapping)

    phantom.debug('artifact added as id:'+str(artifact_id))

    return


def on_finish(container, summary):

    return

The output of the above playbook in debugger shows the following results: 

Thu May 05 2016 14:03:42 GMT-0700 (PDT): Starting playbook '2498' testing on 'incident' id: '79'...
Thu May 05 2016 14:03:42 GMT-0700 (PDT): calling on_start(): on incident 'test_incident', id: 79.
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=False
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect(): will be limited to return 100 rows by default. To override, please provide limit parameter. 0 implies no limit
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect():  called with datapath 'artifacts:*', scope='all' and limit=100. Found 0 TOTAL artifacts
Thu May 05 2016 14:03:42 GMT-0700 (PDT):
[]
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.add_artifact() called
Thu May 05 2016 14:03:42 GMT-0700 (PDT): artifact added as id:122
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=False
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect(): will be limited to return 100 rows by default. To override, please provide limit parameter. 0 implies no limit
Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect():  called with datapath 'artifacts:*', scope='all' and limit=100. Found 1 TOTAL artifacts
Thu May 05 2016 14:03:43 GMT-0700 (PDT):
[
    {
        "create_time": 1462482222615,
        "id": 122,
        "severity": "high",
        "label": "netflow",
        "version": 1,
        "type": "network",
        "owner_id": 0,
        "cef": {
            "sourceAddress": "1.1.1.1"
        },
        "update_time": 1462482222615,
        "hash": "4cb608956567e4a95784382de5f81c1b",
        "description": "",
        "tags": [],
        "cef_types": {},
        "start_time": 1462482222615,
        "container_id": 79,
        "kill_chain": "",
        "playbook_run_id": 25,
        "data": {},
        "name": "test_event",
        "ingest_app_id": 0,
        "source_data_identifier": "0617e876-7ca1-407d-bab4-b5c3acf644f3",
        "end_time": 0
    }
]
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.add_artifact() called
Thu May 05 2016 14:03:43 GMT-0700 (PDT): artifact added as id:123
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=False
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect(): will be limited to return 100 rows by default. To override, please provide limit parameter. 0 implies no limit
Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect():  called with datapath 'artifacts:*', scope='all' and limit=100. Found 2 TOTAL artifacts
Thu May 05 2016 14:03:43 GMT-0700 (PDT):
[
    {
        "create_time": 1462482222615,
        "id": 122,
        "severity": "high",
        "label": "netflow",
        "version": 1,
        "type": "network",
        "owner_id": 0,
        "cef": {
            "sourceAddress": "1.1.1.1"
        },
        "update_time": 1462482222615,
        "hash": "4cb608956567e4a95784382de5f81c1b",
        "description": "",
        "tags": [],
        "cef_types": {},
        "start_time": 1462482222615,
        "container_id": 79,
        "kill_chain": "",
        "playbook_run_id": 25,
        "data": {},
        "name": "test_event",
        "ingest_app_id": 0,
        "source_data_identifier": "0617e876-7ca1-407d-bab4-b5c3acf644f3",
        "end_time": 0
    },
    {
        "create_time": 1462482223566,
        "id": 123,
        "severity": "high",
        "label": "netflow",
        "version": 1,
        "type": "network",
        "owner_id": 0,
        "cef": {
            "foo": "c8e5728b05c3ac46212c33535b65f183",
            "sourceAddress": "1.1.1.1"
        },
        "update_time": 1462482223566,
        "hash": "03134c15c2df2f7417f3ce360ce75d87",
        "description": "",
        "tags": [],
        "cef_types": {
            "foo": [
                "md5"
            ]
        },
        "start_time": 1462482223566,
        "container_id": 79,
        "kill_chain": "",
        "playbook_run_id": 25,
        "data": {},
        "name": "test_event",
        "ingest_app_id": 0,
        "source_data_identifier": "8dc4e4f8-0d81-4c64-8685-4742bd1d7bce",
        "end_time": 0
    }
]
Thu May 05 2016 14:03:43 GMT-0700 (PDT): No actions were executed
Thu May 05 2016 14:03:43 GMT-0700 (PDT): calling on_finish()
Thu May 05 2016 14:03:43 GMT-0700 (PDT):
Playbook '2498 (id: 58)' executed (playbook_run_id: 25) on incident 'test_incident'(id: 79).
Playbook execution status is:'success'
	No actions were executed for this playbook and 'incident'
Thu May 05 2016 14:03:43 GMT-0700 (PDT): {"message":"No actions were executed","playbook_run_id":25,"result":[],"status":"success"}

WARNING: When the playbook calls this API, the newly added artifact is not accessible to this instance of playbook run via phantom.collect() API id scope='new'. Hence the sample playbook shown above uses scope='all' in the phantom.collect() call to get all the artifacts including the one that was just added to the container.

close

phantom.close(container)

This is an API that allows Playbooks to close the specified container by setting its status to the default status of type Resolved.

WARNING: If using the save_object() API with auto_delete set to True and this container_id specified, the stored data will be deleted when this container is Resolved/Closed.

Parameter Required? Type Description
container Required dict A container object.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.close start')

    success, message = phantom.close(container)

    phantom.debug('phantom.close results: success: {}, message: {}, '\
                  .format(success, message))

    return

delete_artifact

phantom.delete_artifact(artifact_id=None)

This API allows artifacts to be deleted as identified by an artifact id. On completion it returns a bool indicating whether or not the operation was successful.

WARNING: Prior to Phantom 3.0.x, only manually created artifacts were allowed to be edited or deleted. Phantom 3.0.x onwards does not have this restriction, but requires that the user (default or automation) have the "delete container" permission.

Parameter Required? Type Description
artifact_id Required int The numerical ID of the artifact to be removed.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.delete_artifact start')

    success = phantom.delete_artifact(artifact_id=1)

    phantom.debug('phantom.delete_artifact results: success: {} '\
                  .format(success))

    return

pin

 phantom.pin(container=None, message=None,
            data=None, pin_type=None,
            pin_style=None, truncate=True,
            name=None, trace=False)

This API is used to pin data to a container. On completion it returns a tuple of a success flag (boolean), any response message (str), and the pin_id (int or None).

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.
message Optional, unless data is not provided. str A message associated with the pinned data.
data Optional, unless message is not provided. str The data to be pinned.
pin_type Optional str The type of pin to create, defaults to 'data': card, data.
pin_style Optional str Used to indicate the style of the pin, defaults to 'grey': grey, blue, red, white, and purple.
truncate Optional bool If the message or data fields are longer than the allowable character limit (based on pin_type) this flag will determine if the data should automatically be truncated or if an error should be raised. 'truncate=True', the default, will automatically truncate to the allowable character limit, 'truncate=False' will opt for raising an error and no pin will be created.
name Optional str Allows you to provide a name for the pin. If there is a name, it will be unique in a container. if you try to create a named pin on a container where a pin with that name already exists, it will update that pin instead of creating a new one. This parameters allows you to use this API to create or update a pin without needing to keep track of the pin's 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.pin start')

    success, message, pin_id = phantom.pin(container=container,
                                           data='192.168.1.7',
                                           message='This is a malicious IP',
                                           pin_type='card_small',
                                           pin_style='white')

    phantom.debug('phantom.pin results: success: {}, message: {}, '\
                  'pin_id: {}'.format(success, message, pin_id))

    return

update_pin

phantom.update_pin(pin_id=None, message=None, data=None, pin_type=None, pin_style=None)

This API is used to update an existing pin. On completion it will return a success flag (boolean) and a message (string).

Parameter Required? Type Description
pin_id Required int The ID of the pin to be updated.
message Optional str A new message string for the pin.
data Optional str A new data string for the pin.
pin_type Optional str A new type for the pin.
pin_style Optional str A new style for the pin.

NOTE:It is recommended to use named pins instead of this API to handle updating pins.

Example usage which will update an existing an existing pin's message and data. 

def on_start(container):

    phantom.debug('phantom.update_pin start')

    success, message = phantom.update_pin(pin_id=3, message="A new message",
                                          data="Some new data")

    phantom.debug(
        'phantom.update_pin results:'\
        'success: {}, message: {}'.format(success, message)
    )

    return

delete_pin

phantom.delete_pin(pin_id=None)

This API is used to delete an existing pin. On completion it will return a success flag (boolean) and a message (string)

Parameter Required? Type Description
pin_id Required int The ID of the pin to be deleted.

Example usage which will delete a pin. 

def on_start(container):

    phantom.debug('phantom.delete_pin start')

    success, message = phantom.delete_pin(pin_id=3)

    phantom.debug(
        'phantom.delete_pin results:'\
        'success: {}, message: {}'.format(success, message)
    )

    return

update

phantom.update(container, update_dict)

This API is used to make an update to a container. It returns a tuple of a success flag (boolean) and any response message (str). See the Containers REST documentation for more details.

Parameter Required? Description
container Required The container object to be updated.
update_dict Required A JSON serializable Python dictionary which contains updates to the container. Note: This should only contain fields you are changing.

Example usage which changes the container label to email and sensitivity to red: 

update_data = { "label": "email", "sensitivity": "red" }
success, message = phantom.update(container, update_data)

Example usage which appends a new tag to the container: 

current_tags = phantom.get_container(container['id'])['tags']
current_tags.append('newtag2')
update_data = { "tags" : current_tags }
success, message = phantom.update(container, update_data)

Changing the label on a container can potentially trigger automatic playbook runs on that container if there are any playbooks set to active and run on that container label. Standard automatic playbook run constraints apply, such as actions not running if the playbook had already run and there are no new artifacts, the container is in a closed state, etc. You can set "run_automation": false in the JSON if you wish to explicitly block playbooks running on this update call.

comment

phantom.comment(container=None, comment=None, trace=False)

This API is used to add a text comment to the container. On completion it returns a tuple of a success flag (boolean) and any response message.

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.
comment Required str The comment to add to the container.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    success, message = phantom.comment(comment='Example comment.')

    phantom.debug(
        'phantom.comment results: success: {}, message: {}' \
        .format(success, message)
    )

    return

add_task

phantom.add_task(container=None, name=None, owner=None, role=None, trace=False)

Use this API to add a task to a container. It returns a success flag (bool), a success or error message, and the id of the created task.

Parameter Required? Type Description
container Required int or dict The container to act on, can either be a numerical id or a container object.
name Optional str Name of the task to create.
owner Optional int or string Identifier for the owner to associate with the task.
role Optional int or string Identifier for the role to associate with the task.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom
        
def on_start(container):

        phantom.debug('phantom.add_task')

        success, message, task_id = phantom.add_task(container=container, name='task name')

        phantom.debug('phantom.add_task results: success {}, message {}, task_id {}'\
                      .format(success, message, task_id))

get_tasks

phantom.get_tasks(container=None, trace=False)

Use this API to get all the tasks associated with a container. It returns a tuple of a success flag (boolean), any response message (str), and data (dict).

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.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom
        
def on_start(container):
        
      phantom.debug('phantom.get_tasks')
        
      for task in phantom.get_tasks(container=container):
              phantom.debug('phantom.get_tasks results: success {}, message {}, data {}'\
                            .format(task['success'], task['message'], task['data']))

get_tags

phantom.get_tags(container=None, trace=False)

This API is used to retrieve the tags applied to a container. On completion it returns a tuple of a success flag (bool), any response message (str), and the list of tags (list of str or None).

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.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.get_tags start')

    success, message, tags = phantom.get_tags()

    phantom.debug(
        'phantom.get_tags results: success: {}, message: {}, tags: {}'\
        .format(success, message, tags)
    )

    return

add_tags

phantom.add_tags(container=None, tags=None, trace=False)

This API is used to add tags to a container. On completion it returns a tuple of a success flag (boolean), any response message (str).

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.
tags Required str or list of str The tag(s) to be added.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.add_tags start')

    success, message = phantom.add_tags(tags=['tag1', 'tag2'])

    phantom.debug(
        'phantom.add_tags results: success: {}, message: {}'\
        .format(success, message)
    )

    return

remove_tags

phantom.remove_tags(container=None, tags=None, trace=False)

This API is used to remove tags from a container. On completion it returns a tuple of a success flag (boolean), and any response message (str).

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.
tags Required str or list of str A string or list of strings containing the tag(s) to be removed.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.remove_tags start')

    success, message = phantom.remove_tags(tags=['tag1', 'tag2'])

    phantom.debug(
        'phantom.remove_tags results: success: {}, message: {}'\
        .format(success, message)
    )

    return

add_note

phantom.add_note(container=None, note_type=None, trace=False)

This API is used to add a note of the specified type to the container. On completion it returns a tuple of a success flag (boolean), any response message (str), and the note_id (int).

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.
note_type Optional string Type of note you want to create. Valid options are "general", "artifact", or "task". For types "artifact" or "task" you must supply the artifact_id or task_id as additional parameters.
artifact_id Dependent int Id of the artifact for which you want notes.
task_id Dependent int Id of the task for which you want notes.
title Optional string Title for the note.
content Optional string Content for the note.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

      phantom.debug('phantom.add_note')

      success, message, note_id = phantom.add_note(container=container, note_type='general', title='This is a title.', content='This is the note body.')

      phantom.debug('phantom.add_note results: success {}, message {}, note_id {}'\
                    .format(success, message, note_id))

get_notes

phantom.get_notes(container=None, artifact_id=None, task_id=None, trace=False)

This API is used to get all the notes for the requested object, either a container, a task, or an artifact. On completion it returns the requested notes.

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.
artifact_id Optional int Id of the artifact for which you want notes.
task_id Optional int Id of the task for which you want notes.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom
    
def on_start(container):
    
      phantom.debug('phantom.get_notes')
    
      for note in phantom.get_notes(container=container):
              phantom.debug('phantom.get_notes results: success {}, message {}, data {}'\
                            .format(note['success'], note['message'], note['data']))

get_phase

phantom.get_phase(container=None, trace=False)

This API is used to retrieve the current phase of the container. On completion it returns a tuple of a success flag (bool), any response message (str), the phase_id (int) and the phase_name (str).

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.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.get_phase start')

    success, message, phase_id, phase_name = phantom.get_phase()

    phantom.debug(
        'phantom.get_phase results: success: {}, message: {}, phase_id: {}, phase_name: {}'\
        .format(success, message, phase_id, phase_name)
    )

    return

set_phase

phantom.set_phase(container=None, phase=None, trace=False)

This API is used to set the current phase of the container. Returns a tuple of a success flag (boolean), and a message if available (str).

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.
phase Required str or int Either phase name (str) or a numerical id (int) for the phase to apply.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_phase start')

    success, message = phantom.set_phase(phase='Example Phase')

    phantom.debug(
        'phantom.set_phase results: success: {}, message: {}'\
        .format(success, message)
    )

    return

set_duetime

phantom.set_duetime(container=None, operation='+', minutes=None, trace=False)

This API is used to modify the due time of a container. Returns a tuple of a success flag (boolean), a message if available (str), and the new due time (str).

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.
operation Optional str A choice of 'add'/'+' or 'subtract'/'-', defaults to '+'.
minutes Required int The number of minutes to add or subtract.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_duetime start')

    success, message, new_due_time = phantom.set_duetime(minutes=180)

    phantom.debug(
        'phantom.set_duetime results: success: {}, message: {}, new_due_time: {}'
        .format(success, message, new_due_time)
    )

    return

set_owner

phantom.set_owner(container=None, task_id=Int, user='', role='', trace=False)

This is an API that allows users to dynamically assign a container or task to a user or role. On completion it returns a tuple of a success flag (boolean), and a message if available (str).

Parameter Required? Type Description
container Optional int or dict The ID of the container being assigned ownership, either the numerical id or the container object. If no container is provided, the currently running container will be used.
task_id Optional int The task_id of the task to be assigned ownership. If an empty string is sent, this API will remove any owners from the task.
user Optional str or int Valid Phantom user name (str) or id (int) to be assigned, or an empty string to remove assignments the container. Note that if you do not set a user or you send an empty string, you will remove assignments from the container.
role Optional int or str Name or id of the role. If no user or role values are set, or empty strings are sent, role assignments are removed from the container or task.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Sample playbook: 

import phantom.rules as phantom

def on_start(container):

  # assign container to user@company.com
  success, message = phantom.set_owner(container=container, user='user@company.com')
  phantom.debug(
      'phantom.set_owner results: success: {}, message: {}'
      .format(success, message)
  )

  # container unassigned, no user assigned
  success, message = phantom.set_owner(container=container, user="")
  phantom.debug(
      'phantom.set_owner results: success: {}, message: {}'
      .format(success, message)
  )
  return

set_status

phantom.set_status(container=None, status=None, trace=False)

This API is used to update the status of a container. Returns a tuple of a success flag (boolean), and a message if available (str).

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.
status Required str The status, either 'new', 'open', 'resolved', 'closed', or a custom status defined by an administrator. Please see the note following this table if you have been using set_status with 'resolved' prior to Splunk Phantom 4.5.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Prior to Splunk Phantom 4.5 the statuses 'resolved' and 'closed' were interchangeable. With customizable statuses, this is no longer true. For backwards compatibility, if there is no active status named 'resolved', calling this API with a value of 'resolved' causes the set_status call to retry with a value of 'closed'. If you depend on 'resolved' and 'closed' being interchangeable, you should call phantom.set_status() with status="closed" instead.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_status start')

    success, message = phantom.set_status(status='open')

    phantom.debug(
        'phantom.set_status results: success: {}, message: {}'\
        .format(success, message)
    )

    return

set_label

phantom.set_label(container=None, label=None, trace=False)

This is an API that allows users to dynamically change the 'label' of a container. The label must already exist in system settings to be applied to a container. On completion it returns a tuple of a success flag (boolean), and any response message (str).

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.
label Required str A string containing the label to be applied.
trace Optional bool When set to True, more detailed output will be displayed in debug output.

Example: 

import phantom.rules as phantom

def on_start(container):

    phantom.debug('phantom.set_label start')

    success, message = phantom.set_label(label='Example label')

    phantom.debug(
        'phantom.set_label results: success: {}, message: {}'\
        .format(success, message)
    )

    return

set_severity

phantom.set_severity(container, severity)

This is an API that allows users to dynamically change the 'severity' of a container, while it is being processed.

Parameter Required? Type Description
container Required dict The current container object.
severity Required str String containing the name of the desired severity.

set_sensitivity

phantom.set_sensitivity(container, sensitivity)

This is an API that allows users to dynamically change the 'sensitivity' of a container, while it is being processed. The system supports 4 levels of 'sensitivity' in accordance to the US-CERT Traffic Light Protocol- red, amber, green, and white.

Parameter Required? Type Description
container Required dict The current container object.
sensitivity Required str String containing the desired sensitivity. ("red", "amber", "green", or "white")

completed

phantom.completed(action_names=None, trace=False)

This API checks to see if all of the actions in the user given list of action_names have finished executing or not. Succeeded or Failed implies 'Done'. Returns True if and only if all the actions are done or else returns False.

Parameter Required? Type Description
action_names Optional dict A list of names given to an action via phantom.act() API in the parameter name.
trace Optional Boolean When set to True, more detailed output will be displayed in debug output. 
def join_add_tag_1(action=None, success=None, container=None, results=None,
                   handle=None, filtered_artifacts=None, filtered_results=None):
    # this is a "join" function. It is a callback for 2 separate actions
    # check if all connected incoming actions are done i.e. have succeeded or failed
    # only invoke add_tag_1 when both have completed

    if phantom.completed(action_names=[ 'block_ip_1','block_domain_1' ]):

        # call connected block "add_tag_1"
        add_tag_1(container=container, handle=handle)

    return
Last modified on 16 August, 2021
Playbook automation API   Data management automation API

This documentation applies to the following versions of Splunk® Phantom (Legacy): 4.8

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







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