Splunk® Phantom (Legacy)

Python Playbook API Reference for Splunk Phantom

Splunk Phantom 4.10.7 is the final release of Splunk's Security Orchestration, Automation, and Response (SOAR) system to be called Splunk Phantom. All later versions are named Splunk SOAR (On-premises). For more information, see the Splunk SOAR (On-premises) documentation.

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

See also

Last modified on 23 September, 2021
Understanding containers   Understanding datapaths

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


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