After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:
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
Playbook automation API | Data management automation API |
This documentation applies to the following versions of Splunk® SOAR (On-premises): 6.2.1, 6.2.2, 6.3.0
Feedback submitted, thanks!