REST Containers
Create, modify, and manage containers using the following rest endpoints.
/rest/container
Manage containers and their associated authorized users, notes, pin templates, comments, attachments, and options.
Syntax
https://<username>:<password>@<host>/rest/container
POST
Create a container.
Request parameters
Containers are modified with the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| artifacts | optional | JSON Array of Objects | Enables creation of artifacts in the same POST with the container. Must be a list of JSON objects containing the artifact data. See the REST documentation on artifacts regarding artifact format and the note below on run_automation for additional information. |
| asset_id | optional | integer | Id of the asset which produced the container. |
| close_time | optional | ISO 8601 formatted timestamp | Date and time (in UTC) when the container was closed. |
| custom_fields | optional | JSON Object | JSON objects contains key/value pairs for custom container fields. There may be required fields defined in the administration settings. See the Administrator's Guide for details. |
| data | optional | JSON Object | Custom data field. |
| description | optional | string | A brief useful description of the behavior tracked by this container. |
| due_time | optional | ISO 8601 formatted timestamp | Date and time (in UTC) when the SLA for this container will expire. |
| end_time | optional | ISO 8601 formatted timestamp | Date and time (in UTC) when the behavior tracked by the container stopped. |
| ingest_app_id | optional | integer | Id of the app which produced the container. |
| kill_chain | optional | string | Cyber kill chain. One of
|
| label | required | string | The label classifies the container. This field is required, however if the label can be determined using the app or an automation user's default label, then it may be omitted. Specifying a label overrides the default. Some example labels:
|
| name | required | string | A short friendly name for the container. |
| owner_id | optional | integer or string | Phantom account username or numeric Id. Id of the user who is the current owner of the container. You can use owner_id or role_id, but not both at the same time. |
| role_id | optional | integer or string | Phantom role name or numeric Id as per the /rest/role API. Id of the role that is the current owner of the container, if you don't know the username of the owner. You can use owner_id or role_id, but not both at the same time. |
| run_automation | optional | boolean | Not a container data field: This parameter instructs Phantom to run automation upon creation or update of the container, and defaults to False. |
| sensitivity | optional | string | Describes how sensitive material related to the container is. One of:
|
| severity | optional | string | Describes how severe material related to the container is. Helps to determine the SLA applied to Actions related to the container. Either one of Low, Medium, High, or a custom severity name created by an administrator.
|
| source_data_identifier | optional | string | Id which can be used to find this container in the source product. (e.g. the container was retrieved from a SIEM, this is the Id in the SIEM) Must be unique per container, if no identifier is provided, a unique value is generated. |
| start_time | optional | ISO 8601 formatted timestamp | Date and time (in UTC) when the behavior tracked by the container started. |
| open_time | optional | ISO 8601 formatted timestamp | Date and time (in UTC) when the container was opened or reopened. |
| status | optional | string | Current status of the container. Either one of New, Open, Closed, or a custom status created by an administrator. |
| tags | optional | Array of strings | 0 or more tags associated with the asset. A simple string can also be used for a single tag. |
| tenant_id | optional | integer or string | Phantom tenant ID as per the /rest/tenant API. While this field is optional, it is required if multi-tenancy is enabled. |
| container_type | optional | string | The container type. Valid values are 'default' or 'case'. Containers with the 'default' type are events in the user interface. |
| template_id | optional | integer | The ID of the workbook to apply to this container. If provided, the phases and tasks from the specified workbook will be added to this container. The workbook ID can be found using the /rest/workbook_template API. |
| authorized_users | optional | list of integers | Phantom user IDs as per the /rest/ph_user API, for example [1,5,6,7]. The authorized user list is always updated to include only the list passed by this command. Authorized access can only be granted to the subset of users who are already assigned to a label that has edit permissions on the container. Some teams only want to allow certain people to work on particular types of cases, so just because people are assigned to the label, it doesn't mean they all need access to a particular case. Admins always have access to all containers, so they don't need to be added to the authorized list. |
To optimize performance when creating multiple artifacts, first create the container, then create all artifacts except the last with run_automation set to False, and then create the last artifact with run_automation set to True. This will cause automation such as active playbooks to run only after all artifacts have been added. To be even more efficient, you can create the container and artifacts in a single POST (see above) in which case you should not set run_automation at all, as Phantom will automatically set run_automation after the last artifact is created.
Example request
Create a container named "Example Container" with a label of "events" and assign it to an "owner."
curl -k -u admin:changeme https://localhost/rest/container \
-d '{
"asset_id": 12,
"artifacts": [ ],
"custom_fields": {},
"data": { },
"description": "Useful description of this container.",
"due_time": "2019-03-21T19:29:23.759Z",
"label": "events",
"name": "Example Container",
"owner_id": "user@mail.example.com",
"run_automation": false,
"sensitivity": "red",
"severity": "high",
"source_data_identifier": "4",
"status": "new",
"start_time": "2019-03-21T19:28:13.759Z",
"open_time": "2019-03-21T19:29:00.141Z",
"tags": ["tag1", "tag2"],
"container_type": "case"
}'
Success example response
A successful POST returns a success indicator and the Id of the newly created container.
{
"id": 8,
"success": true
}
Failed example response
Posting a JSON that matches the asset and source_data_identifier of an existing container results in a duplication error. The response also returns the Id of the matching container.
{
"existing_container_id": 8,
"failed": true,
"message": "duplicate with source_data_identifier 1 and asset_id 4"
}
Example request
Create a container and assign a role instead of an owner.
curl -k -u admin:changeme https://localhost/rest/container \
-d '{
"name": "Example Container",
"label": "events",
"template_id": 4,
"status": "new",
"role_id": "1",
"severity": "medium",
"sensitivity": "amber",
"source_data_identifier": "4",
"due_time": "2019-03-21T19:29:23.759Z",
"container_type": "default"
}'
Success example response
A successful POST returns a success indicator and the Id of the newly created container.
{
"new_artifact_ids": [],
"id": 52,
"success": true
}
POST
Update existing containers and revise the associated authorized user list.
Request parameters
See Create a container for the full parameters.
Example request
Update container IDs 44 and 45 and revise the associated authorized user list with the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| id | required | integer | ID of the container for which to set the authorized user list. |
| authorized_users | optional | list of integers | Phantom user IDs from the /rest/ph_user API, for example [1,5,6,7]. The authorized user list is always updated to include only the list passed by this command. |
curl -k -u admin:changeme https://localhost/rest/container \
-d '[
{
"id": 44,
"authorized_users": [8, 9]
},
{
"id": 45,
"authorized_users": [8, 9]
}
]'
Example response
A successful POST returns a success indicator and the Id of the updated container.
[
{
"id": 44,
"success": true
},
{
"id": 45,
"success": true
}
]
Example request
Update container IDs 44 and 45 and clear the associated authorized user list. Leave the authorized_users list empty to clear it.
curl -k -u admin:changeme https://localhost/rest/container \
-d '[
{
"id": 44,
"authorized_users": []
},
{
"id": 45,
"authorized_users": []
}
]'
Example response
[
{
"id": 44,
"success": true
},
{
"id": 45,
"success": true
}
]
/rest/container optional query parameters
Query all containers for authorized users with the addition of a query parameter.
/rest/container?_annotation_authorized_users
The Container LIST API will also display the authorized field when the annotation is provided.
Syntax
https://<username>:<password>@<host>/rest/container?_annotation_authorized_users
GET
Get the authorized users.
Example request
Get the authorized users.
curl -k -u admin:changeme https://localhost/rest/container?_annotation_authorized_users -G -X GET
Example response
A successful GET will return back a JSON formatted list of key names and their data. If there are no users associated with an authorized user container list, then an empty list is returned. If the calling user is an admin or on the authorized user list, then this field is a list of user IDs.
[
{
...
"authorized_users": [],
},
{
...
"authorized_users": [
3,
4
],
}
]
/rest/container/<container_id>
Update an existing container.
Syntax
https://<username>:<password>@<host>/rest/container/<container_id>
POST
Update an existing container that is assigned to a user and assign a role instead.
Request parameters
See /rest/container for parameters.
Example request
Update container Id 51 and assign it to role Id 2.
curl -k -u admin:changeme https://localhost/rest/container/51 \
-d '{
"status": "new",
"id": 51,
"role_id": "2"
}'
Example response
A successful POST returns a success indicator and the Id of the previously created container.
{
"id": 51,
"success": true
}
POST
Update an existing container and assign authorized users.
Request parameters
See Create a container for the full parameters.
Example request
Update container 51 and assign authorized users with the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| id | required | integer | ID of the container for which to set the authorized user list. |
| authorized_users | optional | list of integers | Phantom user Ids from the /rest/ph_user API, for example [1,5,6,7]. The authorized user list is always updated to include only the list passed by this command. |
curl -k -u admin:changeme https://localhost/rest/container/51 \
-d '{
"authorized_users": [ <user_id_1> , <user_id_2> ]
}'
Example response
A successful POST returns a success indicator and the Id of the updated container.
{
"id": 2,
"success": true
}
/rest/container/<container_id> optional query parameters
Query a container ID for authorized users.
/rest/container/<container_id>?_annotation_authorized_users
The container API has a query parameter that returns the authorized user field associated with the container.
Syntax
https://<username>:<password>@<host>/rest/container/<container_id>?_annotation_authorized_users
Usage details
GET
Retrieve a list of non-admin users who have sufficient permissions to view a container.
Example request
Returns the authorized user field associated with container ID 51.
curl -k -u admin:pass https://localhost/rest/container/51?_annotation_authorized_users -G -X GET
Example response
If there are no users associated with a container authorized user list, then an empty list is returned. If the calling user is an admin or on the authorized user list, then this field is a list of user IDs.
{
...
"authorized_users": [
3,
4
],
}
/rest/container/<container_id>/permitted_users
Query for authorized user candidates.
Syntax
https://<username>:<password>@<host>/rest/container/<container_id>/permitted_user
Usage details
This is used to show a list of candidates who can be granted authorized user access to a container using the authorized_users parameter.
GET
Retrieve a list of non-admin users who have sufficient permissions to view a container.
Example request
Retrieve a list of non-admin users who have sufficient permissions to view a container.
curl -k -u admin:pass https://localhost/rest/container/<container_id>/permitted_users -G -X GET
Example response
The result is a JSON object.
{
"users": [{
"username": "hansel",
"first_name": "hansel",
"last_name": "breadcrumbs",
"display_name": "hansel breadcrumbs",
"type": "normal",
"id": 3
},
{
"username": "gretel",
"first_name": "gretel",
"last_name": "breadcrumbs",
"display_name": "gretel breadcrumbs",
"type": "normal",
"id": 4
}
]
}
/rest/container_note
Add a note to an existing container.
Syntax
https://<username>:<password>@<host>/rest/container_note
POST
Add a note to an existing container.
Request parameters
See Create a container for the full parameters.
Example request
Update container Id 12 and add a note with the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| container_id | required | integer | Id of the container to add the note to. |
| title | required | string | The title of the note. |
| content | required | string | The content of the note. |
| phase_id | optional | integer | If the container is a case, a phase_id can be provided to associate the note to a particular phase. |
curl -k -u admin:changeme https://localhost/rest/container_note \
-d '{
"container_id": 12,
"title": "note title",
"content": "Content of note.",
"phase_id": 3
}'
Example response
A successful POST returns a success indicator and the Id of the newly created note.
{
"id": 5,
"success": true
}
/rest/container_pin_settings
Create a pin template.
Syntax
https://<username>:<password>@<host>/rest/container_pin_settings
Usage details
Pins are also called Heads Up Display (HUD) cards. These cards are displayed in Investigation. HUD cards are used to help analysts or other users easily track important information at a glance.
A new end point has been added to set a pin/HUD card that will be automatically created when a container matching the set label is created. Setting the label to null makes the pin/HUD card apply to all containers.
POST
Create a template pin/HUD card.
Request parameters
Create a template with the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| pin_type | required | string | The pin type of the pin. Can either be "preset metric" or "custom field". The types "data" and "manual card" cannot be used for a template. |
| label | required | string | The label of the card. When an event with this label is created, a pin with this template will also be created for that event. |
| preset_metric | string | The preset metric for the card. Available options are:
This option cannot be set if "custom_field" is used. | |
| custom_field | string | The custom field for the card. The custom field has to exist prior to the REST API request. This option cannot be set if "preset_metric" is used. | |
| pin_style | optional | string | The color of the HUD card. If not specified, defaults to grey.
|
| order | optional | int | The position at which the new pin is created. Existing pins at this position or later have their positions shifted by 1. |
Example request
Create a HUD card with the pin type of "preset metric," the label of "global," and the preset metric of "remaining tasks."
curl -k -u admin:changeme https://localhost/rest/container_note \
-d '{
"pin_type": "preset metric",
"preset_metric": "remaining tasks",
"label": "global",
"pin_style": "grey",
"order": 1
}'
Example response
A successful POST returns a success indicator and the Id of the newly created pin.
{
"id": 17,
"success": true,
"message": "Created a new pin"
}
/rest/container_pin
Add a Pin to a container.
Syntax
https://<username>:<password>@<host>/rest/container_pin
POST
Pin data to the HUD tab in Investigation.
Request parameters
Pin data to the HUD tab in Investigation with the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| container_id | required | integer | Id of the container to pin to. |
| order | required | integer | The position at which the new pin is created. Existing pins at this position or later have their positions shifted by 1. |
| message | required | string | The pin message. |
| data | required | string | The pin data. |
| pin_type | optional | string | Defaults to "data". There are four valid "pin_type" values:
If you use "data", you have the option to add a "data" field to your request. If you use "manual card", "input type" becomes a required field. |
| pin_style | optional | string | Valid values are:
Defaults to grey if no value is set. |
| name | optional | string | Defaults to null. Names can be used to easily reference pins without needing to know its Id. A name is unique per container. If a pin is creating using a name which already exists on that container, the existing named pin is updated instead of a new one being created. There can be any number of unnamed pins on a container. |
| input_type | dependent | string | Valid options are "text" or "select". |
| input_choices | dependent | JSON list | If the "input type" is set to "select", provide a list of the choices.
Example: ["one", "two", "three"] |
| custom_field | dependent | string | If the "pin_type" is set to "custom_field" provide the name of the custom field. |
| preset_metric | dependent | string | If the "pin_type" is set to "preset_metric" set the metric to use. Options are:
|
Example request
Pin data to container Id 12 with a pin type of "manual card," a message, and the data.
curl -k -u admin:changeme https://localhost/rest/container_pin \
-d '{
"container_id": 12,
"message": "This is a malicious IP",
"data": "192.168.58.130",
"pin_type": "manual card",
"input_type": "select",
"input_choices": ["one", "two", "three"],
"pin_style": "grey",
"name": null
}'
Example response
A successful POST returns a message, "Created a new pin", the content of the newly created pin, the id of the pin, and a success indicator.
{
"message": "Created a new pin",
"data": {
"pin_type": "manual card",
"preset_metric": null,
"container": 12,
"name": null,
"author": 1,
"input_type": "select",
"custom_field": null,
"modified_time": "2019-05-31T18:37:49.191094Z",
"order": 5,
"create_time": "2019-05-31T18:37:49.182561Z",
"playbook": "",
"input_choices": [
"one",
"two",
"three"
],
"message": "This is a malicious IP",
"data": "192.168.58.130",
"id": 5,
"pin_style": "grey"
},
"id": 5,
"success": true
}
/rest/container_comment
Add a comment to a container.
Syntax
https://<username>:<password>@<host>/rest/container_comment
Usage details
The user adding the comment must have Edit permissions to the container.
POST
Add a comment to a container.
Request parameters
The request string contains the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| container_id | required | integer | Id of the container to comment on. |
| comment | required | string | The contents of the comment. |
Example request
Comment on container Id 12.
curl -k -u admin:changeme https://localhost/rest/container_comment \
-d '{
"container_id": 12,
"comment": "This is an interesting container"
}'
The comment is "from" whichever user is authenticating the REST POST. If POSTing as an automation user, the automation user's name shows up as the commenter.
Example response
A successful POST returns a success indicator and the ID of the newly created comment.
{
"id": 27,
"success": true
}
/rest/container_attachment
Attach a file to a container.
Syntax
https://<username>:<password>@<host>/rest/container_attachment
Usage details
The user adding the attachment must have Edit permissions to the container.
POST
Add an attachment to a container.
Request parameters
The request string contains the following parameters.
| Field | Required | Type | Description |
|---|---|---|---|
| container_id | required | integer | Id of the container to add the attachment to. |
| file_name | required | string | The name of the file being uploaded. |
| file_content | required | string | The contents of the file. This is JSON serialized. Binary files must be base 64 encoded. |
| metadata | optional | JSON Object | This is a space for users to attach information to the file. A key called "contains" should be passed in with this with the value being a JSON Array of contains types. At a minimum, "vault id" should be submitted as a contains. While this is optional, not passing this value limits the ability to take actions on this file from the UI. |
Example request
Add an attachment to container Id 12.
curl -k -u admin:changeme https://localhost/rest/container_attachment \
-d '{
"container_id": 12,
"file_content": "JSON serialized contents of a file",
"file_name": "my_test_upload.txt",
"metadata": {
"contains": [
"vault id"
]
}
}'
Example python script
import json
import requests
from base64 import b64encode
contents = open('/path/to/binary.dat', 'rb').read()
serialized_contents = b64encode(contents)
attachment_json = {
'container_id': 12,
'file_content': serialized_contents,
'file_name': 'binary.dat',
'metadata': {
'contains': [
'vault id'
]
}
}
AUTH_TOKEN = 'AUTH TOKEN GOES HERE'
requests.post('https://phantom.example.com/rest/container_attachment',
auth=('', AUTH_TOKEN), data=json.dumps(attachment_json))
The webserver used by Phantom (NGINX) is configured to reject POSTs larger than 32MB. If you wish to be able to upload files larger than this, the configuration must be modified. However, please be aware of the security and performance implications of changing the maximum request body size.
Example response
A successful POST returns a success indicator and the Id of the newly created attachment.
{
"container": 159,
"hash": "a97e90e672b90ff092c674d709803aeb036e16c9",
"message": "success",
"size": 54,
"succeeded": true,
"vault_id": "a97e90e672b90ff092c674d709803aeb036e16c9"
}
/rest/container_options
Get container options.
Syntax
https://<username>:<password>@<host>/rest/container_options
Usage details
You need the "Container View" permission to get this list.
GET
Get a list of options for containers.
Example request
Retrieve a list of non-admin users who have sufficient permissions to view a container.
curl -k -u admin:pass https://localhost/rest/container_options -G -X GET
Example response
The result is a JSON object.
{
"status": [{
"is_default": true,
"name": "new",
"status_type": "new",
"order": 0
},
{
"is_default": false,
"name": "ripe",
"status_type": "new",
"order": 1
},
{
"is_default": true,
"name": "open",
"status_type": "open",
"order": 0
},
{
"is_default": true,
"name": "closed",
"status_type": "resolved",
"order": 0
}
],
"severity": [{
"color": "red",
"is_default": false,
"name": "high",
"order": 0
},
{
"color": "yellow",
"is_default": true,
"name": "medium",
"order": 1
},
{
"color": "green",
"is_default": false,
"name": "low",
"order": 2
}
],
"tags": [
"tag4",
"tag5",
"tag1",
"tag2",
"tags",
"auto add tag test",
"tag3",
"test123qa2",
"test123qa"
],
"sensitivity": [
[
"red",
"TLP:Red"
],
[
"amber",
"TLP:Amber"
],
[
"green",
"TLP:Green"
],
[
"white",
"TLP:White"
]
],
"label": [
"events"
],
"severity_colors": [
[
"red",
"Red"
],
[
"orange",
"Orange"
],
[
"yellow",
"Yellow"
],
[
"green",
"Green"
],
[
"light_blue",
"Light Blue"
],
[
"blue",
"Blue"
],
[
"purple",
"Purple"
],
[
"pink",
"Pink"
],
[
"light_grey",
"Light Grey"
],
[
"dark_grey",
"Dark Grey"
]
]
}
/rest/container/:id/approvals
Get a list of pending container approvals.
Syntax
https://<username>:<password>@<host>/rest/container/:id/approvals
GET
Get a list of pending container approvals
Example request
curl -k -u admin:pass https://localhost/rest/container_approvals -G -X GET
Example response
{
"count": 1,
"data": [
{
"id": 1,
"_pretty_action_run": "user initiated post ip action",
"action_run": 1,
"_pretty_asset": "abuseipdb",
"asset": 16,
"close_time": null,
"display": true,
"_pretty_due_time": "In 57 minutes",
"due_time": "2020-08-14T02:06:22.543000Z",
"_pretty_escalated_approval": "",
"escalated_approval": null,
"message": "pending-approval",
"name": "approval for 'post ip' on asset 'abuseipdb'",
"_pretty_owner": "admin",
"owner": 5,
"owner_type": "Primary Asset Owner",
"_pretty_parent": "",
"parent": null,
"playbook_run": null,
"_pretty_start_time": "0 minutes ago",
"start_time": "2020-08-14T01:09:01.556000Z",
"status": "pending",
"type": "asset",
"version": 1,
"jitc": {},
"node_guid": "6e17377a-313e-4a96-8c2f-2a3e16f6ec45",
"responses": [],
"_pretty_container": 4,
"_pretty_action_name": "post ip"
}
],
"pages": 1
}
| REST Cluster Nodes | REST custom function |
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
Feedback submitted, thanks!