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
|
| label | optional | string | The label classifies the artifact. Typically the label will be one of:
|
| 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
| REST Approval | REST Asset |
This documentation applies to the following versions of Splunk® Phantom (Legacy): 4.8, 4.9, 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!