Splunk® Phantom (Legacy)
Python Playbook API Reference for Splunk Phantom
- Documentation
- Splunk® Phantom (Legacy)
- Python Playbook API Reference for Splunk Phantom
- Container automation API
Overview
- About Splunk Phantom playbook automation APIs
- Understanding containers
- Understanding artifacts
- Understanding datapaths
- Understanding apps and assets
- Understanding callbacks
- Convert playbooks or custom functions from Python 2 to Python 3
Automation API
- Playbook automation API
- Container automation API
- Data management automation API
- Data access automation API
- Session automation API
- Vault automation API
- Network automation API
Deprecated API
- Deprecated automation API
- Container automation API compatibility with custom...
- How to import containers via rest api?
- Getting containers from Jan to March using REST AP...
- SOAR Cloud - Bulk Delete Containers through API?
- Splunk search REST API - Is there a way to search ...
- Is it possible to add a task in phase of a workboo...
- REST API to automate CSV creation/export using Pyt...
- Is there a way to edit note in a container via the...
- Exporting search to csv contains headers, exportin...
- How to upload/attach a file (vault) to a container...
Read more...
Splunk Phantom 4.10.7 is the final release of Splunk's Security Orchestration, Automation, and Response (SOAR) system to be called Splunk Phantom. All later versions are named Splunk SOAR (On-premises). For more information, see the Splunk SOAR (On-premises) documentation.
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 responses to a security breach. The following APIs are supported to leverage the capabilities of data management automation using playbooks.
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 tothe 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. |
Some effort is made to prevent duplicate artifacts being added using the add_artifact() API. Each request to add an artifact generates a unique hash based on the body of the add_artifact() API call. Multiple calls to the add_artifact() API with the same hash will not add multiple instances of the same artifact.
This sample uses the phantom.add_artifact() API.
import phantom.rules as phantomimport jsonimport uuiddef 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)) returndef on_finish(container, summary): returnThe 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=FalseThu 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 limitThu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect(): called with datapath 'artifacts:*', scope='all' and limit=100. Found 0 TOTAL artifactsThu May 05 2016 14:03:42 GMT-0700 (PDT):[]Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.add_artifact() calledThu May 05 2016 14:03:42 GMT-0700 (PDT): artifact added as id:122Thu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=FalseThu 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 limitThu May 05 2016 14:03:42 GMT-0700 (PDT): phantom.collect(): called with datapath 'artifacts:*', scope='all' and limit=100. Found 1 TOTAL artifactsThu 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() calledThu May 05 2016 14:03:43 GMT-0700 (PDT): artifact added as id:123Thu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect() called with datapath: artifacts:*, limit = 100 and none_if_first=FalseThu 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 limitThu May 05 2016 14:03:43 GMT-0700 (PDT): phantom.collect(): called with datapath 'artifacts:*', scope='all' and limit=100. Found 2 TOTAL artifactsThu 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 executedThu 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 (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. |
| trace | Optional | Boolean | Trace is a flag related tothe 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 phantomdef 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 tothe 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 phantomdef 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) ) returnadd_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 tothe 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 Splunk Phantom web server.
The add_workbook API is supported from within a custom function.
phantom.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 tothe 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 phantomdef 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 returnclose
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 phantomdef on_start(container): phantom.debug('phantom.close start') success, message = phantom.close(container) phantom.debug('phantom.close results: success: {}, message: {}, '\ .format(success, message)) returncomment
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 tothe 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 phantomdef on_start(container): success, message = phantom.comment(comment='Example comment.') phantom.debug( 'phantom.comment results: success: {}, message: {}' \ .format(success, message) ) returncreate_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 tothe 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 Splunk Phantom 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 phantomdef 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) ) returndelete_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 Phantom 3.0.x, only manually created artifacts were allowed to be edited or deleted. 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 phantomdef 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)) returndelete_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) ) returnget_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 tothe 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 tothe 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 phantomdef 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) ) returnget_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 tothe 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 phantomdef 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) ) returnget_tasks
Use the get_tasks API to get all the tasks associated with a container. This API returns a tuple of a success flag (Boolean), any response message (string), and data (dictionary).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 tothe 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 tothe 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 phantomdef 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)) returnpin
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 'data': card, data. |
| pin_style | Optional | String | The style of the pin. The default pin style type is 'grey': grey, blue, red, white, and purple. |
| 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 tothe 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 phantomdef 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)) returnpromote
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 tothe 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 phantomdef 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) ) returnremove_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 tothe 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 phantomdef 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) ) returnset_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 tothe 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 phantomdef 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) ) returnset_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 tothe 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 phantomdef 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) ) returnset_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 Splunk Phantom 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 tothe 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 phantomdef 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) ) returnset_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 tothe 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 phantomdef 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) ) returnset_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 tothe 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 phantomdef 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) ) returnupdate
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, Kwargs)
| 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)| Kwarg | Required? | Description |
|---|---|---|
| unify_datetime_format=bool | Optional | Default is 'False'. Change the format of the datetime values for the following container fields:
When set to True datetime values will use the format |
Changing the label of a container can trigger automatic playbook runs on that container, if there are playbooks set to 'active' that will run on that container label. Standard automatic playbook run constraints apply such as: actions will not run if the playbook has already run and the container has no new artifacts or if the container is closed.You can set "run_automation": false in the JSON to block playbooks running on this update call.
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) ) returnLast modified on 17 August, 2021
| Playbook automation API | Data management automation API |
This documentation applies to the following versions of Splunk® Phantom (Legacy): 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7
Download manual
Download this page
Back To Top
Container automation API
- add_artifact
- add_note
- add_tags
- add_task
- add_workbook
- close
- comment
- create_container
- delete_artifact
- delete_pin
- get_notes
- get_phase
- get_tags
- get_tasks
- merge
- pin
- promote
- remove_tags
- set_duetime
- set_label
- set_owner
- set_phase
- set_sensitivity
- set_severity
- set_status
- update
- update_pin
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.
We use our own and third-party cookies to provide you with a great online experience. We also use these cookies to improve our products and services, support our marketing campaigns, and advertise to you on our website and other websites. Some cookies may continue to collect information after you have left our website. Learn more (including how to update your settings) here »
Closing this box indicates that you accept our Cookie Policy.
