Configuring correlation searches

Configure correlation searches to update the settings associated with how they run. See Correlation search overview to learn more about a correlation search.

Enable correlation searches

Enable correlation searches to start running adaptive response actions and receiving notable events. Splunk Enterprise Security installs with all correlation searches disabled so that you can choose the searches that are most relevant to your security use cases.

From the Splunk ES menu bar, select Configure > Content Management.
Filter the Content Management page by a Type of Correlation Search to view only correlation searches.
Review the names and descriptions of the correlation searches to determine which ones to enable to support your security use cases.
For example, if compromised accounts are a concern, consider enabling the Concurrent Login Attempts Detected and Brute Force Access Behavior Detected correlation searches.
In the Actions column, click Enable to enable the searches that you want to enable.

After you enable correlation searches, dashboards will start to display notable events, risk scores, and other data.

Change correlation search scheduling

Change the default search type of a correlation search from real-time to scheduled. Splunk Enterprise Security uses indexed real-time searches by default.

From the Content Management page, locate the correlation search you want to change.
In the Actions column, click Change to scheduled.

Editing correlation searches

You can make changes to correlation searches to fit your environment. For example, modify the thresholds used in the search, change the response actions that result from a successful correlation, or change how often the search runs. Modifying a correlation search does not affect existing notable events.

Click the name of a correlation search on the Content Management page to edit it.

If you modify the start time and end time for the correlation search, use relative time modifiers. See Specify time modifiers in your search in the Splunk Enterprise Search Manual.

Edit the correlation search in guided mode

You can edit some correlation searches in guided mode. Not all correlation searches support guided search editing. If a search appears grayed-out and has the option to Edit search manually or Edit search in guided mode, the search was built in guided mode and can be edited in guided mode. If a search can be edited in the search box and only has the option to Edit search in guided mode, editing the search in guided mode overwrites the existing search.

Click Edit search in guided mode to open the guided search creation wizard.
Review the search elements in the correlation search, making changes if you want.
Save the search.

Throttle the number of response actions generated by a correlation search

Set up throttling to limit the number of response actions generated by a correlation search. When a correlation search matches an event, it triggers a response action.

By default, every result returned by the correlation search generates a response action. Typically, you may only want one alert of a certain type. You can use throttling to prevent a correlation search from creating more than one alert. Some response actions allow you to specify a maximum number of results in addition to throttling. See Set up adaptive response actions in Splunk Enterprise Security.

Select Configure > Content Management.
Click the title of the correlation search you want to edit.
Type a Window duration. During this window, any additional event that matches any of the Fields to group by will not create a new alert. After the window ends, the next matching event will create a new alert and apply the throttle conditions again.
Type the Fields to group by to specify which fields to use when matching similar events. If a field listed here matches a generated alert, the correlation search will not create a new alert. You can define multiple fields, and available fields depend on the search fields that the correlation search returns.
Save the correlation search.

Throttling applies to any type of correlation search response action and occurs before notable event suppression. See Create and manage notable event suppressions for more on notable event suppression.

Obtain a list of correlation searches

To obtain a list of correlation searches enabled in Splunk Enterprise Security, use a REST search to extract the information that you want in a table.

For example, create a table with the app, security domain, name, and description of all correlation searches in your environment.

| rest splunk_server=local count=0 /services/saved/searches | where match('action.correlationsearch.enabled', "1|[Tt]|[Tt][Rr][Uu][Ee]") | rename eai:acl.app as app, title as csearch_name, action.correlationsearch.label as csearch_label, action.notable.param.security_domain as security_domain | table csearch_name, csearch_label, app, security_domain, description

As another example, create a table with only the enabled correlation searches and the adaptive response actions associated with those searches in your environment. To see the adaptive response actions for all correlation searches, remove | where disabled=0.

Correlation searches migration to `savedsearches.conf`

Starting in Splunk Enterprise Security version 4.6.0, correlationsearches.conf is no longer used to define correlation searches. Instead, savedsearches.conf uniquely identifies correlation searches using the action.correlationsearch.enabled=1 parameter. The correlationsearches.conf file is deprecated.

For stability, the Threat - Correlation Searches - Lookup Gen saved search continues to use the contents of both correlationsearches.conf and savedsearches.conf to populate the correlationsearches KV Store collection used by Incident Review.

Changes Splunk Enterprise Security makes at upgrade

When you upgrade to Splunk Enterprise Security 4.6.0, Splunk Enterprise Security migrates all correlation searches in your environment, including custom correlation searches. The confcheck_es_correlationmigration.py script migrates all entries in correlationsearches.conf into updated entries in savedsearches.conf. The migration can take up to five minutes to complete after the upgrade.

During the upgrade, Splunk Enterprise Security continues to create notable events without interruption.

Changes you have to make after upgrade

After upgrading to Splunk Enterprise Security 4.6.0, you have to make additional changes.

Check for searches that did not migrate successfully and migrate the correlationsearches.conf entries manually using the parameter definitions below.
Update searches that call the correlationsearches REST endpoint.
- For example, a search that displays a list of correlation searches in your environment would change from
  | rest splunk_server=local /services/alerts/correlationsearches | rename eai:acl.app as app, title as csearch_name | table app security_domain csearch_name description
  to
  | rest splunk_server=local count=0 /services/saved/searches | where match('action.correlationsearch.enabled', "1|[Tt]|[Tt][Rr][Uu][Ee]") | rename eai:acl.app as app, title as csearch_name, action.correlationsearch.label as csearch_label, action.notable.param.security_domain as security_domain | table csearch_name, csearch_label, app, security_domain, description
- See Obtain a list of correlation searches for more examples of updated searches.

Both the correlationsearches.conf and savedsearches.conf files are used to populate the KV Store collection used by Incident Review. Custom search macros that reference that KV Store collection continue to work as before, but consider updating them anyway.

`correlationsearches.conf` parameter translation to `savedsearches.conf`

All correlationsearches.conf parameters now exist in savedsearches.conf and the correlationsearches.conf file has been deprecated. Do not update it directly except to manually migrate correlation search definitions.

Identification parameters for correlation searches

New parameters identify whether a saved search is a correlation search and the name of the correlation search.

`correlationsearches.conf` parameter in pre-4.6.0 versions	`savedsearches.conf` parameter starting in 4.6.0	Notes
N/A	`action.correlationsearch=0`	This is an internal parameter and can be ignored.
A stanza for the search exists	`action.correlationsearch.enabled=1`	This parameter identifies a saved search as a correlation search.
`rule_name`	`action.correlationsearch.label`	This parameter provides the name of the correlation search.
`description`	`description`	This parameter provides the description of the correlation search.

Notable event parameters for correlation searches

The action.notable parameter identifies a notable event associated with a correlation search. The parameters that describe additional details associated with the notable event now exist in the savedsearches.conf file.

`correlationsearches.conf` parameter in pre-4.6.0 versions	`savedsearches.conf` parameter starting in 4.6.0
`security_domain`	`action.notable.param.security_domain`
`severity`	`action.notable.param.severity`
`rule_title`	`action.notable.param.rule_title`
`rule_description`	`action.notable.param.rule_description`
`nes_fields`	`action.notable.param.nes_fields`
`drilldown_name`	`action.notable.param.drilldown_name`
`drilldown_search`	`action.notable.param.drilldown_search`
`default_status`	`action.notable.param.default_status`
`default_owner`	`action.notable.param.default_owner`

Example correlation search stanzas from this version and previous versions

The savedsearches.conf stanza for a correlation search looks as follows starting in 4.6.0.

[Access - Concurrent App Accesses - Rule]
action.correlationsearch = 0
action.correlationsearch.enabled = 1
action.correlationsearch.label = Concurrent Login Attempts Detected
action.email.sendresults = 0
action.notable = 0
action.notable.param.security_domain = access
action.notable.param.severity = medium
action.notable.param.rule_title = Concurrent Access Event Detected For $user$
action.notable.param.rule_description = Concurrent access attempts to $app1$ by $user$ from two different sources( $src1$, $src2$ ) have been detected.
action.notable.param.nes_fields = user
action.notable.param.drilldown_name = View access attemps by $user$
action.notable.param.drilldown_search = | datamodel Authentication Authentication search | search Authentication.user="$user$"
action.risk = 1
action.risk.param._risk_object = user
action.risk.param._risk_object_type = user
action.risk.param._risk_score = 20
alert.suppress = 1
alert.suppress.fields = user
alert.suppress.period = 86300s
alert.track = false
cron_schedule = 10 * * * *
description = Alerts on concurrent access attempts to an app from different hosts. These are good indicators of shared passwords and potential misuse.
disabled = True
dispatch.earliest_time = -70m@m
dispatch.latest_time = -5m@m
enableSched = 1
is_visible = false
request.ui_dispatch_app = SplunkEnterpriseSecuritySuite
search = | tstats `summariesonly` count from datamodel=Authentication.Authentication by _time,Authentication.app,Authentication.src,Authentication.user span=1s | `drop_dm_object_name("Authentication")` | eventstats dc(src) as src_count by app,user | search src_count>1 | sort 0 + _time | streamstats current=t window=2 earliest(_time) as previous_time,earliest(src) as previous_src by app,user | where (src!=previous_src) | eval time_diff=abs(_time-previous_time) | where time_diff<300

In previous versions of Splunk Enterprise Security, the savedsearches.conf and correlationsearches.conf definitions for the same correlation search would look as follows. savedsearches.conf

[Access - Concurrent App Accesses - Rule]
action.email.sendresults            = 0
action.risk                         = 1
action.risk.param._risk_object      = user
action.risk.param._risk_object_type = user
action.risk.param._risk_score       = 20
alert.suppress                      = 1
alert.suppress.fields               = user
alert.suppress.period               = 86300s
alert.track                         = false
cron_schedule                       = 10 * * * *
disabled                            = True
dispatch.earliest_time              = -70m@m
dispatch.latest_time                = -5m@m
enableSched                         = 1
is_visible                          = false
request.ui_dispatch_app             = SplunkEnterpriseSecuritySuite
search                              = | tstats `summariesonly` count from datamodel=Authentication.Authentication by _time,Authentication.app,Authentication.src,Authentication.user span=1s | `drop_dm_object_name("Authentication")` | eventstats dc(src) as src_count by app,user | search src_count>1 | sort 0 + _time | streamstats current=t window=2 earliest(_time) as previous_time,earliest(src) as previous_src by app,user | where (src!=previous_src) | eval time_diff=abs(_time-previous_time) | where time_diff<300

correlationsearches.conf

[Access - Concurrent App Accesses - Rule]
security_domain     = access
severity            = medium
rule_name           = Concurrent Login Attempts Detected
description         = Alerts on concurrent access attempts to an app from different hosts. These are good indicators of shared passwords and potential misuse.
rule_title          = Concurrent Access Event Detected For $user$
rule_description    = Concurrent access attempts to $app1$ by $user$ from two different sources( $src1$, $src2$ ) have been detected.
nes_fields          = user
drilldown_name      = View access attemps by $user$
drilldown_search    = | datamodel Authentication Authentication search | search Authentication.user="$user$"
default_owner       =
default_status      =

Related answers from Splunk Community