splunk-security_content/docs/investigations.spec.json

{
  "$id": "https://api.splunkresearch.com/schemas/investigations.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "phantom": {
      "properties": {
        "phantom_server": {
          "description": "IP address and username of the Phantom server. Currently, we ship these values as automation (hostname) and encourage users to modify them according to their environments: for example, automation (hostname)",
          "type": "string"
        },
        "playbook_name": {
          "description": "Name of the playbook. This name should be the same as the name on the Phantom community repository on github, with underscores, and appended with \"community/<playbook_name>.\" The playbooks are hosted on https://github.com/phantomcyber/playbooks. For example: community/simple_network_enrichment.",
          "type": "string"
        },
        "playbook_url": {
          "description": "URL of the playbook on the Phantom website",
          "type": "string"
        },
        "schedule": {
          "description": "Various fields used to assist in scheduling the search",
          "properties": {
            "cron_schedule": {
              "description": "Schedule of the search in cron format",
              "type": "string"
            },
            "earliest_time": {
              "description": "The earliest time the search should run in Splunk format",
              "type": "string"
            },
            "latest_time": {
              "description": "The latest time the search should run again in Splunk format",
              "type": "string"
            }
          },
          "type": "object"
        },
        "sensitivity": {
          "description": "TLP colors (White, Green, Amber, or Red)",
          "type": "string"
        },
        "severity": {
          "description": "Severity in Phantom (High, Medium, Low)",
          "type": "string"
        }
      },
      "required": [
        "playbook_name",
        "phantom_server",
        "playbook_url"
      ],
      "type": "object"
    },
    "splunk": {
      "properties": {
        "fields_required": {
          "description": "A list of data models, if any, used by this search",
          "minItems": 0,
          "type": "array",
          "uniqueItems": true
        },
        "schedule": {
          "description": "Various fields to assist in scheduling the search",
          "properties": {
            "cron_schedule": {
              "description": "Schedule of the search in cron format",
              "type": "string"
            },
            "earliest_time": {
              "description": "The earliest time the search should run in Splunk format",
              "type": "string"
            },
            "latest_time": {
              "description": "The latest time the search should run again in Splunk format",
              "type": "string"
            }
          },
          "type": "object"
        },
        "search": {
          "description": "The search (in SPL) executed within Splunk Enterprise for investigation",
          "type": "string"
        }
      },
      "required": [
        "search",
        "fields_required",
        "schedule"
      ],
      "type": "object"
    }
  },
  "description": "The fields that make up the manifest of a version 2 investigative object",
  "properties": {
    "creation_date": {
      "description": "The date the story manifest was created",
      "type": "string"
    },
    "data_metadata": {
      "description": "Information about the data being ingested",
      "properties": {
        "data_eventtypes": {
          "description": "A list of eventtypes, if any, used by this search",
          "items": {
            "type": "string"
          },
          "minItems": 0,
          "type": "array",
          "uniqueItems": true
        },
        "data_models": {
          "description": "A list of data models, if any, used by this search",
          "items": {
            "enum": [
              "Alerts",
              "Application_State",
              "Authentication",
              "Certificates",
              "Change_Analysis",
              "Change",
              "Cloud_Infrastructure",
              "Malware",
              "Email",
              "Identity_Management",
              "Network_Resolution",
              "Network_Traffic",
              "Vulnerabilities",
              "Web",
              "Network_Sessions",
              "Updates",
              "Risk",
              "Endpoint"
            ]
          },
          "minItems": 0,
          "type": "array",
          "uniqueItems": true
        },
        "data_source": {
          "description": "A high-level description of the type of data needed for this search to complete",
          "items": {
            "type": "string"
          },
          "minItems": 0,
          "type": "array",
          "uniqueItems": true
        },
        "data_sourcetypes": {
          "description": "The list of sourcetypes, if any, used by this search",
          "items": {
            "type": "string"
          },
          "minItems": 0,
          "type": "array",
          "uniqueItems": true
        },
        "providing_technologies": {
          "description": "A list of technologies that provide this data",
          "items": {
            "enum": [
              "Apache",
              "AWS",
              "Bro",
              "Microsoft Windows",
              "Linux",
              "macOS",
              "Netbackup",
              "Splunk Enterprise",
              "Splunk Enterprise Security",
              "Splunk Stream",
              "Active Directory",
              "Bluecoat",
              "Carbon Black Response",
              "Carbon Black Protect",
              "CrowdStrike Falcon",
              "Microsoft Exchange",
              "Nessus",
              "Palo Alto Firewall",
              "Qualys",
              "Sysmon",
              "Tanium",
              "Ziften",
              "Censys",
              "OSquery",
              "SMTP",
              "Cuckoo",
              "VirusTotal",
              "DeepSight"
            ]
          },
          "minItems": 0,
          "type": "array",
          "uniqueItems": true
        }
      },
      "required": [
        "data_source",
        "providing_technologies"
      ],
      "type": "object"
    },
    "description": {
      "description": "A description of what the search is designed to detect",
      "type": "string"
    },
    "eli5": {
      "description": "Explain it like I\u2019m 5 - A detail description of the SPL of the search, written in a style that can be understood by a future Splunk expert",
      "type": "string"
    },
    "entities": {
      "description": "A list of entities that will used in the story flow or are relevant to the security investigation. ",
      "items": {
        "enum": [
          "accessKeyId",
          "arn",
          "awsRegion",
          "bucketName",
          "City",
          "Country",
          "dest_port",
          "dest",
          "event_id",
          "instanceId",
          "message_id",
          "networkAclId",
          "process_name",
          "process",
          "recipient",
          "Region",
          "resourceId",
          "session_id",
          "src_ip",
          "src_mac",
          "src_user",
          "src",
          "user"
        ]
      },
      "minItems": 0,
      "type": "array",
      "uniqueItems": true
    },
    "how_to_implement": {
      "description": "A discussion of how to implement this search, from what needs to be ingested, config files modified, and suggested per-site modifications",
      "type": "string"
    },
    "id": {
      "description": "The unique identifier for the search",
      "type": "string"
    },
    "investigate": {
      "anyOf": [
        {
          "required": [
            "splunk"
          ]
        },
        {
          "required": [
            "phantom"
          ]
        }
      ],
      "properties": {
        "phantom": {
          "$ref": "#/definitions/phantom"
        },
        "splunk": {
          "$ref": "#/definitions/splunk"
        }
      },
      "type": "object"
    },
    "known_false_positives": {
      "description": "Scenarios in which detected behavior is benign, coupled with suggestions on how to verify the behavior",
      "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 search",
            "type": "string"
          },
          "email": {
            "description": "Email address of the person maintaining this search",
            "type": "string"
          },
          "name": {
            "description": "Name of the person maintaining this search",
            "type": "string"
          }
        },
        "required": [
          "name",
          "email",
          "company"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "modification_date": {
      "description": "The date of the most recent modification to the search",
      "type": "string"
    },
    "name": {
      "description": "The name of the search",
      "type": "string"
    },
    "original_authors": {
      "description": "A list of the original authors of the search",
      "items": {
        "additionalProperties": false,
        "properties": {
          "company": {
            "description": "Company associated with the person who originally authored the search",
            "type": "string"
          },
          "email": {
            "description": "Email address of the person who originally authored the search",
            "type": "string"
          },
          "name": {
            "description": "Name of the person who originally authored the search",
            "type": "string"
          }
        },
        "required": [
          "name",
          "email",
          "company"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "spec_version": {
      "description": "The version of the investigative search specification this manifest follows",
      "type": "integer"
    },
    "type": {
      "description": "Type of product that will support this investigate object",
      "enum": [
        "phantom",
        "splunk",
        "uba"
      ]
    },
    "version": {
      "description": "The version of the search",
      "type": "string"
    }
  },
  "required": [
    "creation_date",
    "data_metadata",
    "how_to_implement",
    "maintainers",
    "modification_date",
    "original_authors",
    "description",
    "id",
    "type",
    "spec_version",
    "version",
    "investigate"
  ],
  "title": "Investigative Search Manifest",
  "type": "object"
}