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
}