Splunk® SOAR (On-premises)

REST API Reference for Splunk SOAR (On-premises)

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® SOAR (On-premises). For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

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 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 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 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_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-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_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 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:
  • "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 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.
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-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/<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 admin:pass 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": "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.

Last modified on 09 August, 2023
PREVIOUS
REST Cluster Nodes
  NEXT
REST Custom Function

This documentation applies to the following versions of Splunk® SOAR (On-premises): 5.1.0, 5.2.1, 5.3.1, 5.3.2, 5.3.3, 5.3.4, 5.3.5, 5.3.6, 5.4.0, 5.5.0


Was this documentation topic helpful?


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.

0 out of 1000 Characters