Skip to content

story.spec.md

Latest commit

 

History

History
725 lines (335 loc) · 9.58 KB

story.spec.md

File metadata and controls

725 lines (335 loc) · 9.58 KB

Analytic Story Manifest Schema

https://api.splunkresearch.com/schemas/story.json

The fields that make up the manifest of a version 2 Analytic Story

Abstract Extensible Status Identifiable Custom Properties Additional Properties Defined In
Can be instantiated No Experimental No Forbidden Permitted

Analytic Story Manifest Properties

Property Type Required Nullable Defined by
category enum[] Required No Analytic Story Manifest (this schema)
channel string Optional No Analytic Story Manifest (this schema)
creation_date string Optional No Analytic Story Manifest (this schema)
description string Required No Analytic Story Manifest (this schema)
detections object[] Required No Analytic Story Manifest (this schema)
id string Required No Analytic Story Manifest (this schema)
maintainers object[] Optional No Analytic Story Manifest (this schema)
modification_date string Optional No Analytic Story Manifest (this schema)
name string Required No Analytic Story Manifest (this schema)
narrative string Optional No Analytic Story Manifest (this schema)
original_authors object[] Optional No Analytic Story Manifest (this schema)
references string[] Optional No Analytic Story Manifest (this schema)
spec_version integer Optional No Analytic Story Manifest (this schema)
usecase enum Required No Analytic Story Manifest (this schema)
version string Required No Analytic Story Manifest (this schema)
* any Additional Yes this schema allows additional properties

category

The category to which the Analytic Story belongs

category

  • is required
  • type: enum[]
  • at least 0 items in the array
  • defined in this schema

category Type

Array type: enum[]

All items must be of the type: string

channel

A grouping function that designates where this search came from. For example, searches and stories in Enterprise Security Content Updates are in the ESCU channel

channel

  • is optional
  • type: string
  • defined in this schema

channel Type

string

channel Example

"ESCU"

creation_date

The date this story was created

creation_date

  • is optional
  • type: string
  • defined in this schema

creation_date Type

string

creation_date Example

"2017-11-21"

description

A high-level description or goal of the Analytic Story

description

  • is required
  • type: string
  • defined in this schema

description Type

string

description Example

"Secure your environment against DNS hijacks with searches that help you detect and investigate unauthorized changes to DNS records."

detections

An array of detection mechanisms from Splunk, UBA and phantom.

detections

  • is required
  • type: object[]
  • defined in this schema

detections Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
detection_id string Required
name string Required
type string Required

detection_id

unique identifier of the detection, in the form of UUID

detection_id

  • is required
  • type: string
detection_id Type

string

detection_id Example
1169w17b-ef78-4b59-aae8-5369073014e1

name

Name of the Detection. It can be a name of a Splunk correlation search name, a UBA threat or a Phantom detection playbook.

name

  • is required
  • type: string
name Type

string

name Example
DNS record changed

type

What product gives you a detection

type

  • is required
  • type: enum

The value of this property must be equal to one of the known values below.

type Known Values
Value Description
splunk
uba
phantom
type Examples
splunk
uba
phantom

id

A unique identifier for the Analytic Story

id

  • is required
  • type: string
  • defined in this schema

id Type

string

id Example

"8169f17b-ef68-4b59-aae8-5869073014e1"

maintainers

An array of the current maintainers of the Analytic Story.

maintainers

  • is optional
  • type: object[]
  • defined in this schema

maintainers Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
company string Required
email string Required
name string Required

company

Company associated with the person maintaining this Analytic Story

company

  • is required
  • type: string
company Type

string

company Example
Splunk

email

Email address of the person maintaining this Analytic Story

email

  • is required
  • type: string
email Type

string

email Example
daftpunk@splunk.com

name

Name of the person maintaining this Analytic Story

name

  • is required
  • type: string
name Type

string

name Example
Daft Punk

modification_date

The date of the most recent modification to this Analytic Story

modification_date

  • is optional
  • type: string
  • defined in this schema

modification_date Type

string

modification_date Example

"2018-09-06"

name

The name of the Analytic Story

name

  • is required
  • type: string
  • defined in this schema

name Type

string

name Example

"DNS Hijacking"

narrative

Long-form text that describes the Analytic Story and the rationale behind it, as well as an overview of the included searches, and how they enable the story

narrative

  • is optional
  • type: string
  • defined in this schema

narrative Type

string

narrative Example

"Dubbed the Achilles heel of the Internet (see https://www.f5.com/labs/articles/threat-intelligence/dns-is-still-the-achilles-heel-of-the-internet-25613), DNS plays a critical role in routing web traffic but is notoriously vulnerable to attack. One reason is its distributed nature. It relies on unstructured connections between millions of clients and servers over inherently insecure protocols.<br></br>The gravity and extent of the importance of securing DNS from attacks is undeniable. The fallout of compromised DNS can be disastrous."

original_authors

An array of the original authors of the Analytic Story

original_authors

  • is optional
  • type: object[]
  • defined in this schema

original_authors Type

Array type: object[]

All items must be of the type: object with following properties:

Property Type Required
company string Required
email string Required
name string Required

company

Company associated with the person who originally authored the Analytic Story

company

  • is required
  • type: string
company Type

string

company Example
Splunk

email

Email address of the person who originally authored the Analytic Story

email

  • is required
  • type: string
email Type

string

email Example
daftpunk@splunk.com

name

Name of the person who originally authored the Analytic Story

name

  • is required
  • type: string
name Type

string

name Example
Daft Punk

references

An array of URLs that give information about the problem the story is addressing

references

  • is optional
  • type: string[]
  • at least 0 items in the array
  • defined in this schema

references Type

Array type: string[]

All items must be of the type: string

references Example

"https://www.fireeye.com/blog/threat-research/2017/09/apt33-insights-into-iranian-cyber-espionage.html"

spec_version

The version of the Analytic Story specification this manifest follows

spec_version

  • is optional
  • type: integer
  • defined in this schema

spec_version Type

integer

spec_version Example

2

usecase

The usecase to which the Analytic Story belongs to.

usecase

  • is required
  • type: enum
  • defined in this schema

The value of this property must be equal to one of the known values below.

usecase Known Values

Value Description
Security Monitoring
Advanced Threat Detection
Insider Threat
Compliance
Fraud Detection

usecase Example

"Advanced Threat Detection"

version

The version of the Analytic Story, bump the version number when the story gets an update

version

  • is required
  • type: string
  • defined in this schema

version Type

string

version Example

"1.0"