Administer and customize the investigation workbench

The workbench extends existing investigation functionality in Splunk Enterprise Security by allowing analysts to perform investigative actions in one location. Analysts investigate artifacts, or assets and identities, using panels, tabs, and profiles on the workbench. You can customize the workbench by creating panels, tabs, and profiles to help analysts. You can also set up artifact extraction from notable events to accelerate investigations that start from notable events.

The workbench introduces a configuration file, es_investigations.conf, that is used to manage the metadata for panels, tabs, and profiles. You can make changes in the file system by adding stanzas to the es_investigations.conf file. Refer to es_investigations.conf.spec and es_investigations.conf.example for details.

Create panels and tabs for the investigation workbench

The investigation workbench can display any prebuilt panel that has a workbench panel reference and has been added to a workbench tab.

1. Create or modify a prebuilt panel. See Create or modify a prebuilt panel for the investigation workbench in this topic.
2. Create a workbench panel that references the prebuilt panel. See Create a tab for the investigation workbench in this topic.
3. Create a workbench tab that includes the workbench panel. See Create a tab for the investigation workbench in this topic.

For an example of this entire process, see Example panel conversion and workbench panel creation in this topic.

Create or modify a prebuilt panel for the investigation workbench

You can use any prebuilt panel on the investigation workbench. You can create one specifically for the workbench, or you can modify an existing panel. You can create or modify a prebuilt panel with Splunk Enterprise Security in several ways:

• Create a panel from Content Management.
  1. From the ES menu bar, select Configure > Content > Content Management.
  2. Select Create New Content > Panel.
  3. Type a Prebuilt panel ID.
  4. Select a Destination App.
  5. Type Prebuilt panel XML.
  6. Click Save.
• Convert a dashboard panel to a prebuilt panel. See Convert an existing panel to a prebuilt panel in Dashboards and Visualizations.
• Modify a panel in Splunk Settings.
  1. From the Splunk menu bar, select Settings > User Interface.
  2. Click Prebuilt Panels and click Edit > Edit Panel for the panel that you want to modify.
     

     If you modify an existing prebuilt panel, consider cloning it before you modify it. If you clone the panel, change the panel ID so that you remember which one is specific to the workbench.

• Create a panel in Splunk Settings. See Add panels to dashboards in Dashboards and Visualizations.

When creating or modifying a prebuilt panel for the workbench, follow these guidelines for the best user experience:

• Add one or more tokens to the panel search to limit your search results to the artifacts investigated on the workbench. Use multiple tokens to substitute more than one type of artifact. Define your token using the syntax $token$. You set up the format of the token when you create the workbench panel.
• Remove the panel name from the panel XML. If you do not do this, two panel titles appear on the workbench. Workbench panels get the title from the Label field when you create a workbench panel.
• Add a drilldown to the panel so that analysts can add artifacts from the panel. Add a drilldown using the syntax <option name="drilldown">cell</option> in the panel XML. The workbench replaces existing panel drilldowns, such as custom searches, with this ability to add artifacts to the workbench scope from the panel.
• Update the permissions on the panel to be shared with Splunk Enterprise Security. Confirm that the panel is Shared in App or set to Display For: All Apps.
• If you save your panel in a dedicated app, make sure that the objects in the app are set to export globally. See Set permissions for objects in a Splunk app in the Splunk dev portal.
• To make your panel use a different time range than the one set by the workbench, set a time range in the panel search or panel XML.

Then, follow the steps to create a panel for the investigation workbench. See Create a panel for the investigation workbench in this topic.

Create or modify a panel for the investigation workbench

Create a workbench panel.

1. Select Configure > Content > Content Management.
2. Select Create New Content > Workbench Panel.
3. Select the prebuilt panel that you want to use on workbench from the drop-down list.
4. (Optional) Type a Label to replace the default panel title on the workbench.
5. (Optional) Type a Description to provide information about the panel.
6. Add a token to replace the token in the panel search. See Example panel conversion and workbench panel creation in this topic or see Define tokens for multiselect inputs in the Splunk Enterprise Dashboards and Visualizations Manual.
   1. Select the type of artifact from the Type drop-down menu: Identity, Asset, File, or URL.
   2. Click Apply.
7. Click Save.
8. Click Save.

Then add the panel to a tab so that it is visible on the workbench.

Modify a workbench panel.

1. Select Configure > Content > Content Management.
2. From the Type filter, select Workbench Panel.
3. Click the name of the panel.
4. Edit something, such as a token.

Tokens are now displayed in summary view instead of list view. The summary view displays each token name, type of artifact, and a preview of the token text that is generated out of the artifacts and put into place to run the search.

When you click the pencil to edit a token in the summary view, it will slide open into edit mode. In the preview section at the bottom of the edit window, you can see how the token value changes as you edit the token parameters. This helps to simulate what you will see in the search under certain situations.

Create a tab for the investigation workbench

Create a tab to display information specific to a particular data type, use case, or something else.

1. Select Configure > Content > Content Management.
2. Select Create New Content > Workbench Tab.
3. Type a Tab Name. This name becomes part of the stanza name in es_investigations.conf and is used as the label if you do not specify a label.
4. (Optional) Type a Label to provide a user-facing name for the workbench tab.
5. In Workbench Panels, select the panels that you want to appear on this tab. The order in which you select the panels is the order in which they appear on this tab on the workbench.
6. (Optional) Select a workbench profile to associate with this tab. You can only associate a tab with one profile. Profiles allow analysts to load multiple tabs that relate to a use case on the workbench.
7. (Optional) Change the Load by default selection. Select True if you want this tab to load for all workbench investigations.
8. (Optional) Type a Description for the tab. This helps analysts determine what types of information and context they can gather using the panels on the tab.
9. Click Save.

Example panel conversion and workbench panel creation

Prerequisite

You must have the Splunk Add-on for Blue Coat ProxySG installed, and data from the add-on in your Splunk Enterprise Security deployment. You can download the Splunk Add-on for Blue Coat ProxySG from Splunkbase.

1. Clone a panel and modify the search to use an input token with the workbench.
   1. Select Settings > User Interface.
   2. Click Prebuilt panels.
   3. Click Edit > Clone for the actions_by_destination_ip for the Splunk_TA_bluecoat-proxysg.
   4. Type a Prebuilt panel ID. workbench_actions_by_dest_ip.
   5. Remove the title from the XML, unless you want two titles to appear on the workbench.
   6. Modify the query in the XML to include a token that limits the results to the investigated asset artifacts. sourcetype="bluecoat:proxysg:access*" $dest_token$ | iplocation dest | geostats count by action
   7. Decide whether to remove the <earliest> and <latest> time range for the panel. This time range takes precedence over the time range set on the workbench, so you likely want to remove it so that analysts can perform context-sensitive searches.
   8. Click Save.
2. Modify the permissions of the panel.
   1. Locate the panel that you just created, workbench_actions_by_dest_ip.
   2. Select Edit > Edit Permissions.
   3. For Display for, select All apps.
   4. Click Save.
3. Return to Splunk Enterprise Security and set up the panel to be used on the workbench.
   1. Select Configure > Content > Content Management.
   2. Select Create New Content > Workbench Panel.
   3. Select a Panel Name of workbench_actions_by_dest_ip.
   4. (Optional) Type a user-facing Label that appears on the workbench: Proxy Actions by Destination.
   5. (Optional) Type a user-facing description that appears on the workbench: Displays a map that graphs the actions by destination IP, when possible, specific to the investigated assets.
   6. Click Add a Token to add a token for the $dest_token$ from the search.
   7. Type a Token Name that corresponds to the token name. dest_token
   8. Type a Prefix of (.
   9. Type a Suffix of ).
   10. Type a Value Prefix of dest=".
   11. Type a Value Suffix of ".
   12. Unselect the check box for Is Null for the Delimiter and type OR in the text box. Include the spaces on either side of the OR.
   13. Leave the check box for Is Null for the Default field selected. If this check box is selected, the search runs only when an artifact of the relevant type is selected on the workbench. In this case, the search runs only if you are exploring assets on the workbench.
   14. Select a Type of Asset, because the destination is an asset, not an identity or file or URL.
   15. Click the Available Artifacts buttons to see what the token value will look like if there are 0, 1, or 2 artifacts. For an example of two assets:
       (dest="<Asset_Value_1>" OR dest="<Asset_Value_2>")
   16. Click Apply.
   17. Click Save.
       This panel now contains a search that would be constructed as follows for two assets investigated on the workbench:

       sourcetype="bluecoat:proxysg:access*" (dest="<investigated_asset_1>" OR dest="<investigated_asset_2>") | iplocation dest | geostats count by action

4. Add the new panel to a new tab.
   1. On Content Management, select Create New Content > Workbench Tab.
   2. Type a Tab Name of proxy_data. This name becomes the stanza name in es_investigations.conf and is used as the label if the label is not specified.
   3. (Optional) Type a Label of Proxy Data.
   4. In Workbench Panels, type and select the Proxy Actions by Destination IP panel.
   5. For Load by default, leave it as False. Select True if you want this tab to load for all workbench investigations.
   6. (Optional) Type a Description for the tab. Proxy data related to investigated assets and identities.
   7. Click Save.

Analysts can then open a workbench and add the new tab to start investigating proxy data in the workbench.

Create a workbench profile

You can use profiles on the workbench to associate several tabs together that all fit a specific use case. For example, a DDoS Investigation profile might include a Firewall data tab and a general Network data tab. An analyst can then add the DDoS Investigation profile to an investigation to add both of those tabs to the workbench, rather than having to individually add tabs that fit the investigation.

1. Select Configure > Content > Content Management.
2. Select Create New Content > Workbench Profile.
3. Type a Profile Name. This name becomes the stanza name in es_investigations.conf and is used as the label if the label is not specified.
4. (Optional) Type a Label to provide a user-facing name for the workbench profile.
5. (Optional) Type a Description for the profile. This helps analysts determine what types of information and context they can gather by adding the profile to their investigation.
6. Click Save.

After creating a profile, update the tabs with the profile that you created. For the DDoS investigation example, edit the Firewall data and Network data tabs and select the new DDoS Investigation profile.

Set up artifact extraction for investigation of notable events

You can define the fields that are automatically extracted as identities or assets on the workbench when a notable event is added to an investigation. By default, the same fields that are used for asset and identity correlation are the fields extracted from the notable events created by included correlation searches. You must add fields to be extracted for any custom correlation searches.

When artifacts are extracted, duplicates are not created if they already exist in the investigation. You will see a notification that "the following artifacts already exist and have not been added." The existing artifact is not linked against the new notable event that would have caused the duplicate artifact to be created. This does not prevent you from manually adding a duplicate artifact.

Type of investigation artifact	Fields extracted for investigation scope
Asset	dest, src, dvc, orig_host
Identity	src_user, user, src_user_id, src_user_role, user_id, user_role, vendor_account
File and URL	These correspond to the artifact creation flow on the investigation workbench. Instead of creating a file or URL artifact on the workbench by hand, you can specify which fields should be used to create artifacts automatically when you add a notable to the investigation workbench.

If your correlation search does not use data models, or the search results contain different fields that you want to extract, you can specify the fields to extract into the investigation scope.

1. Select Configure > Content > Content Management.
2. Click the correlation search that you want to customize to open it for editing.
3. Select the notable event adaptive response action.
4. For Asset Extraction, type a field name from the correlation search results that identifies an asset. Press Enter to add the field name.
5. For Identity Extraction, type a field name from the correlation search results that identifies an identity. Press Enter to add the field name.
6. Click Save.
7. For File Extraction, type a field name from the correlation search results that identifies a file. Press Enter to add the field name.
8. Click Save.
9. For URL Extraction, type a field name from the correlation search results that identifies a URL. Press Enter to add the field name.
10. Click Save.