Container 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 data management automation using containers.

add_artifact

Add a new artifact to the specified container. After creating an artifact, this call returns a tuple of a success flag (Boolean), any response message (string), and the artifact ID (integer).

The add_artifact API is supported from within a custom function.

 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)

Parameter	Required?	Description
container	Optional	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.
raw_data	Required	The raw artifact data is stored as-is and is accessible from the artifacts. You can also use an empty dictionary.
cef_data	Required	The Common Event Format (CEF) representation of the original data. You can also use an empty dictionary.
label	Required	The label expressing the class of artifact. For example, event or netflow.
name	Required	The name of the artifact.
severity	Required	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 generates a GUID for the source data identifier.
artifact_type	Required	The type of the artifact, such as host or network.
field_mapping	Optional	If CEF field names are not specific enough, use this parameter to specify the contains type for the field. For example, if you add a playbook with an artifact that has a CEF field named user_hash, 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.
trace	Optional	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.
run_automation	Optional	Default is False. If set to True, the parameter causes active playbooks to run when new artifacts are added to the container.

This sample uses the phantom.add_artifact() API.

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 playbook in the 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"}

When the playbook calls this API, the newly added artifact is not accessible to this instance of the playbook run through the phantom.collect() API id scope='new'. The previous sample uses scope='all' in the phantom.collect() call to get all the artifacts including the one that was added to the container.

add_note

Use the add_note API to add a note of the specified type to the container. On completion it returns a tuple of a success flag, any response messages, and the note ID.

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

The add_note API is supported from within a custom function.

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.
note_type	Optional	String	The type of note you want to create. Valid options are "general", "artifact", or "task". For "artifact" or "task" types you must supply the artifact_id or task_id as additional parameters.
note_format	Optional	String	The format of the note. Valid options are HTML or markdown. If the format is not provided, HTML is the default.
artifact_id	Dependent	Integer	ID of the artifact for which you want notes.
task_id	Dependent	Integer	ID of the task for which you want notes.
title	Optional	String	Title for the note.
content	Optional	String	Content for the note. The content of a note can include a limited set of HTML and Markdown. See Using HTML and Markdown in notes in the manual for a list of what is and what is not supported.
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.

This sample uses the phantom.add_note API.

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))

add_tags

Use the add_tags API to add tags to a container. On completion, the call returns a success flag and any response messages.

The add_tags API is supported from within a custom function.

phantom.add_tags(container=None, tags=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.
tags	Required	String(s)	The tags to be added.
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.

This sample uses the phantom.add_tags API.

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

add_task

Use the add_task API to add a task to a container. It returns a success flag, a success or error message, and the ID of the created task. The add_task API is supported from within a custom function.

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

Parameter	Required?	Type	Description
container	Required	Integer or dictionary	The container to act on. This parameter can either be a numerical ID or a container object.
name	Optional	String	Name of the task to create.
owner	Optional	Integer or string	Identifier you can associate with the task.
role	Optional	Integer or string	Identifier for the role to associate with the task.
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.

This sample uses the phantom.add_task() API.

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))

add_workbook

Use the add_workbook API to add a workbook to a container. This API returns a two-tuple of a success flag and a message. The success flag is set to true if the workbook was successfully added, otherwise it is set to false. The message originates from the HTTP response from your web server.

The add_workbook API is supported from within a custom function.

def add_workbook(container=None, workbook_id=None, trace=False)

Parameter	Required?	Type	Description
container	Yes	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.
workbook_id	Yes	Integer	The ID of the workbook to be added.
trace	No	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.

This sample uses the phantom.add_workbook API.

import phantom.rules as phantom
def on_start(container):
    phantom.debug('phantom.add_workbook start')
    phishing_workbook_id = 4
   success, message = phantom.add_tags(workbook_id=phishing_workbook_id)
   success, message = phantom.add_workbook(workbook_id=phishing_workbook_id)
    if success:
        phantom.debug('phantom.add_workbook succeeded. API message: {}'.format(message))
        # Call on_success callback
    else:
        phantom.debug('phantom.add_workbook failed. API message: {}'.format(message))
        # Call on_fail callback
    return

close

The close API allows playbooks to close the specified container by setting its status to the default status of Resolved.

The close API is supported from within a custom function.

If using the save_object() API with the auto_delete value set to True, and the container_id value specified, the stored data is deleted when this container is closed or resolved.

phantom.close(container)

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

This sample uses the phantom.close() API.

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

comment

Use the comment API to add a text comment to the container. On completion, the API returns a tuple of a success flag and any response messages.

The comment API is supported from within a custom function.

phantom.comment(container=None, comment=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.
comment	Required	String	The comment to add to the container.
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.

This sample uses the phantom.comment() API.

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

create_container

Use the create_container API to create a new container. It returns a tuple of a success flag, any response message, and the numeric ID of the created container. If no container was created, the ID returned is None. Once a container is created, it is possible to retrieve container data using get_container by passing the created container_id.

The create_container API is supported from within a custom function.

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

Parameter	Required?	Type	Description
name	Required	String	The name of the case.
label	Required	String	The label of the case.
container_type	Optional	String	The type of container to create, either default or case.
template	Optional	Integer or String	Applies to containers of type case, and indicates the template to use on creation. If the container type is case and no template is provided, the default template is used. If no default template is set, 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.
tenant_id	Optional	Integer or String	The tenant ID as per the /rest/tenant API. This field is required if multi-tenancy is enabled.

This sample uses the phantom.create_container() API.

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

delete_artifact

The delete_artifact API allows artifacts to be deleted as identified by an artifact ID. On completion, this API returns a Boolean value indicating whether the operation was successful.

Prior to Splunk Phantom 3.0.x, only manually created artifacts were allowed to be edited or deleted. Splunk Phantom 3.0.x and later does not have this restriction, but requires that the user, either default or automation, have the delete container permission.

The delete_artifact API is supported from within a custom function.

phantom.delete_artifact(artifact_id=None)

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

This sample uses the phantom.delete_artifact API.

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

delete_pin

The delete_pin API is used to delete an existing pin. On completion, this API returns a success flag and a message.

The delete_pin API is supported from within a custom function.

phantom.delete_pin(pin_id=None)

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

Example usage to 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

get_notes

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

The get_notes API is supported from within a custom function.

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

Parameter	Required?	Type	Description
container	Optional	Integer or Dictionary	The container to act on. This container can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
artifact_id	Optional	Integer	ID of the artifact you want notes for.
task_id	Optional	Integer	ID of the task you want notes for.
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.

This sample uses the phantom.get_notes() API.

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

Use the get_phase API to retrieve the current phase of the container. On completion, this API returns a tuple of a success flag, any response messages, the phase ID and the phase name.

The get_phase API is supported from within a custom function.

phantom.get_phase(container=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.
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.

This sample uses the phantom.get_phase() API.

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

get_tags

Use the get_tags API to retrieve the tags applied to a container. On completion, this API returns a tuple of a success flag, a response message, and a list of tags.

The get_tags API is supported from within a custom function.

phantom.get_tags(container=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.
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.

This sample uses the phantom.get_tags() API.

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

get_tasks

Use the get_tasks API to get all the tasks associated with a container. This API returns a generator object. Each item in the generator is a dictionary containing the following keys: a boolean flag "success", a response message "message" and a dictionary "data".

The get_tasks API is supported from within a custom function.

phantom.get_tasks(container=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.
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.

This sample uses the phantom.get_tasks() API.

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']))

merge

Use the merge API to add items to a case. The merge API returns a tuple of a success flag and any response messages.

The merge API is supported from within a custom function.

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

Parameter	Required?	Type	Description
case	Optional	Integer or dictionary	The case to add items to. This parameter can either be a numerical ID or a container object. If no case is provided, the currently running container is used.
container_id	Optional	Integer	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 are not copied.
artifact_id	Optional	Integer	The numerical ID of an artifact to add. This parameter 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	String	Common Event Format (CEF) key of the indicators of compromise (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 and artifact pair has already been added to the case, an error is returned.
playbook_run_id	Optional	Integer	The numerical ID of the 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	Integer	The numerical ID of an action run, which can be retrieved from an action object or by using the get_summary API, which enumerates all the actions that were executed in the playbook. This parameter 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	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.
note_title	Optional	String	The title of the note.
note_description	Optional	String	The description of the note.

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

This sample uses the phantom.merge API.

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

pin

Use the pin API to pin data to a container. Once complete, the API returns a tuple of a success flag, any response messages, and the pin ID.

The pin API is supported from within a custom function.

 phantom.pin(container=None, message=None,
            data=None, pin_type=None,
            pin_style=None, truncate=True,
            name=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.
message	Optional, unless the data parameter is not provided	String	A message associated with the pinned data.
data	Optional, unless the message parameter is not provided	String	The data to be pinned.
pin_type	Optional	String	The type of pin to create. The default pin type is 'card': card, data.
pin_style	Optional	String	The style of the pin. The default pin style type is 'grey'. Options are: transparent, grey, green, blue, violet, coral, red, pink, crimson, orange, dark orange, topaz.
truncate	Optional	Boolean	If the message or data fields are longer than the character limit, this flag determines if the data is automatically truncated or if an error is raised. The default is truncate=True, and the flag automatically truncates the message to the allowable character limit. truncate=False raises an error and no pin is created.
name	Optional	String	The name for the pin. If there is a name, it is unique in a container. If you try to create a named pin on a container where a pin with that name already exists, it updates that pin instead of creating a new one. This parameter lets you use the pin API to create or update a pin without needing to keep track of the pin 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.

This sample uses the phantom.pin() API.

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

promote

The promote API is used to promote a container to a case. The promote API is supported from within a custom function.

phantom.promote(container=None, template=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.
template	Optional	Integer or string	Either a numerical ID or the name of the template to use for the case. If no template is provided, the default template is used. If no default is set, 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.

This sample uses the phantom.promote() API.

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

remove_tags

The remove_tags API is used to remove tags from a container. Upon completion, the API returns a success flag and any response messages. The remove_tags API is supported from within a custom function.

phantom.remove_tags(container=None, tags=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.
tags	Required	String(s)	A string or list of strings that contains the tags to be removed.
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.

This sample uses the phantom.remove_tags() API.

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

set_duetime

Use the set_duetime API to modify the due time of a container. This parameter returns a tuple of a success flag, a message if available, and the new due time.

The set_duetime API is supported from within a custom function.

phantom.set_duetime(container=None, operation='+', minutes=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.
operation	Optional	String	A choice of add or + or subtract -, defaults to +.
minutes	Required	Integer	The number of minutes to add or subtract.
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.

This sample uses the phantom.set_duetime() API.

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_label

The set_label API allows users to dynamically change the label of a container. The label must already exist in system settings to be applied to a container. Upon completion, the API returns a tuple of a success flag and any response messages.

The set_label API is supported from within a custom function.

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

Parameter	Required?	Type	Description
container	Optional	Integer or Dictionary	The container to act on. It can either be a numerical ID or a container object. If no container is provided, the currently running container is used.
label	Required	String	A string containing the label to apply.
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.

This sample uses the phantom.set_label API.

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_owner

Use the set_owner API to dynamically assign a container or task to a user or role. Upon completion, the API returns a tuple of a success flag and a message, if available.

The set_owner API is supported from within a custom function.

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

Parameter	Required?	Type	Description
container	Optional	Integer or dictionary	The ID of the container assigned ownership. If no container is provided, the currently running container is used.
task_id	Optional	Integer	The task ID of the task assigned ownership. If an empty string is sent, this API removes any owners from the task.
user	Optional	String or integer	Valid username or ID assigned, or an empty string to remove assignments on the container. If you don't set a user, or you send an empty string, you remove assignments from the container.
role	Optional	Integer or string	The name or ID of the role. If no user or role values are set or if empty strings are sent, role assignments are removed from the container or task.
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.

This sample uses the phantom.set_owner() API.

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_phase

Use the set_phase API to set the current phase of the container. This parameter returns a tuple of a success flag and a message, if available.

The set_phase API is supported from within a custom function.

phantom.set_phase(container=None, phase=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.
phase	Required	String or Integer	Use either a phase name or a numerical ID for the phase to apply.
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.

This sample uses the phantom.set_phase API.

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_sensitivity

Use the set_sensitivity API to dynamically change the sensitivity of a container while it is being processed. The system supports four levels of sensitivity in accordance to the US-CERT Traffic Light Protocol. The levels supported are red, amber, green, and white.

The set_sensitivity API is supported from within a custom function.

phantom.set_sensitivity(container, sensitivity)

Parameter	Required?	Type	Description
container	Required	Dictionary	The current container object.
sensitivity	Required	String	The desired sensitivity. Options include red, amber, green, and white.

set_severity

Use the set_severity API to dynamically change the severity of a container while it is being processed.

The set_severity API is supported from within a custom function.

phantom.set_severity(container, severity)

Parameter	Required?	Type	Description
container	Required	Dictionary	The current container object.
severity	Required	String	The name of your desired severity level.

set_status

Use the set_status API to update the status of a container. Returns a tuple of a success flag and a message, if available.

The set_status API is supported from within a custom function.

phantom.set_status(container=None, status=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.
status	Required	String	Set the status of either new, open, resolved, closed, or a custom status defined by an administrator.
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.

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

This sample uses the phantom.set_status API.

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

update

Use the update API to make an update to a container. It returns a tuple of a success flag and any response messages.

The update API is supported from within a custom function.

phantom.update(container, update_dict)

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. Include only the fields that you want to change.

Example usage to change the container label to email and sensitivity to red.

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

Example usage to append 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 that 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, or if the container is in a closed state. You can set "run_automation": false in the JSON to block playbooks running on this update call.

Updating and reading custom field values

For information on updating and reading custom field values with the container.update API, refer to Update and read custom field values.

update_pin

Use the update_pin API to update an existing pin. Upon completion, this API returns a success flag and a message.

The update_pin API is supported from within a custom function.

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

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

Use named pins instead of this API to handle updating pins.

In this example, an existing pin's message and data is updated.

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