REST Containers

Create, modify, and manage containers using the following rest endpoints.

/rest/container

Manage containers and their associated authorized users, 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 Reconnaissance Weaponization Delivery Exploitation Installation Command & Control Actions on Objectives
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: events incident intelligence vulnerability
name	required	string	A short friendly name for the container.
owner_id	optional	integer or string	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	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 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: white green amber red
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	The 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	The 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 Splunk SOAR automatically sets 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 soar_local_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 soar_local_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	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 soar_local_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 soar_local_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 soar_local_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 administrator 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 soar_local_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	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 soar_local_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-administrator users who have sufficient permissions to view a container.

Example request
Returns the authorized user field associated with container ID 51.

curl -k -u soar_local_admin:password 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 administrator 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_users

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-administrator users who have sufficient permissions to view a container.

Example request
Retrieve a list of non-administrator users who have sufficient permissions to view a container.

curl -k -u soar_local_admin:password 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_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: "remaining tasks" "failed actions" "failed playbooks" "tasks exceeding sla" "time to resolve" 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. grey blue red
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 soar_local_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

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.

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: "data" "manual card" "custom field" "preset metric" 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: "grey" "blue" "red" 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: "remaining tasks" "failed actions" "failed playbooks" "tasks exceeding sla" "time to resolve"

Example request
Pin data to container Id 12 with a pin type of "manual card," a message, and the data.

curl -k -u soar_local_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 soar_local_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.
task_id	optional	integer	Use the task ID to associate a file with a specific task in the workbook.

Example request
Add an attachment to container ID 12.

curl -k -u soar_local_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",
        "task_id": "80",
	"metadata": {
		"contains": [
			"vault id"
		]
	}
}'

Example python script

import json
import requests
from pathlib import Path
from base64 import b64encode

contents = Path('/path/to/binary.dat').read_bytes()

attachment_json = {
    'container_id': 12,
    'file_content': b64encode(contents).decode(),
    'file_name': 'binary.dat',
    'task_id': 80,
    '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, 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-administrator users who have sufficient permissions to view a container.

curl -k -u soar_local_admin:changeme 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/<container_id>/approvals

Get a list of container approvals.

Syntax

https://<username>:<password>@<host>/rest/container/<container_id>/approvals

GET

Get a list of container approvals.

Example request

curl -k -u soar_local_admin:changeme https://localhost/rest/container/<container_id>/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": "soar_local_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
}

For information on the container status API, see Status endpoints.