Splunk® SOAR (Cloud)

REST API Reference for Splunk SOAR (Cloud)

The classic playbook editor will be deprecated in early 2025. Convert your classic playbooks to modern mode.
After the future removal of the classic playbook editor, your existing classic playbooks will continue to run, However, you will no longer be able to visualize or modify existing classic playbooks.
For details, see:

REST Artifact

Artifacts are objects that are associated with a Container and serve as corroboration or evidence related to the Container. See Add artifacts from a container to a case in Use .

/rest/artifact

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 REST container documentation) in which case you should not set run_automation at all, as will automatically set run_automation after the last artifact is created.

Syntax

https://<username>:<password>@<host>/rest/artifact

POST

Create a new artifact.

Request string
An argument string must include the following fields: container_id.

Field Required Type Description
cef optional Javascript object. Contains standard fields available in the Common Event Format.
cef_types optional Javascript object. Allows association of "contains" information to custom CEF fields. Object keys should be keys in the "cef" object. Values should be a list of strings where the strings are standard "contains" data types such as "ip" or "pid" etc.
container_id required integer The artifact will "belong" to this container.
data optional JSON Object Custom data field.
description optional string A textual description of the artifact.
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 or String ID of the app which produced the artifact. Name of the app can also be provided.
kill_chain optional string Cyber kill chain. One of
  • Reconnaissance
  • Weaponization
  • Delivery
  • Exploitation
  • Installation
  • Command & Control
  • Actions on Objectives
label optional string The label classifies the artifact. Typically the label is either:
  • event
  • net flow
name optional string A human friendly name for the artifact.
owner_id optional integer or string ID of the user who should own the artifact. Username can also be used.
run_automation optional boolean Not an artifact data field: This parameter instructs to run automation upon creation or update of the artifact, and defaults to True.
severity optional string The severity level of the artifact you are adding. Helps to determine the SLA applied to Actions related to the container. Either one of Low, Medium, or High or else a custom severity name set by an administrator. If the severity level of the artifact is higher than the current severity level of the container, then the container's severity will be changed to match the artifact. For example, if you add a high severity artifact to a medium severity container, the container will be changed to severity high. You can set a container's severity to Low, Medium, or High with this endpoint even if those severity names have been deleted by the 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)
start_time optional ISO 8601 formatted timestamp Date and time (in UTC) when the behavior tracked by the container started.
tags optional Array of strings 0 or more tags associated with the asset. A simple string can also be used for a single tag.
type optional string Helps to identify the content of this artifact. Typically a string such as "network" or "host" etc.

Response

A success or failure message.


Example request 1
Add a new artifact

curl -k -u username:password https://localhost/rest/artifact \
-d '{
	"asset_id": 10,
	"cef": {
		"ApplicationProtocol": "",
		"act": "",
		"app": "",
		"baseEventCount": "120",
		"bytesIn": "",
		"bytesOut": "",
		"cat": "",
		"cn1": "",
		"cn1Label": "",
		"cn2": "",
		"cn2Label": "",
		"cn3": "",
		"cn3Label": "",
		"cnt": "",
		"cs1": "",
		"cs1Label": "",
		"cs2": "",
		"cs2Label": "",
		"cs3": "",
		"cs3Label": "",
		"cs4": "",
		"cs4Label": "",
		"cs5": "",
		"cs5Label": "",
		"cs6": "",
		"cs6Label": "",
		"destinationAddress": "",
		"destinationDnsDomain": "",
		"destinationHostName": "",
		"destinationMacAddress": "",
		"destinationNtDomain": "",
		"destinationPort": "80",
		"destinationProcessName": "",
		"destinationServiceName": "",
		"destinationTranslatedAddress": "",
		"destinationTranslatedPort": "",
		"destinationUserId": "",
		"destinationUserName": "",
		"destinationUserPrivileges": "",
		"deviceAction": "",
		"deviceAddress": "",
		"deviceCustomDate1": "",
		"deviceCustomDate1Label": "",
		"deviceCustomDate2": "",
		"deviceCustomDate2Label": "",
		"deviceCustomNumber1": "",
		"deviceCustomNumber1Label": "",
		"deviceCustomNumber2": "",
		"deviceCustomNumber2Label": "",
		"deviceCustomNumber3": "",
		"deviceCustomNumber3Label": "",
		"deviceCustomString1": "",
		"deviceCustomString1Label": "",
		"deviceCustomString2": "",
		"deviceCustomString2Label": "",
		"deviceCustomString3": "",
		"deviceCustomString3Label": "",
		"deviceCustomString4": "",
		"deviceCustomString4Label": "",
		"deviceCustomString5": "",
		"deviceCustomString5Label": "",
		"deviceCustomString6": "",
		"deviceCustomString6Label": "",
		"deviceDirection": "",
		"deviceDnsDomain": "",
		"deviceEventCategory": "",
		"deviceExternalId": "",
		"deviceFacility": "",
		"deviceHostname": "",
		"deviceInboundInterface": "",
		"deviceMacAddress": "",
		"deviceOutboundInterface": "",
		"deviceProcessName": "",
		"deviceTranslatedAddress": "",
		"dhost": "",
		"dmac": "",
		"dntdom": "",
		"dpriv": "",
		"dproc": "",
		"dpt": "",
		"dst": "103.230.84.239",
		"duid": "",
		"duser": "",
		"dvc": "",
		"dvchost": "",
		"end": "",
		"endTime": "",
		"externalId": "",
		"fileCreateTime": "2014-10-19 12:41:32",
		"fileHash": "51020390505ecc8cf7045675639937421996529f6d49decc53753e1335aeb574",
		"fileId": "",
		"fileModificationTime": "",
		"fileName": "",
		"filePath": "",
		"filePermission": "",
		"fileSize": "",
		"fileType": "",
		"fname": "",
		"fsize": "",
		"in": "",
		"message": "",
		"method": "",
		"msg": "",
		"oldfileCreateTime": "",
		"oldfileHash": "",
		"oldfileId": "",
		"oldfileModificationTime": "",
		"oldfileName": "",
		"oldfilePath": "",
		"oldfilePermission": "",
		"oldfileType": "",
		"oldfsize": "",
		"out": "",
		"proto": "",
		"receiptTime": "",
		"request": "",
		"requestClientApplication": "",
		"requestCookies": "",
		"requestMethod": "",
		"requestURL": "",
		"rt": "",
		"shost": "",
		"smac": "",
		"sntdom": "",
		"sourceAddress": "10.10.0.201",
		"sourceDnsDomain": "",
		"sourceHostName": "",
		"sourceMacAddress": "",
		"sourceNtDomain": "",
		"sourcePort": "4286",
		"sourceServiceName": "",
		"sourceTranslatedAddress": "",
		"sourceTranslatedPort": "",
		"sourceUserId": "",
		"sourceUserName": "",
		"sourceUserPrivileges": "",
		"spriv": "",
		"spt": "",
		"src": "",
		"start": "",
		"startTime": "09/09/2014 16:30:00",
		"suid": "",
		"suser": "",
		"transportProtocol": "",
		"my_custom_cef_field": "1.1.1.1"
	},
	"cef_types": {
		"my_custom_cef_field": ["ip"]
	},
	"container_id": 41,
	"data": {},
	"end_time": "2014-10-19T14:45:51.100Z",
	"label": "event",
	"run_automation": true,
	"severity": "high",
	"source_data_identifier": "4",
	"start_time": "2014-10-19T14:41:33.384Z",
	"tags": ["tag1", "tag2"],
	"type": "network"
}'

Example response
A successful POST returns a success indicator and the ID of the newly created artifact.

{
    "success": true,
    "id": 41
}

Posting a JSON that is identical to an existing artifact results in a duplication error. The response also returns the ID of the matching artifact.

{
    "existing_artifact_id": 41,
    "failed": true,
    "message": "artifact already exists"
}

Example request 2
Create an artifact.

{
    "container_id": 2,
    "severity": "low",
    "label": "events",
    "cef": {
        "sourceAddress": "127.0.0.1"
    },
    "cef_types": {
        "sourceAddress": [
            "ip"
        ]
    },
    "name": "Ping event"
}

A successful POST returns a success indicator and the ID of the newly created artifact.

{
    "success": true,
    "id": 2
}

Example request 3
Create a vault artifact and associate it with a vault item.

{
"cef": {"vaultId":"c3dad64662c173894735bbb9f91dbf4ce32a8bdf"},
"cef_types"{},
"container_id":1,
"label":"event",
"name":"my_a1",
"owner_id":1,
"severity":"medium",
"tags":[]
}

Example response 3
A successful POST returns a success indicator and the ID of the newly created artifact.

{
    "success": true,
    "id": 3
}
Last modified on 18 September, 2024
REST Approval   REST Asset

This documentation applies to the following versions of Splunk® SOAR (Cloud): current


Was this topic useful?







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