Splunk® Phantom

REST API Reference for Splunk Phantom

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Phantom. Click here for the latest version.
Acrobat logo Download topic as PDF

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 Splunk Phantom.

/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 Phantom 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 will be one of:
  • 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 Phantom 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. E.g. 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
Add a new artifact as follows:

curl -k -u admin:changeme 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 will return a success indicator and the ID of the newly created artifact.

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

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

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

Additional example

Example request
Create an artifact.

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

GET

You can use a GET to request information about artifacts. GET uses the parameters defined in Query for Data.

Example request

curl -X GET -k https://admin:changeme@localhost/rest/artifact?page=2 

Example response

{
    "count": 40,
    "data": [
        {
            "asset": 11,
            "container_id": 5,
            "create_time": "2014-10-19T12:41:33",
            ...
            "start_time": "2014-10-19T14:41:33",
            "type": "network",
            "version": "1.0"
        },
        {
            "asset": 12,
            "container_id": 5,
            "create_time": "2014-10-19T12:40:33",
            ...
            "start_time": "2014-10-19T14:40:33",
            "type": "network",
            "version": "1.0"
        },
        ...
        {
            "asset": 20,
            "container_id": 7,
            "create_time": "2014-09-04T12:40:33",
            "end_time": null,
            ...
            "start_time": "2014-09-04T14:40:33",
            "type": "",
            "version": "1.0"
        }
    ],
    "num_pages": 4
}
Last modified on 30 April, 2021
PREVIOUS
REST Approval
  NEXT
REST Asset

This documentation applies to the following versions of Splunk® Phantom: 4.8, 4.9, 4.10, 4.10.1, 4.10.2, 4.10.3, 4.10.4, 4.10.6, 4.10.7


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