Splunk® Enterprise Security

REST API Reference

Acrobat logo Download manual as PDF


This documentation does not apply to the most recent version of Splunk® Enterprise Security. For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

Analytic Story API reference

Access the Analytic Story framework in Splunk Enterprise Security.

The Analytic Story framework is a mechanism for proxy access to the stories in the Splunk Enterprise Security Content Update (ESCU). The ESCU analytic story content is available directly in Splunk ES through the use case library.

Usage details

Authentication and authorization

Username and password authentication is required for access to endpoints and REST operations. You must have the edit_analyticstories capability to use the analyticstories endpoint.

Alternatively, you can use token authentication. See Set up authentication with tokens in the Splunk Enterprise Securing the Splunk Platform manual.

Username and password authentication is used in the examples that follow.

Splunk Cloud Platform URL for REST API access

Splunk Cloud Platform has a different host and management port syntax than Splunk Enterprise. Depending on your deployment type, use one of the following options to access REST API resources.

Splunk Cloud Platform deployments
Use the following URL for single-instance deployments.

https://<deployment-name>.splunkcloud.com:8089

Use the following URL for clustered deployments. If necessary, submit a support case to open port 8089 on your deployment.

https://<deployment-name>.splunkcloud.com:8089

To get the required credentials, submit a support case on the Support Portal. After installing the credentials, use the following URL.

https://input-<deployment-name>.splunkcloud.com:8089

See Using the REST API in Splunk Cloud Platform in the the Splunk REST API Tutorials for more information.

Common return format

For success and error responses, the general format follows.

Success
The general response for successes, such as 200/201, follows:

{
  "entry": [
    {JSON object 1},
    ...
  ],
  "paging": {
    "offset": <number>,
    "perPage": <number>,
    "total": <number>
  }
}

where each object in the entry array would be specified per endpoint.

Error
The general response for errors, such as 4xx/5xx, follows:

{
  "messages": [
    {
      "type": "ERROR",
      "text": "<error message>"
    },
    ...
  ]
}

/services/analyticstories/configs/{stanza_type}

Acts as a proxy to configs/conf-analyticstories, with validation.

Syntax

https://<host>:<mPort>/services/analyticstories/configs/{stanza_type}

Usage details
The {stanza_type} must be one of the following:

  • analytic_story
  • analytic_story_category
  • savedsearch

GET

Return all a list of stanzas of the give stanza_type, or all stanzas if stanza_type is "all".

Example request
Retrieve a list of all analytic stories.

curl -k -u admin:pass https://localhost:8089/services/analyticstories/configs/analytic_story -G -X GET

Example response

If the request is successful, the endpoint returns a JSON array of objects from the stanza_type. Each object is of format returned by "single entity" endpoint, {stanza_type}/{name}. If the request fails, the endpoint returns an error message.

{
	"paging": {
		"offset": 0,
		"perPage": 30,
		"total": 3
	},
	"entry": [{
		"acl": {
			"can_share_app": true,
			"modifiable": true,
			"owner": "nobody",
			"can_write": true,
			"removable": false,
			"sharing": "global",
			"can_change_perms": true,
			"can_share_user": false,
			"can_list": true,
			"perms": {
				"write": ["*"],
				"read": ["*"]
			},
			"app": "DA-ESS-AccessProtection",
			"can_share_global": true
		},
		"name": "Access Protection",
		"stanza_type": "analytic_story",
		"content": {
			"narrative": "Access protection&#151;selective restriction of who may access data or other resources via authentication and authorization&#151;is arguably one of the most important activities in network security. The first part of the equation, authentication, involves ensuring that the user is who they purport to be. Next, an authorization process determines the level of privilege the user or role possesses.\n\nAlthough implementing an end-to-end access-protection system is critical, no system is foolproof, making ongoing automated monitoring critical. This use case is designed to help you detect attackers who may be attempting to circumvent access-protection mechanisms in your environment. It includes the following searches: \n\n1. **Excessive Failed Logins:** Detects excessive numbers of failed login attempts (typical of a brute-force attack)\n\n1. **Inactive Account Usage:** Discovers previously inactive accounts that are now being used.\n\n1. **Insecure Or Cleartext Authentication Detected:** Detects authentication requests that transmit the password over the network as cleartext (unencrypted).\n\n1. **Short-lived Account Detected:** Looks for accounts that were created and or deleted within the previous four hours&#151;a possible red flag.",
			"spec_version": 1,
			"description": "Monitoring account activity and securing authentication are critical to enterprise security. This use case includes searches that detect suspicious account activity and alert you to the use of cleartext (non-encrypted) authentication protocols.",
			"last_updated": "2018-09-13",
			"version": 1.0,
			"maintainers": [{
				"email": "rvaldez@splunk.com",
				"name": "Rico Valdez",
				"company": "Splunk"
			}],
			"searches": ["Access - Excessive Failed Logins - Rule", "Access - Inactive Account Usage - Rule", "Access - Insecure Or Cleartext Authentication - Rule", "Access - Short-lived Account Detected - Rule"],
			"category": "Best Practices",
			"references": ["https://www.sans.org/media/critical-security-controls/critical-controls-poster-2016.pdf"]
		}
	}, {
		"acl": {
			"can_share_app": true,
			"modifiable": true,
			"owner": "nobody",
			"can_write": true,
			"removable": false,
			"sharing": "global",
			"can_change_perms": true,
			"can_share_user": false,
			"can_list": true,
			"perms": {
				"write": ["*"],
				"read": ["*"]
			},
			"app": "DA-ESS-EndpointProtection",
			"can_share_global": true
		},
		"name": "Endpoint Protection",
		"stanza_type": "analytic_story",
		"content": {
			"narrative": "Continuous advanced threat monitoring on the endpoint is one of the most critical components of your organization's security strategy. Its focus is on early detection and analysis of suspicious events that may indicate the presence of an internal or external threat in your environment. \n\nThe time to get serious about advanced threat detection on your endpoints is after you have implemented basic security measures related to your network perimeter, devices, and applications. The most critical areas of focus include detection of anomalous and prohibited processes and services, suspicious behavior involving user accounts, and malware outbreaks.\n\nThis use case includes searches to help with all of these and more. They include: \n\n1. **Anomalous New Process:** This search alerts you when an unusual number of hosts are detected running a new process.\n\n1. **Anomalous New Service:** Alerts when an anomalous number of hosts are detected with a new service.\n\n1. **Prohibited Process Detected:** Detects prohibited processes running in the environment.\n\n1. **Prohibited New Service:**  Detects prohibited services running in the environment.\n\n1. **New User Account Created on Multiple Hosts:** This search alerts you when it detects that numerous accounts are created for a username across multiple hosts. \n\n1. **Outbreak Detected:** This search will give you a distinct count of the number of systems affected by the malware event destination for the last 24 hours.",
			"spec_version": 1,
			"description": "Use the included searches to set up continuous monitoring for some of the most common threats in your network.",
			"last_updated": "2018-11-05",
			"version": 1.0,
			"maintainers": [{
				"email": "rvaldez@splunk.com",
				"name": "Rico Valdez",
				"company": "Splunk"
			}],
			"searches": ["Endpoint - Anomalous New Processes - Rule", "Endpoint - Anomalous New Services - Rule", "Endpoint - Anomalous User Account Creation - Rule", "Endpoint - Outbreak Observed - Rule", "Endpoint - Prohibited Process Detection - Rule", "Endpoint - Prohibited Service Detection - Rule"],
			"category": "Adversary Tactics",
			"references": [""]
		}
	}, {
		"acl": {
			"can_share_app": true,
			"modifiable": true,
			"owner": "nobody",
			"can_write": true,
			"removable": false,
			"sharing": "global",
			"can_change_perms": true,
			"can_share_user": false,
			"can_list": true,
			"perms": {
				"write": ["*"],
				"read": ["*"]
			},
			"app": "DA-ESS-NetworkProtection",
			"can_share_global": true
		},
		"name": "Network Protection",
		"stanza_type": "analytic_story",
		"content": {
			"narrative": "Continuous network monitoring for advanced threats has become mission critical in the context of today's constantly evolving threat landscape. What's more, given the potentially devastating consequences of a breach, the necessity for strong defense, rapid detection, and the agility to respond immediately to threats has never been higher.\n\nThis use case focuses on detecting anomalous activity that may indicate that an adversary has penetrated your network. It monitors DNS and ports for unusual activity and looks for vulnerability scanners.\n\nIt includes the following searches:\n\n1. **Excessive DNS Failures:** This search alerts when a host is detected with a high number of failed DNS requests. \n\n1. **Excessive DNS Queries:** Detect an excessive number of DNS queries from a host, which may indicate that a threat actor is sending data to a malicious server.\n\n1. **Prohibited Port Activity Detected:** Use of unapproved ports can help you monitor for the installation of new software (potentially unapproved) or a successful compromise of a host (such as the presence of a backdoor or a system communicating with a botnet). This search returns values where the destination port is > 0 and `is_prohibited` is not \"false.\"\n\n1. **Vulnerability Scanner Detected (by events):** Detects possible vulnerability scanners by monitoring for devices that have triggered a large number of unique events, activity that is typical of a vulnerability scanner (because each vulnerability check tends to trigger a unique event).\n\n1. **Vulnerability Scanner Detected (by targets):** This search detects possible vulnerability scanners by monitoring for devices that have triggered events against a large number of unique targets, which is typical for vulnerability scanners (they are scanning a network for vulnerable hosts).",
			"spec_version": 1,
			"description": "Detect anomalous activity that may indicate that an adversary has penetrated your network. This use case monitors DNS and ports for unusual activity and looks for vulnerability scanners.",
			"last_updated": "2018-11-05",
			"version": 1.0,
			"maintainers": [{
				"email": "rvaldez@splunk.com",
				"name": "Rico Valdez",
				"company": "Splunk"
			}],
			"searches": ["Network - Excessive DNS Failures - Rule", "Network - Excessive DNS Queries - Rule", "Network - Unapproved Port Activity Detected - Rule", "Network - Vulnerability Scanner Detection (by event) - Rule", "Network - Vulnerability Scanner Detection (by targets) - Rule"],
			"category": "Best Practices",
			"references": ["https://www.esecurityplanet.com/network-security/security-information-event-management-siem.html"]
		}
	}]
}

POST

Add a new stanza of the given stanza_type. Following splunkd common practice, PUT with name argument will also create a new stanza of that name.

Request string
An argument string must include the following fields: name, stanza_type, content.

Field Description
name The name of the new stanza that you're creating. Special {stanza_type} "all" is not allowed. Required.
stanza_type
analytic_story
For adding an analytic story, the stanza_type parameter is analytic_story. Required parameters for analytic_story are the following: name, searches, spec_version, version.
analytic_story_category
For adding additional info to an analytic story category, the stanza_type parameter is analytic_story_category. This is additional info for an analytic story category <name> where name is the value of categoryunder analytic_story stanza. The required parameter for analytic_story_category is name.
savedsearch
For adding saved search metadata, the stanza_type parameter is savedsearch. This defines metadata for savedsearch named name. Required parameters for analytic_story are the following: name, type.
content A JSON object containing the key/value pairs. For the parameters of each {stanza_type}, see Stanza_type Parameters.

Response

A success or failure message.


Example request
Add a new analytic story named "my_story" as follows:

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/analytic_story \
-d '{"name":"my_story","content":{"category":"Best Practices","description":"This is my own analytic story","searches":["ESCU - Prohibited Software On Endpoint - Rule","ESCU - Detect malicious requests to exploit JBoss servers - Rule"],"spec_version":1,"version":1}}'

Example response

{
	"entry": [{
		"stanza_type": "analytic_story",
		"acl": {
			"can_share_global": true,
			"can_change_perms": true,
			"can_share_app": true,
			"can_list": true,
			"removable": true,
			"modifiable": true,
			"can_write": true,
			"sharing": "app",
			"owner": "admin",
			"perms": {
				"read": ["*"],
				"write": ["admin", "power"]
			},
			"app": "search",
			"can_share_user": true
		},
		"content": {
			"spec_version": 1,
			"searches": ["ESCU - Prohibited Software On Endpoint - Rule", "ESCU - Detect malicious requests to exploit JBoss servers - Rule"],
			"category": "Best Practices",
			"description": "This is my own analytic story",
			"version": 1
		},
		"name": "my_story"
	}],
	"paging": {
		"perPage": 30,
		"total": 1,
		"offset": 0
	}
}

/services/analyticstories/configs/{stanza_type}/{name}

Acts as a proxy to configs/conf-analyticstories/{stanza_name}. Accepts standard splunkd query terms.

Syntax

https://<host>:<mPort>/services/analyticstories/configs/{stanza_type}/{name}

Usage details
The {stanza_type} must be one of the following:

  • analytic_story
  • analytic_story_category
  • savedsearch


POST

Update stanza {name} of the specified stanza_type. This updates corresponding fields specified in the REST call and leaves the other existing values intact.

Request string
An argument string must include the following fields: name, stanza_type, content.

Field Description
name The name of the new stanza that you're creating. Special {stanza_type} "all" is not allowed. Required.
stanza_type
analytic_story
For adding an analytic story, the stanza_type parameter is analytic_story. Required parameters for analytic_story are the following: name, searches, spec_version, version.
analytic_story_category
For adding additional info to an analytic story category, the stanza_type parameter is analytic_story_category. This is additional info for an analytic story category <name> where name is the value of categoryunder analytic_story stanza. The required parameter for analytic_story_category is name.
savedsearch
For adding saved search metadata, the stanza_type parameter is savedsearch. This defines metadata for savedsearch named name. Required parameters for analytic_story are the following: name, type.
content A JSON object containing the key/value pairs. For the parameters of each {stanza_type}, see Stanza_type Parameters.


Example request
Update the analytic story named "Access Protection" with a new description.

Create a file called update.json, for example, with the following content:

{
  "content": {
    "last_updated": "2019-05-31",
    "description": "my new description",
    "version": 1
  }
}

Use the file to update the analytic story as follows:

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/analytic_story/Access%20Protection -d @update.json | python -m json.tool 

Example response
If the request is successful, the endpoint returns a JSON object.

{
	"entry": [{
		"acl": {
			"app": "search",
			"can_change_perms": true,
			"can_list": true,
			"can_share_app": true,
			"can_share_global": true,
			"can_share_user": true,
			"can_write": true,
			"modifiable": true,
			"owner": "admin",
			"perms": {
				"read": [
					"*"
				],
				"write": [
					"admin",
					"power"
				]
			},
			"removable": true,
			"sharing": "app"
		},
		"content": {
			"category": "Best Practices",
			"description": "my new description",
			"last_updated": "2019-05-31",
			"maintainers": [{
				"company": "Splunk",
				"email": "rvaldez@splunk.com",
				"name": "Rico Valdez"
			}],
			"narrative": "Access protection&#151;selective restriction of who may access data or other resources via authentication and authorization&#151;is arguably one of the most important activities in network security. The first part of the equation, authentication, involves ensuring that the user is who they purport to be. Next, an authorization process determines the level of privilege the user or role possesses.\n\nAlthough implementing an end-to-end access-protection system is critical, no system is foolproof, making ongoing automated monitoring critical. This use case is designed to help you detect attackers who may be attempting to circumvent access-protection mechanisms in your environment. It includes the following searches: \n\n1. **Excessive Failed Logins:** Detects excessive numbers of failed login attempts (typical of a brute-force attack)\n\n1. **Inactive Account Usage:** Discovers previously inactive accounts that are now being used.\n\n1. **Insecure Or Cleartext Authentication Detected:** Detects authentication requests that transmit the password over the network as cleartext (unencrypted).\n\n1. **Short-lived Account Detected:** Looks for accounts that were created and or deleted within the previous four hours&#151;a possible red flag.",
			"references": [
				"https://www.sans.org/media/critical-security-controls/critical-controls-poster-2016.pdf"
			],
			"searches": [
				"Access - Excessive Failed Logins - Rule",
				"Access - Inactive Account Usage - Rule",
				"Access - Insecure Or Cleartext Authentication - Rule",
				"Access - Short-lived Account Detected - Rule"
			],
			"spec_version": 1,
			"version": 1
		},
		"name": "Access Protection",
		"stanza_type": "analytic_story"
	}],
	"paging": {
		"offset": 0,
		"perPage": 30,
		"total": 1
	}
}

PUT

Replace stanza {name} of the specified {stanza_type}. This replaces the entire configuration of that stanza with the values in the REST call. If the REST call does not provide a value for a field, it is treated as unset.

Request string
An argument string must include the following fields: name, stanza_type, content.

Field Description
name The name of the stanza that you're updating. Special {stanza_type} "all" is not allowed. Required.
stanza_type
analytic_story
For adding an analytic story, the stanza_type is analytic_story. Required parameters for analytic_story are the following: name, searches, spec_version, version.
analytic_story_category
For adding additional info to an analytic story category, the stanza_type is analytic_story_category. This is additional info for an analytic story category <name> where name is the value of categoryunder analytic_story stanza. The required parameter for analytic_story_category is name.
savedsearch
For adding saved search metadata, the stanza_type is savedsearch. This defines metadata for savedsearch named name. Required parameters for analytic_story are the following: name, type.
content A JSON object containing the key/value pairs. For the parameters of each {stanza_type}, see Stanza_type Parameters.

Example request
Update the savedsearch named "my_saved_search" with new parameters for type, spec_version, status, confidence, and asset_type.

curl -X PUT -u admin:changeme -k https://localhost:8089/services/analyticstories/configs/savedsearch/my_saved_search \
-d '{"name":"my_saved_search","stanza_type":"savedsearch","content":{"type":"access","spec_version":1,"status":"development","confidence":"medium","asset_type":"AWS"}}'

Example response
If the request is successful, the endpoint returns a JSON object.

{"paging": {"perPage": 30, "offset": 0, "total": 1}, "entry": [{"name": "my_saved_search", "content": {"spec_version": 1, "asset_type": "AWS", "confidence": "medium", "status": "development", "type": "access"}, "stanza_type": "savedsearch", "acl": {"modifiable": true, "can_list": true, "owner": "admin", "can_write": true, "app": "search", "can_share_app": true, "removable": true, "perms": {"write": ["admin", "power"], "read": ["*"]}, "can_share_global": true, "can_change_perms": true, "can_share_user": true, "sharing": "app"}}]}

GET

Return the stanza {name} of the specified stanza_type.

Example request
Retrieve the analytic story named "my_story."

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/analytic_story/my_story -G -X GET

Example response
If the request is successful, the endpoint returns a JSON object.

{"entry":[{"acl":{"can_share_global":true,"modifiable":true,"removable":true,"sharing":"global","app":"SplunkEnterpriseSecuritySuite","can_share_app":true,"owner":"plainuser","can_list":true,"perms":{"read":["*"],"write":["*"]},"can_change_perms":true,"can_share_user":true,"can_write":true},"content":{"descriptions":"asdf","spec_version":1},"stanza_type":"analytic_story","name":"alala"}],"paging":{"offset":0,"perPage":30,"total":1}}

If the request fails, the endpoint returns an error message.

{"messages":[{"text":"version: u'B' is not of type u'integer'","type":"ERROR"},{"text":"maintainers: u'bennay' is not of type u'array'","type":"ERROR"}]}

/services/analyticstories/configs/{stanza_type}/{name}/acl

Returns ACL information. The accepted parameters are the same as Splunk /acl endpoints. See Access Control List in the REST API User Manual.

Syntax

https://<host>:<mPort>/services/analyticstories/configs/{stanza_type}/{name}/acl

Usage details
The {stanza_type} must be one of the following:

  • analytic_story
  • analytic_story_category
  • savedsearch

POST

Update ACL information.

Example request
Share the analytic story named "my other story" globally and change its permissions.

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/analytic_story/my%20other%20story/acl \
        -d owner=plainuser \
        -d perms.read=* \
        -d sharing=global

Example response
If the request is successful, the endpoint returns a JSON object.

{"entry": [{"owner": "plainuser", "can_write": true, "perms": {"read": ["*"]}, "sharing": "global", "app": "search", "modifiable": true, "can_share_app": true, "removable": true, "can_share_global": true, "can_share_user": true, "can_change_perms": true, "can_list": true}], "paging": {"total": 1, "perPage": 30, "offset": 0}}

GET

Return the ACL information.

Example request
Retrieve the ACL for the analytic story named "my_story."

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/analytic_story/my_story/acl -G -X GET

Example response
If the request is successful, the endpoint returns a JSON object.

{"entry":[{"can_share_global":true,"modifiable":true,"removable":true,"sharing":"global","app":"SplunkEnterpriseSecuritySuite","can_share_app":true,"owner":"plainuser","can_list":true,"perms":{"read":["*"],"write":["*"]},"can_change_perms":true,"can_share_user":true,"can_write":true}],"paging":{"offset":0,"perPage":30,"total":1}}

/services/analyticstories/configs/{stanza_type}/{name}/move

Moves stanzas to other apps. The accepted parameters are the same as Splunk /move endpoints. See Move an object to a different app in the REST API Tutorials.

Syntax

https://<host>:<mPort>/services/analyticstories/configs/{stanza_type}/{name}/move

Usage details
The {stanza_type} must be one of the following:

  • analytic_story
  • analytic_story_category
  • savedsearch

POST

Move stanza to another app.

Example request
Make the analytic story named "my_story" available to all users and change the context to a different app.

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/analytic_story/my_story/move  \
        -d user=nobody \
        -d app=otherapp

/services/analyticstories/configs/_reload

Reloads data for the endpoint.

Syntax

https://<host>:<mPort>/services/analyticstories/configs/_reload

GET

Append _reload to a URL to force the server to reload data for the endpoint.

Example request
Inform splunkd to reload analyticstories.conf, in case of manual edits to the file.

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/configs/_reload  -G -X GET

/services/analyticstories/schemas/{version}

Return the JSON schema for the analytic stories. The schema is used for validation.

Syntax

https://<host>:<mPort>/services/analyticstories/schemas/{version}

Usage details
The last segment {version} would be either of the following:

  • The letter v followed by spec version number, such as v1
  • The word latest for the latest version

Frontend or users can use the returned schema to do validations.

GET

Return the JSON schema for version 1.

Example request
Return the JSON schema for version 1.

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/schemas/v1 -G -X GET

/services/analyticstories/batch

Takes a JSON array conforming to the analytic story JSON schema and saves it in proper format into analyticstories.conf.

Syntax

https://<host>:<mPort>/services/analyticstories/batch

Usage details
The {stanza_type} must be one of the following:

  • analytic_story
  • analytic_story_category
  • savedsearch

POST

Batch update or create multiple stanzas.

Example request
The POST input is a JSON array whose element is of format specified in "/services/analyticstories/configs/{stanza_type}"

Create a file called batch.json, for example, with the following content:

[{
  "name": "my other story",
  "stanza_type": "analytic_story",
  "content": {
    "category": "Best Practices",
    "description": "This is my own other analytic story",
    "searches": ["ESCU - Other Prohibited Software On Endpoint - Rule", "ESCU - Detect malicious requests to exploit JBoss servers - Rule"],
    "spec_version": 1,
    "version": 1
  }
}, {
  "name": "my third story",
  "stanza_type": "analytic_story",
  "content": {
    "category": "Malware",
    "description": "Detect malware",
    "searches": ["ESCU - Detect malicious requests to exploit JBoss servers - Rule"],
    "spec_version": 1,
    "version": 1,
    "last_updated": "2019-06-02"
  }
}, {
  "name": "SpearPhishing",
  "stanza_type": "analytic_story_category",
  "content": {
    "icon": "spearphishing.png"
  }
}]

Use the file to update multiple analytic stories as follows:

curl -k -u admin:changeme https://localhost:8089/services/analyticstories/batch -d @batch.json | python -m json.tool

Example response
If the request is successful, the endpoint returns the items created or updated.

{"entry":[{"acl":{"app":"search","can_change_perms":true,"can_list":true,"can_share_app":true,"can_share_global":true,"can_share_user":true,"can_write":true,"modifiable":true,"owner":"admin","perms":{"read":["*"],"write":["admin","power"]},"removable":true,"sharing":"app"},"content":{"category":"Best Practices","description":"This is my own other analytic story","searches":["ESCU - Other Prohibited Software On Endpoint - Rule","ESCU - Detect malicious requests to exploit JBoss servers - Rule"],"spec_version":1,"version":1},"name":"my other story","stanza_type":"analytic_story"},{"acl":{"app":"search","can_change_perms":true,"can_list":true,"can_share_app":true,"can_share_global":true,"can_share_user":true,"can_write":true,"modifiable":true,"owner":"admin","perms":{"read":["*"],"write":["admin","power"]},"removable":true,"sharing":"app"},"content":{"category":"Malware","description":"Detect malware","last_updated":"2019-06-02","searches":["ESCU - Detect malicious requests to exploit JBoss servers - Rule"],"spec_version":1,"version":1},"name":"my third story","stanza_type":"analytic_story"},{"acl":{"app":"search","can_change_perms":true,"can_list":true,"can_share_app":true,"can_share_global":true,"can_share_user":true,"can_write":true,"modifiable":true,"owner":"admin","perms":{"read":["*"],"write":["admin","power"]},"removable":true,"sharing":"app"},"content":{"icon":"spearphishing.png","spec_version":1},"name":"SpearPhishing","stanza_type":"analytic_story_category"}]}

Stanza_type Parameters

The following parameters are used per stanza_type.

analytic_story parameters description
name Defines an analytic story of title name, such as analytic_story://<name>. Cannot be an empty string.
category A string that best describes this type of analytic story, such as "Abuse" or "Compliance" or "Malware." If unset, it will be displayed as "Uncategorized". Optional.
description A string explanation of why the story is useful or what the story includes.
last_updated Update time of the analytic story in the format of ISO 8601 date format YYYY-MM-DD. Optional.
maintainers A JSON array of the current maintainers of the analytic story. Defaults to an empty array. Optional.

Format of each item:

{
   "company": "<string>",
   "email": "<string>",
   "name": "<string>"
 }

company (optional): Company associated with the person maintaining this analytic story
email (required, valid RFC5322 addr-spec): Email address of the person maintaining this analytic story
name (required, non-empty): Name of the person maintaining this analytic story

narrative Long-form text that describes the analytic story use case and the rationale behind it, an overview of the included searches, and how to enable the story. Optional.
references A JSON array of URLs that give information about the problem the story is addressing. Optional.
searches A JSON array of searches used by the analytic story. Each string in the array refers to a unique savedsearch name. Required.
spec_version Version of analytics spec used by current stanza, in positive integer number format. A larger number means a more recent update. Required.
analytic_story_category
parameters
description
name Additional info for analytic story category <name>, where <name> is the value of 'category' under analytic_story stanza. Cannot be an empty string.
description A string explanation of the category.
icon An image file for the category. It should be the filename of the icon image located under <app>/appserver/static. Supported format is png. Optional.
spec_version Version of analytics spec used by current stanza, in positive integer number format. A larger number means a more recent update. Required.
savedsearch parameters description
name Defines metadata for savedsearch named <name>. Cannot be an empty string.
annotations A JSON object of metadata on the search, currently used to annotate a search with various industry standards and frameworks. Optional.

The supported format and standards follow:

{
   "cis20": ["<string>"],
   "kill_chain_phases": ["<string>"],
   "mitre_attack": ["<string>"],
   "nist": ["<string>"]
}

cis20: Critical security controls this search implements
kill_chain_phases: Kill-chain phases to which the search applies
mitre_attack: Techniques and tactics identified by the search
nist: Controls the search implements

asset_type Type of asset being investigated in string format. For example, AWS Instance. Optional.
confidence Confidence that detected behavior is malicious. For instance, high, medium, or low. Optional.
earliest_time_offset The number of seconds into the past from the event time the search should cover, in the format of a non-negative integer. Optional.
explanation Detailed description of the SPL, written in a style that can be understood without deep technical knowledge. Optional.
how_to_implement A description of how to put this search into effect, from what needs to be ingested, config files modified, and suggested per site modifications. Optional.
known_false_positives Scenarios in which detected behavior is benign, coupled with suggestions on how to verify the behavior. Optional.
latest_time_offset The number of seconds into the future from the event time the search should cover, in the format of a non-negative integer. Optional.
providing_technologies External services, software, or hardware that would provide data this analytic story relies on, in the format of a JSON array of strings. Optional.
status Current status of the search. For example: development, experimental, production. Optional.
type Type of this search. Cannot be an empty string. Required.
Last modified on 29 January, 2022
PREVIOUS
Notable Event API reference
 

This documentation applies to the following versions of Splunk® Enterprise Security: 5.2.0, 5.2.1, 5.2.2, 5.3.0, 5.3.1, 6.0.0, 6.0.1, 6.0.2, 6.1.0, 6.1.1, 6.2.0, 6.3.0 Cloud only, 6.4.0, 6.4.1, 6.5.0 Cloud only, 6.5.1 Cloud only, 6.6.0, 6.6.2


Was this documentation topic helpful?


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