Understanding artifacts

Artifacts are JSON objects that are stored in a container. Artifacts are objects that are associated with a container and serve as corroboration or evidence related to the container. Much like the container schema, the artifact schema has a common header that can be operated on, and also contains a Common Event Format (CEF) body and raw data body to store elements that can be accessed by playbooks as shown in the following code. The fields in the code are defined in the table immediately following the code:

{
  "id": 1,
  "version": 1,
  "name": "test",
  "label": "event",
  "source_data_identifier": "140a7ae0-9da5-4ee2-b06c-64faa313e94a",
  "create_time": "2016-01-18T19:26:39.053087Z",
  "start_time": "2016-01-18T19:26:39.058797Z",
  "end_time": null,
  "severity": "low",
  "type": null,
  "kill_chain": null,
  "hash": "7a61100894c1eb24a59c67ce245d2d8c",
  "cef": {
    "sourceAddress": "1.1.1.1"
  },
  "container": 1,
  "description": null,
  "tags": [""],
  "data": {}
}

Field	Description
id	A unique identifier for the artifact, generated by the platform.
version	The version of this schema.
name	A name of the artifact as identified by the ingestion app from the data source.
label	The label as identified by the app that is ingesting the data. Labels can be anything that is found to be the label of the data or event in the ingestion data source. For example, labels can be event, FWAlert, AVAlert, to name a few.
source_data_identifier	The identifier of the artifact as found in the ingestion data source.
create_time	The timestamp of when this artifact was created in .
start_time	The timestamp of when this artifact was first seen. This timestamp typically coincides with when the artifact was initially detected or produced by the device that generated it.
end_time	The timestamp of this artifact as last seen in the ingestion data source.
severity	The severity of this artifact. For example, medium, high, or a custom severity created by an administrator.
type	The type of artifact. The type is used to identify the origin of this artifact, such as "network" or "host".
kill_chain	The kill-chain value as specified by the ingestion app and data source.
hash	The hash of the contents of the artifact. The hash is used by the platform to avoid saving duplicate artifacts for the same container.
cef	A normalized representation of the data mapped to each field's representative CEF key.
container	The ID of the container that contains this artifact.
tags	The list of tags assigned to this artifact.
data	The raw representation of the data.

Artifact deduplication

As a case proceeds, users and automation can add artifacts of interest. Splunk SOAR attempts to prevent duplicate artifacts from appearing in the system. However, inconsistencies occur when using a mix of input sources. For example, one user can't add an artifact twice, but different users can add the same artifact. When adding an artifact to a case with the Splunk SOAR app's "create container" action, adding the same artifact with the playbook api phantom.add_artifact will add a duplicate, but running phantom.add_artifact again for the artifact will be rejected.

A hash of the entire artifact body is taken to determine if it is a duplicate. Deduplication is determined by the hash, and the hash is based on the body of the POST request. A component of the artifact is the source ID, which is different depending on the how the artifact was created. The source_data_identifier is important in managing artifact duplication. If the the POSTed artifact doesn't have an SDI, the artifact is never deduplicated. Only if you add the same artifact twice, and they both have the same SDI, will deduplication happen. Deduplication doesn't trigger ingestion, even if "run_automation" is set to true on the artifact.

The hash is never changed after the fact, but it is sometimes altered intentionally to prevent collisions in certain scenarios such as cloning an artifact.

For information on container duplication see Container labels and deduplication in Understanding containers.

See also

• add_artifact in the Python Playbook API Reference for Splunk SOAR.
• Add artifacts from a container to a case in Use Splunk SOAR.