Install (TS Unif)

Updated 1 month ago by TruSTAR

Overview

Purpose.

This article explains how to install and configure the TruSTAR Unified Workflow App for Splunk Enterprise and Enterprise Security (ES). Installing typically takes anywhere from 15-30 minutes, depending on your Splunk environment and the number of TruSTAR Enclaves you specify during configuration.

TruSTAR Docs

Splunk Docs

Splunk Dev Docs

Splunk API Docs

Requirements - Splunk deployment.

Software

  • Splunk Enterprise version 8.0 or higher
    • Splunk 7+ is supported up to TruSTAR Unified 2.0.3
    • TruSTAR Unified 2.0.4 deprecates interoperability with Splunk 7 and Python 2.
  • Optional: Splunk Enterprise Security version 6.0 or higher.

Log Data

  • CIM-compliant logs from relevant sources (ex: Proxy, Firewall, Antivirus, SSH logs, etc.)

User Accounts

You must have two Splunk user accounts on each search head:

  • admin required for installation
  • power recommended for Splunk Enterprise users
  • ess_admin (or greater) required for Splunk ES users
    • Must have the "modify_notable_event" permission to be able to manually run the "Enrich" adaptive response action.

For more information, see Check Splunk User Account Permissions in the FAQ.

Networking

  • Modinput & Modaction Code is started & executed by the Splunk application on search-heads.
  • The TruSTAR Unified app running on the search head will need to be able to make REST API calls to the search-head's Splunk application on localhost, port 8089.
  • The search heads' Splunk application daemon must accept incoming traffic on port 8089, from "localhost" / loopback.
  • Modinput & modactions all make HTTP REST API calls to TruSTAR's API. Search-head will need to be able to call to TruSTAR (https://api.trustar.co) through port 443 using TLS 1.2.

Logs-to-CIM Mapping

For Splunk ES to generate notable events when it finds a TruSTAR Indicator in logs, those logs must be mapped to the Splunk Common Information Model. Splunk Professional Services can assist with this process. For more information see the Splunk ES CIM Overview.

Special Requirements.

SplunkCloud users

  • SplunkCloud has a policy that modinputs not be allowed to run on search heads.
  • This app has been granted an exception to the policy, but SplunkCloud personnel who install this app for customers often are not aware of that exception.
  • Notify TruSTAR TAM and send a support request to support@trustar.co if you encounter this.
  • Technical details regarding why this app must run on search heads (not heavy forwarders / IDMS) are explained on the app's Splunkbase page

Distributed Splunk Deployments

  • Many Splunk ES knowledge objects reside on search-heads only.
  • Correlation, threat-gen, and lookup-gen searches must process entirely on search-heads and cannot be distributed to an indexer or indexer cluster.
  • This app's modinput is intended to run on the search head, and will add cyber threat observables to kvstores on that searchhead.
  • Most likely, any searches you write that use the observables added to the kvstores by this app will need to process entirely on the searchhead.

For assistance, please contact Splunk Professional Services.

Related Link: Splunk Distributed Search documentation.

Search-head Clusters

Lots. see next table.

Search-Head Clusters:

Concept

Description

Related Links

Config File Replication

  • The TruSTAR Unified App ships with a custom server.conf file that should enable your cluster to replicate the necessary config files to all nodes in the cluster.
  • In some cases, your Splunk Administrator may need to manually copy its (server.conf) contents to a different server.conf file.

KV Store Replication

  • Downloading observables from TruSTAR to search-head can occur only on the cluster Captain node.
  • The SHC must be configured to replicate observables added to the Captain's kvstores to all nodes in the cluster.
  • Cluster Captain should also be the KV Store Captain.

Sticky Sessions

  • If a user's interaction with your search heads passes through a proxy or load balancer, you must enable sticky sessions. This is a Splunk requirement and ensures a consistent user experience.

passwords.conf files

  • Do not copy passwords.conf files from one Splunk host to another.
  • TruSTAR Unified does not ship with one, but other apps do.

Deployer

  • you should be able to use your deployer to distribute the TruSTAR app to SHC nodes.
  • ** caution: any Splunk app built using the Splunk Addon Builder will fail if your deployer distributes a "passwords.conf" file to the SHC nodes.
  • Do not configure the TruSTAR app on your deployer node and push the configs to the SHC nodes - you'll encounter the passwords.conf problem.

Requirements - Prepare TruSTAR account.

Steps:

Step number.

Task.

References.

Subscribe to intel sources.

Create Splunk Threat Activity enclave.

n/a - TruSTAR TAM will do this.

Create Prioritized Indicator Intel Workflows.

  • must be done before can configure the app
    • the intel workflow's service user API creds are required for first step in app config.

Enclaves.

  • Enclaves are TruSTAR's intelligence data storage facility.
  • This table tells you what enclaves this app will interact with, the enclave's purpose, and how that enclave gets created.

Enclave

Purpose

How Create?

Splunk Threat Activity

  • Submit ARA will send all events / notable events that match your threatintel-related correlation searches to this enclave for historical archiving, which enables TruSTAR to enrich the observables in that event.

TruSTAR Account Manager will create for you.

Workflow destination enclaves

  • Ideally each modinput will connect to and download from a single workflow destination enclave only.

Create Prioritized Indicator Intel Workflows.

Intel Source Enclaves

  • Prioritized Indicator Intel Workflows select subsets of indicators from your intel source enclaves and deposit them in Workflow Destination Enclaves.

Subscribe to intel sources.

Sharing Group Enclaves

  • share splunk events / alerts / notable events with sharing group using Submit ARA.

TruSTAR Account Manager will permission you to these enclaves.

Prioritized Indicator Intel Workflows.

  • This App is designed to work together with TruSTAR Intel Workflows that specify Splunk or Splunk Enterprise Security as a destination for the workflow.
  • You will have to create at least one intel workflow before configuring this app, because the intel workflow creation also creates a set of service user credentials needed early in the config process.

Requirements - Upgrading from "TruSTAR App for ES" to "TruSTAR Unified".

De-configure Adaptive Response Actions.

  • TruSTAR Unified has the same Adaptive Response Actions that the TruSTAR App for ES did.
  • all correlation searches configured to use TruSTAR App for ES's ARAs will need those configs removed.
    • To find those searches, run this SPL search:
      | rest splunk_server=local count=0 /servicesNS/-/SplunkEnterpriseSecuritySuite/saved/searches

      | where match('action.correlationsearch.enabled', "1|[Tt]|[Tt][Rr][Uu][Ee]")

      | table title actions

      | where match('actions', "trustar")

Note your modinput configs.

  • you will have to re-configure them.

Delete TruSTAR App for ES entirely.

Ref: Manage app and add-on knowledge objects

Follow instructions in section "Installing TruSTAR Unified" to install the TruSTAR Unified app and reconfigure the adaptive response actions.

Installing TruSTAR Unified.

The TruSTAR App must be installed on search-heads. Do not install the App on indexers or heavy-forwarders.
  1. Select Apps -> Manage Apps from the Splunk main menu bar.
  2. Click the Browse More Apps button, then use the Search box to find the TruSTAR Unifed App.
    SplunkES_Install_Figure4
  3. Proceed with the installation of the TruSTAR App.

Configuring TruSTAR Unified.

The Configuration Options is where you enter API credentials and set up proxy server, logging, and other details for the TruSTAR App. You can also configure automatic submission of Notable Events to TruSTAR (Splunk ES only).

  1. Choose TruSTAR Unified App from the App pull-down menu on the top-level Splunk menu.
  2. Click Configuration on the blue submenu.

Account Settings.

The Account Settings tab sets up the API credentials for the integration.

  1. Add 3 accounts.
    1. Account names (verbatim, all caps):
      1. DOWNLOAD
      2. ENRICH
      3. SUBMIT
    2. API Key + Secret:
      1. all 3 accounts should use the service account API key + secret from one of the user's Indicator Prioritization Intel Workflows. (should have created at least 1 intel workflow in previous section "Requirements - Prepare TruSTAR Account" whose "destination" is Splunk or Splunk Enterprise Security.)

Proxy Settings.

If your installation uses a proxy between search head(s) and the TruSTAR platform, you need to configure the proxy information as shown below.

SplunkES_Install_Figure8

Logging.

You can choose one of five logging levels: Debug, Info, Warning, Error, and Critical.

TruSTAR recommends leaving the level at Info (the default) unless instructed by TruSTAR Support.

Add-On Settings.

The Add-on Settings specify which Enclaves to use for submissions and for enrichment.

Explanation of Settings

  • Default Submit Enclave: The Enclave ID for Splunk Threat Activity.
  • Default Enrich Enclaves: The Enclaves to use when enriching events.
    • TruSTAR recommends: ALL
    • Alternatively, you can enter a comma-separated list of Enclave IDs.
You can override the default Enclave settings when running individual enrichment or submission actions.

Configure Notable Event Auto-Submission.

You can configure the TruSTAR App to automatically submit Notable Events. You can manually submit events, using the procedure described in the User Guide for the App.

This feature is only available with Splunk ES.
  1. Choose Enterprise Security from the App pull-down menu on the top-level Splunk menu.
  2. Click the Configure menu, then click the Content menu, and then click Content Management.
    SplunkES_Install_Figure15
  3. Search for "threat activity detected" and then click the correlation search named Threat Activity Detected. This opens a configuration window for that search.
    SplunkES_Install_Figure17
  4. In the configuration window, scroll to the Adaptive Response Actions section, then click the carat next to Notable.
    SplunkES_Install_Figure19
  5. In the Next Steps text box, add these lines, separated by 2 newline characters:
[[action|trustar_submit_event]]


[[action|trustar_enrich_threat_activity]]
  1. In the Recommended Actions section, select TruSTAR - Enrichment and TruSTAR - Submit. The configuration should now look like this example:
    SplunkES_Install_Figure20
  2. Go back to the Adaptive Response Actions section and choose Add New Response Action, then select the TruSTAR - Submit action.
  3. Configure the Submit action by adding a Report Title and any comments you want to add to the event. The configuration should now look like this:
    SplunkES_Install_Figure22
  4. Click the green Save button in the lower right corner to complete the configuration.

Configuring Notable Event Auto-Enrichment. (ES only).

  1. Choose Enterprise Security from the App pull-down menu on the top-level Splunk menu.
  2. Click Settings, then click Searches, reports, and alerts.
  3. Click New Alert.
  4. In the Create Alert window, use these settings:

Setting

Value

Title

TruSTAR Enrichment

Search

`notable` | search rule_title="*Threat Activity Detected*"

Permissions

Shared in App

Alert Type

Scheduled (recommend every 4 hours)

Trigger Alert When

  • Number of Results
  • is greater than
  • zero

Trigger

For each result

  • Scroll to the Adaptive Response Actions section and click +Add Actions.
  1. In the list, select TruSTAR - Enrichment.
  2. Optionally, you can click the Custom Radio button and enter a Custom Enclave ID to send the results to a different Enclave than your default Enclave. You can also enable or disable the Urgency Adjustment for the search.
  3. Click Save in the bottom right corner to save the correlation search.

Configuring Inputs.

  • Inputs download observables from TruSTAR to Splunk KV Stores for use in detection.
  • These instructions show how to create a single input.
  • For ideas on what inputs to create, see User Guide: Download Observables to Splunk

Creating an Input

  1. Choose TruSTAR Unified from the App pull-down menu on the top-level Splunk menu.
  2. Click Inputs on the blue submenu.
  3. Click Create New Input to start defining an input source.
  4. Fill out the configuration options as shown in this table.

Field

Value

Notes

Name

Name of the input

A unique input name. Valid characters are letters and underscores only. You cannot use spaces or special characters.

Destination KV Store Group

TruSTAR

or

Splunk ES Threatintel

Tells the app which KV Stores to copy observables to.

Global Account

DOWNLOAD

The account you created during the installation process.

Enclave IDs

Workflow Enclaves to download from

You must enter the Workflow Enclave ID. TruSTAR recommends configuring one mod input per Workflow. To specify multiple Enclave IDs, separate them with commas and no spaces. Finding Enclave IDs

IOC Types

Indicator Types

If you used Workflow Enclave ID, this is not needed because this filtering is configured during the creation of the Workflow.

The Indicator types you want to download from TruSTAR. The default is to include all Indicators supported by Splunk (Email Address, IP, MD5, SHA1, SHA256, Software, Registry Key, URL).

Click x on an Indicator to remove it.

Tags

List of Indicator tags

This list is used to filter Indicators when downloading from TruSTAR. Lowercase characters only.

The input will only download Indicators that match all other criteria (Enclaves, IOC types, etc.) AND include ALL the tags in the list.

Expiration

Number of days

When an Indicator has not been mentioned in any of the Enclaves this input downloads from in the specified number of days, that Indicator will no longer be detected on.

  1. Click Add to save these settings and create the input.


How Did We Do?