Upgrade Splunk App for Enterprise Security to a newer version

Follow these steps to use the Enterprise Security Install App to upgrade from the Splunk App for Enterprise Security 2.x to a newer version.

For details about what is new in this release, see "Enhancements" in the Release Notes.

Step 1. Get the Splunk App for Enterprise Security

1. Download the Splunk App for Enterprise Security Install app version 3.0 from Splunk Apps.

2. Click Download App and save the Splunk Enterprise Security Install App (splunk-app-for-enterprise-security_300.tgz) to your desktop.

Note: You must be logged into Splunk Apps with your Splunk.com ID and be a licensed customer to download the app. If you have issues, contact Splunk Support.

3. From Splunk Home, navigate to App > Manage Apps… > Install App from File to add the Install App to your Splunk instance.

Important: If you already have the Enterprise Security Install App on your system, be sure to click Upgrade app. and overwrite the existing app with the newer version when you upload the file.

4. Restart Splunk.

Step 2. Launch the upgrade installer

1. After Splunk restarts, log back into Splunk.

2. Go to Splunk Home and click Enterprise Security Install App.

3. The Install App appears. To perform the upgrade, the installer first needs to disable the current instance of the Splunk App for Enterprise Security. Click Disable to begin.

4. Restart Splunk.

Note: The Splunk App for Enterprise Security includes a setting that forces Splunk Web to run over HTTPS. While disabled you may need to connect to Splunk Web using HTTP instead (HTTP://yourserver:yourport).

4. Click the click here to continue link when the Splunk restart is complete.

Re-enable the app

Should you, for any reason, choose not to continue with the upgrade and instead want to continue to use the existing version of the Splunk App for Enterprise Security, you must re-enable the app before it can be used.

In order to fully re-enable the Splunk App for Enterprise Security, you must re-enable all of the following apps using Manage Apps:

• SA-*
• TA-*
• DA-ESS-*
• Splunk_TA-*
• Splunk_SA-*
• SplunkEnterpriseSecuritySuite

To do this:

1. From Splunk Home go to Apps > Manage Apps.

2. Click Enable next to each of these apps.

3. Restart Splunk.

The SA-* and DA-ESS* apps do not contain UI elements; because of this no Enable button shows up on the Splunk Web Home page.

Note: SA-AuditAndDataProtection is among the apps disabled/enabled as part of the upgrade process. If SA-AuditAndDataProtection is in the disabled state, Splunk is accessed via HTTP; if it is enabled, Splunk is accessed via HTTPS.

Step 3. Evaluate your environment prior to upgrade

1. After restarting Splunk, log back into Splunk. In the Enterprise Security Install App, click Continue to begin the upgrade.

2. The Upgrade and Compare screen contains tabs with upgrade warnings, customizations, deprecated apps, or changes to the default configuration files associated with the upgrade. Review each of these tabs before continuing with the upgrade. See "Resolve warnings and conflicts" for details.

3. Use the information in these panels to evaluate your existing configuration and resolve potential conflicts and customizations that could pose a problem during the upgrade. See Resolve warnings and conflicts for more information.

4. As you make changes to resolve issues, click Recheck to verify that the issue is fixed. Repeat this process as many times as necessary.

5. Click Print Report for a list of the warnings, customizations, deprecated apps, and changes to configuration files associated with the upgrade.

Resolve warnings and conflicts

During an upgrade using the Enterprise Security Install App, you may encounter warnings and conflicts between your current installation and the newer version of the Splunk App for Enterprise Security.

The following sections describe the possible issues and the appropriate actions to resolve them.

Upgrade warnings

Any warnings associated with your upgrade are shown on this tab. Use the examples in this section to resolve these upgrade warnings.

A Custom navigation file is detected

This custom navigation file will prevent updates from being deployed with the new navigation. This custom file will be renamed (to default.xml.old) and disabled after the upgrade. Re-enable this custom navigation file to rollback the changes.

Explanation:

The latest version of the Splunk App for Enterprise Security includes major changes to app navigation. If you upgrade from a 2.x version, you have a pre-existing custom navigation for Enterprise Security, most likely an artifact of previous setup tasks that generate a custom, local navigation as a side effect.

If you didn't make any customizations to your navigation, you can ignore this message. The install/upgrade disables the existing custom navigation and deploys the new one. If you have customizations you want to keep, continue with the upgrade. After the upgrade, the new navigation will be used.

To retrieve your previous customizations, refer to the old navigation file, now located: $SPLUNK_HOME/etc/apps/SplunkEnterpriseSecuritySuite/local/data/ui/nav/default.xml.old. You will need to manually map and add the earlier customizations into the new default.xml navigation file.

Invalid Savedsearches.conf Attribute Settings

Example:

File: $SPLUNK_HOME/etc/apps/SA-NetworkProtection/local/aggregate.conf

Network - Policy Or Configuration Change - Rule ==> 
duration :: -86400 - ERROR: 'duration' less than 1 second group_by ::
 - ERROR: 'group_by' cannot be empty

Explanation:

These conflicts apply to the detection and conversion of correlation search aggregation settings. These errors only apply to ES 2.0.* upgrades, which used the correlation search aggregate framework, and correspond to invalid custom settings with that older framework. The change needed to fix each error is shown in the detected error message.

Example:

Network - Policy Or Configuration Change - Rule ==> 
duration :: -86400 - ERROR: 'duration' less than 1 second
group_by :: - ERROR: 'group_by' cannot be empty

Errors show the correlation search stanzas and the offending settings for each. Possible errors include:

    duration cannot be less than 1 second
    duration must be an integer
    group by cannot be empty

To resolve the issue, change the local values of settings in their respective stanzas, in the /local/aggregate.conf file before proceeding with the upgrade. Click the recheck button after you make changes to the aggregate.conf file to verify that the issue is resolved.

Local/Custom Savedsearch overwrites new default search

Example:

File: $SPLUNK_HOME/etc/apps/SA-EndpointProtection/local/savedsearches.conf

Endpoint - Recurring Malware Infection - Rule ==> search :: 
`get_summary(endpoint_summary,Endpoint - All Malware - Summary Gen)` | 
search * | stats dc(date_mday) as day_count by dest,signature | 
search day_count>3 | localop | aggregate search="Endpoint - Recurring Malware Infection - Rule"

Explanation:

You can modify search strings in a saved searches local directory, but if the newer version of the app includes a fix/change in the same saved search, the local version will prevent the new changes from taking effect. The searches detected here are specifically correlation searches and ones that have undergone conversion from the aggregate framework to the per-event-alerting framework.

Splunk recommends that you comment out the existing custom search string in your /local directory. The new search string in the /default stanza will be used. To preserve the existing custom search string, you will need to reconcile the differences between the existing search logic and the new analogous search string in the /default stanza.

Customizations

Click Customizations to see what local customizations may be lost during the upgrade. This tab identifies local customizations in .conf files in the Splunk App for Enterprise Security that may prevent new default content from taking effect. The Install App searches for modifications to configuration files in default and local directories and displays any custom configuration conflicts that may occur with the newer version of the app.

Changes to configuration files should always be performed in an equivalent file within the local sub-directory. User customizations made to default objects are not saved and will be overwritten during the app upgrade.

Warning: If you chose to move forward with the upgrade, the files listed will be overwritten and any customizations will be lost.

For guidance on modifying default files versus local files, see "About the default files" in the core Splunk Admin Manual.

The Splunk configuration file layering system gives local .conf settings precedence over default .conf settings. If a setting's value changed in the new release and there is an existing local setting, this prevents new functionality or fixes.

The reporting hierarchy for .conf files is as follows:

- removed file
- modified file
  - removed stanza
  - modified stanza
    - removed attribute setting
    - modified attribute setting

This information is presented this way in the panel:

• Local .conf files different from latest default version
• Local .conf stanzas removed from latest default version
• Local .conf attributes different from latest default version
• TSIDX Conflicts
• Navigation Lite View Differences

Conflicting deprecated local .conf files

The detected local customized files that are deprecated from the latest release. We recommend that you remove these files, as they no longer exist in default. Examine the files to determine if anything needs to be backed up.

Example:

Conflicting Deprecated Local .conf Files
file: SA-IdentityManagement/local/correlationsearches.conf

Conflicting modified local .conf files

The upgrade process may detect local configuration files that have stanza and attribute conflicts.

• Deprecated Stanzas: These stanzas no longer exist in the latest release. We recommend that you remove this stanza from the 'local' .conf file

deprecated stanza(s): file: SA-EndpointProtection/local/savedsearches.conf
> stanza: [Endpoint - Disk Tracker - Lookup Gen]

• Deprecated Attributes: These attributes no longer exist in the latest release. We recommend that you remove this attribute from the 'local' .conf file

deprecated attribute(s): file: SA-CommonInformationModel/local/macros.conf > stanza: [cim_ids_types]
attribute: errormsg

• Conflicting Attributes: The following attributes have updated default values in the latest release. We recommend that you evaluate whether you want to keep your local customization. You can simply remove it and the default value will override it.

conflicting attribute(s): file: SA-CommonInformationModel/local/macros.conf > stanza: [cim_ids_types]
attribute: definition

TSIDX Conflicts

These searches have updated search attributes. These are former lookup or summary generating searches that have been replaced with TSIDX generating searches.

Example:

TSIDX Conflicts
File: $SPLUNK_HOME/etc/apps/SA-AccessProtection/local/savedsearches.conf
Access - All Account Management - Lookup Gen

Evaluate and determine the significance of your customization. We recommend that you remove this customization to allow the new default search to replace it. See "Tscollect" in the core Splunk Search Reference for more information about TSIDX.

Navigation Lite View Differences

The Splunk app for Enterprise Security 2.0.x included the option of enabling "Lite" dashboards within the navigation. These dashboards have been deprecated in the latest release.

Navigation Lite View Conflicts
File: $SPLUNK_HOME/etc/apps/SplunkEnterpriseSecuritySuite/local/data/ui/nav/default.xml
access_center_lite

We recommend that you remove these links from the navigation.

Deprecated Apps

Click Deprecated Apps to see any currently installed apps or add-ons, previously shipped with the Splunk App for Enterprise Security, that are deprecated in this release. Some deprecated apps are replaced with a newer app and others are simply left in place. Notes on this tab tell you what the installer will do with each of these apps.

Default .conf

The Default .conf tab shows any modified default configuration files or extension files that have been detected by the Install App.

• Detected Modified Configuration Files: These files have been modified from the original files shipped with the Splunk App for Enterprise Security. These files will be overwritten during the installation. If you want to save the modified files, copy the files to an appropriate location (like the local directory on your system).

Warning: If you chose to move forward with the upgrade, the modified configuration files listed will be overwritten and any customizations will be lost.

• Detected Extension Files: These files are new 'extension' files detected by the Install app. They will be unaffected by the upgrade.

Step 4. Upgrade Enterprise Security

When you have reviewed each of the tabs and made changes, continue with the upgrade.

Note: If you chose not to continue with the upgrade, you will need upgrade manually.

1. Click Upgrade & Restart to perform the upgrade.

2. Click the click here to continue link when the Splunk restart is complete.

Note: The Splunk App for Enterprise Security automatically enables SSL. The link to Splunk should already provide the correct protocol redirection (https). If you do not get redirected properly, check the protocol in your web browser (for example: https://localhost:8000).

3. The Enterprise Security Install App should display a message like:

Splunk App for Enterprise Security is up to date. Current version (version:3.0.0, build:xxxx) 
is installed.

You will be notified of future updates. 

Do not remove or disable the Enterprise Security Install App.

Step 5. Set up and configure the app

After performing the upgrade, set up the app.

1. Click Splunk to go to Splunk Home.

2. Click the Enterprise Security app.

3. Click Continue to app setup page on the App configuration dialog.

Note: If the upgrade is performed, and the setup procedure is not run, Splunk may display errors on some dashboards.

4. Verify the settings on the Splunk App for Enterprise Security Setup page.

See "Capacity planning for a larger Splunk deployment" in the core Splunk product documentation for more information about capacity planning.

5. Click Save. The Enterprise Security configure page appears.

See the "Steps to configure" in this manual for more details on setting up the Splunk App for Enterprise Security.

Backup of the upgrade

The Enterprise Security Install App creates a backup of the Splunk App for Enterprise Security installation after the upgrade completes. The folder and ZIP file of the Enterprise Security installation are located at:

  $SPLUNK_home/etc/apps/ess-backup-yyyy-mm-dd-hh-nn-ss

This file is located $SPLUNK_HOME/etc/apps/.

Note: After completing the upgrade and restarting Splunk, check various parts of the Splunk App for Enterprise Security to see if they are still working as expected. For details about what is new in this release, see "Enhancements" in the Release Notes.