splunk-security_content/docs/story.spec.json

{
  "$id": "https://api.splunkresearch.com/schemas/story.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "The fields that make up the manifest of a version 2 Analytic Story",
  "meta:license": [
    "This file is licensed to you under the Apache License, Version 2.0 (the 'License');",
    "you may not use this file except in compliance with the License. You may obtain a copy",
    "of the License at http://www.apache.org/licenses/LICENSE-2.0"
  ],
  "properties": {
    "category": {
      "description": "The category to which the Analytic Story belongs",
      "items": {
        "enum": [
          "Abuse",
          "Account Compromise",
          "Account Sharing",
          "Adversary Tactics",
          "Best Practices",
          "Cloud Security",
          "Command and Control",
          "Compliance",
          "Data Exfiltration",
          "Denial of Service",
          "Endpoint Compromise",
          "GDPR",
          "IAM Analytics",
          "Insider Threat",
          "Lateral Movement",
          "Malware",
          "Network Attack",
          "Operations",
          "Other",
          "Privilege Escalation",
          "Phishing",
          "Ransomware",
          "SaaS",
          "Scanning",
          "Shadow IT",
          "Threat Intelligence",
          "Unauthorized Software",
          "Vulnerability",
          "Web Attack"
        ],
        "examples": [
          "Adversary Tactics"
        ],
        "type": "string"
      },
      "maxItems": 1,
      "minItems": 0,
      "type": "array",
      "uniqueItems": true
    },
    "channel": {
      "description": "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",
      "examples": [
        "ESCU"
      ],
      "type": "string"
    },
    "creation_date": {
      "description": "The date this story was created",
      "examples": [
        "2017-11-21"
      ],
      "type": "string"
    },
    "description": {
      "description": "A high-level description or goal of the Analytic Story",
      "examples": [
        "Secure your environment against DNS hijacks with searches that help you detect and investigate unauthorized changes to DNS records."
      ],
      "type": "string"
    },
    "detections": {
      "description": "An array of detection mechanisms from Splunk, UBA, and Phantom. ",
      "items": {
        "additionalProperties": false,
        "properties": {
          "detection_id": {
            "description": "Unique identifier of the detection, in the form of UUID",
            "examples": [
              "1169w17b-ef78-4b59-aae8-5369073014e1"
            ],
            "type": "string"
          },
          "name": {
            "description": "Name of the Detection. This can be a name of a Splunk correlation search, a UBA threat, or a Phantom detection playbook.",
            "examples": [
              "DNS record changed"
            ],
            "type": "string"
          },
          "type": {
            "description": "Product providing the detection",
            "enum": [
              "splunk",
              "uba",
              "phantom"
            ],
            "examples": [
              "splunk",
              "uba",
              "phantom"
            ],
            "type": "string"
          }
        },
        "required": [
          "detection_id",
          "type",
          "name"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "id": {
      "description": "A unique identifier for the Analytic Story",
      "examples": [
        "8169f17b-ef68-4b59-aae8-5869073014e1"
      ],
      "format": "uuid",
      "type": "string"
    },
    "maintainers": {
      "description": "An array of the current maintainers of the Analytic Story",
      "items": {
        "additionalProperties": false,
        "properties": {
          "company": {
            "description": "Company associated with the person maintaining this Analytic Story",
            "examples": [
              "Splunk"
            ],
            "type": "string"
          },
          "email": {
            "description": "Email address of the person maintaining this Analytic Story",
            "examples": [
              "daftpunk@splunk.com"
            ],
            "type": "string"
          },
          "name": {
            "description": "Name of the person maintaining this Analytic Story",
            "examples": [
              "Daft Punk"
            ],
            "type": "string"
          }
        },
        "required": [
          "name",
          "email",
          "company"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "modification_date": {
      "description": "The date of the most recent modification to this Analytic Story",
      "examples": [
        "2018-09-06"
      ],
      "type": "string"
    },
    "name": {
      "description": "The name of the Analytic Story",
      "examples": [
        "DNS Hijacking"
      ],
      "type": "string"
    },
    "narrative": {
      "description": "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",
      "examples": [
        "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."
      ],
      "type": "string"
    },
    "original_authors": {
      "description": "An array of the original authors of the Analytic Story",
      "items": {
        "additionalProperties": false,
        "properties": {
          "company": {
            "description": "Company associated with the person who originally authored the Analytic Story",
            "examples": [
              "Splunk"
            ],
            "type": "string"
          },
          "email": {
            "description": "Email address of the person who originally authored the Analytic Story",
            "examples": [
              "daftpunk@splunk.com"
            ],
            "type": "string"
          },
          "name": {
            "description": "Name of the person who originally authored the Analytic Story",
            "examples": [
              "Daft Punk"
            ],
            "type": "string"
          }
        },
        "required": [
          "name",
          "email",
          "company"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "references": {
      "description": "An array of URLs that provide information about the problem the story addresses",
      "examples": [
        "https://www.fireeye.com/blog/threat-research/2017/09/apt33-insights-into-iranian-cyber-espionage.html"
      ],
      "items": {
        "type": "string"
      },
      "minItems": 0,
      "type": "array",
      "uniqueItems": true
    },
    "spec_version": {
      "description": "The version of the Analytic Story specification this manifest follows",
      "examples": [
        2
      ],
      "type": "integer"
    },
    "usecase": {
      "description": "The use case to which the Analytic Story belongs",
      "enum": [
        "Security Monitoring",
        "Advanced Threat Detection",
        "Insider Threat",
        "Compliance",
        "Fraud Detection"
      ],
      "examples": [
        "Advanced Threat Detection"
      ]
    },
    "version": {
      "description": "The version of the Analytic Story (bumps the version number when the story gets an update)",
      "examples": [
        "1.0"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "category",
    "usecase",
    "name",
    "description",
    "detections",
    "version"
  ],
  "title": "Analytic Story Manifest",
  "type": "object"
}