Install: TruSTAR for Splunk v1.0.9

This article explains how to install and configure the TruSTAR Workflow App and Add-On for Splunk. The integration typically takes anywhere from 20 - 60 mins; this depends on the Splunk environment and whether it is a standalone or distributed environment.

Related Documents

• FAQ: TruSTAR for Splunk

For Splunk ES users: TruSTAR Workflow App for Splunk Enterprise Security

TruSTAR Components

The integration consists of two components installed into your Splunk environment:

• TruSTAR App for Splunk (App): This is the user interface component for the TruSTAR integration. It is composed an overview dashboard and tables that display Intel Reports and Indicators from TruSTAR. The App monitors Splunk indexes for the presence of Indicators that TruSTAR has copied over from TruSTAR Enclaves.
• Technology Add-on for TruSTAR (Add-On): The back-end component fetches Intel Reports and Indicators from selected TruSTAR Enclaves and indexes them for use with the Splunk search tool.

Hardware Requirements

Search Head

Search heads go through the data on indexers and return results. More info here

The search-head on which TruSTAR's "App" resides must be robust. Splunk is a compute-resource-intensive application, and the types of searches TruSTAR's App performs are no exception to that rule. The search head should have at least 8 cores and 16 GB of RAM, and harddrive space equivalent to ~2xthe quantity of data (measured in disk size consumption - MB, GB, etc) that you need the app to hunt through. The amount of harddrive required is related to the amount of log data you make the App hunt through every day; if you need the app to hunt for malicious IOCs in all logs added to 10 indexes over the last 24 hours, and ~100GB of data is added to each index every day, then your search head will need to have at least 2TB of harddrive available for the app to perform its search operations. If you want it to be able to hunt through the last 96 hours of log data in the same scenario, the search head would need 8TB of harddrive space available.

Heavy Forwarder and Indexer

Heavy forwarders push data into Splunk Enterprise indexes or a third-party system. More info here.

The Heavy Forwarder on which the TA resides can be a fairly small instance. For example, TruSTAR often runs these on AWS free-tier T2.Micro instances.

Indexers house and organize the data sent from the heavy forwarder. More info here

Installation Options

This section explains the three options for using the Splunk integration.

Single Instance

In a self-managed, single-server Splunk deployment, a single instance of Splunk Enterprise serves as the search head, indexer, and data-collection node. You will install both the TruSTAR TA and App onto this instance. For sizing information, see the "Hardware Requirements" section above.

Distributed

In a distributed Splunk deployment, Splunk Enterprise consists of these components:

• Heavy Forwarder: Requires the TruSTAR TA
• Search Head: Requires the TruSTAR App.
• Multiple Search Heads:
  • Clustered search heads: TruSTAR App only needs to be installed on one search head; the cluster master / captain should replicate it to all the other search heads in the cluster.
  • Parallel search heads behind a load-balancer: You'll likely need to install the App on all the search heads, especially if you can't reach a single specific search head by its IP address.
  • Multiple search heads, not behind a load-balancer and not clustered: You can install the App on whichever search heads you like, but you will have to contact that search head by its URL and login to that specific search head to use the TruSTAR App.

Best Practices

Before proceeding with the installation, map out your Splunk architecture and decide where the TruSTAR apps will be installed. You can use this as a checklist during installation to ensure that all apps are installed in the required Splunk locations.

Splunk Cloud

In a managed Splunk Cloud deployment, the cloud instance functions as the search head and indexer, so the TruSTAR App must be installed on this instance. While a Splunk Cloud deployment appears to the user to be a single computer, they usually consist of several computers in a cluster configuration. When you install the App on a Splunk Cloud instance, it takes the cluster a while to replicate the app to all members of the cluster. Every time you change the app's configs on one member of the cluster, it takes the same while for the cluster to replicate those config changes to the other members of the cluster.

For data collection TruSTAR recommends that this activity, done by the TruSTAR TA, be handled by a self-managed, on-premise Splunk Enterprise instance configured as a heavy forwarder. If you want to perform data collection in the cloud, you must install the TruSTAR TA on a Splunk Cloud instance that is configured as an Inputs Data Manager (IDM). You will need to work with Splunk to set up this IDM before installing the TruSTAR TA.

Best Practices

Splunk recommends that cloud-based add-ons should be installed on an IDM and on-premise-based add-ons should be installed on a forwarder or heavy forwarder. For this reason, TruSTAR recommends using an on-premise heavy forwarder as the preferred installation point for the TruSTAR TA.

Splunk Enterprise Security (ES)

TruSTAR App 1.0.9 does not have any special Splunk ES functionality.

Before You Install

Before you install TruSTAR App" and TA, you'll need to create a TruSTAR Web App user account for use with your TA, and you need to create the Splunk indexes that your TruSTAR-Splunk integration components will push data into. This section helps walk you through that process.

Setting Up Accounts

1. Create an email account specifically for your Splunk integration; for example: soc_trustar_splunk_integration@customercompany.com.
2. Create a TruSTAR Web App user account tied to that Splunk integration email address. You will need access to that email account so you can open the account verification email Station will send to it. Your Splunk instance will use this Station account’s API credentials. Give this user account view (read-only) access to the Enclaves whose data you want to copy into the Splunk index that houses Station data.
3. Check that your Splunk user account has read/write permissions to the $SPLUNK_HOME directory and all its subdirectories. You will need this to install the TruStar TA and App on the search heads and Heavy Forwarder.
4. Ensure that you login to the Splunk web user interface with a Splunk user account that has the admin role assigned to it.

Configuring Splunk

1. Create two new indexes for your TruSTAR integration:

• Single Instance: Create the two indexes on your instance.
• Distributed:
  • Clustered indexers: On the cluster master, edit the "indexes.conf" file at "$SPLUNK_HOME/etc/master-apps/_cluster/local/indexes.conf". For more information, check this Splunk support document.
  • Parallel indexers: Log in to each indexer and create the indexes.
• Cloud: Create the indexes on the managed cloud instance.

Best Practices

• TruSTAR recommends naming the first index trustar. This is where you will index the indicators and reports that the TA will import from Station.
• TruSTAR recommends naming the second index trustar_app_ta_logs. This one will index logs generated by the TruSTAR App and TA to be used as needed in any troubleshooting efforts.
• TruSTAR recommends setting the Max Size of Entire Index to 5GB for both indexes.

  

• Identify which TruSTAR Enclaves you want to copy into the new trustar index.
• Check that the Heavy Forwarder can view and write to the trustar index.
• Check that the Heavy Forwarder can reach https://station.trustar.co by opening a terminal window and pinging that location. Your firewall or proxy rules may need to be modified to support this connection.
• Check that the search head(s) can see the TruSTAR data index, lookups, and the indexes that you want the TruSTAR App to monitor.
• Check that the URL station.trustar.co. is not blocked by your firewall or proxy rules.
• Check your TruSTAR API limits.

Installing the TruSTAR Files

This section explains how to install the TruSTAR Add-On and App.

Splunk Cloud Installation

If you have SplunkCloud, contact support@splunk.com to ask them to

• Install the TruSTAR Add-On and App on your SplunkCloud instance.
• Create a directory-monitor input for the directory $SPLUNK_HOME/var/log/trustar/ and index all logs in that directory into the trustar_app_ta_logs index

If you are using an on-premises Heavy Forwarder, you can install the TruStar Add-On app on that instance. In this case, TruSTAR recommends also configuring a Directory Monitor input that monitors the $SPLUNK_HOME/var/log/trustar/ directory and imports those logs into the trustar_app_ta_logs index.

After the files have been installed, you can configure the TruSTAR Add-On.

Splunk Enterprise Installation

Enterprise installation requires the installation of both TruSTAR files; the location depends on whether your Splunk Enterprise installation is a single instance or is distributed.

• TruSTAR Technology Add-On (Add-On):
  • Single: Install it on that instance.
  • Distributed: Install it on one Heavy Forwarder.
• TruSTAR App
  • Single: Install it the instance.
  • Distributed: Install on all search heads where you will be using the TruSTAR integration.
    • With deployment server : Use this link to install and configure the App on the cluster’s deployer instance and then use this link to push the App and configuration to the rest of the cluster.
    • Without a deployment server: Install and configure the App on the search head(s) you want to use the TruSTAR App on. Bear in mind that the TruSTAR App will be configured manually on each search head it was installed on.

Install the TruSTAR files using the user interface:

1. Select Apps -> Manage Apps from the main menu bar.
2. Choose how to reach the TruSTAR files:
   1. Click the Browse More Apps button to install from Splunkbase. This ensures you have the latest versions of the TruSTAR TA and App.

      

   2. If you cannot connect to Splunkbase (for example, in an air-gapped environment), click the Install app from file button. You will need to first download the files from another computer and then transfer them onto the instance(s) where the installation will be done. For more information on air-gapped installation, see the FAQ: TruSTAR for Splunk support document.
3. Install the TruSTAR App or Add-on, whichever is appropriate for the Splunk instance you’re logged in to.

Configuring the TruSTAR Add-On

1. Login to the Splunk node with a user account that has the admin role assigned to it.
2. Go to Settings -> Data -> Data Inputs to display the Inputs page
3. Select TruSTAR Configuration in the Local Inputs section.
4. Fill in the configuration details (see Add-On Configuration Parameters below).

1. Click Next at the top of the screen after you have entered all configuration parameters into the form.
2. Select Enable Data Collection to begin importing data from the TruSTAR Enclaves specified in the Enclave IDs box.

Add-On Configuration Parameters

Parameter	Required	Description
Rest Input Name	Yes	The name of rest modular input. Each Modular Input name must be unique and use alphanumeric characters only; you cannot use special characters.  Name it "trustar001" - If you need to delete this REST input and create a new one in future, you will need to use a new name (Ex:  "trustar002").
URL to Connect	Yes	The TruSTAR station URL from which data is collected by executing API calls. Set this parameter to https://station.trustar.co
API Authentication Key	Yes	Used to make API calls. Finding your API Key The Key is in clear text at the time of new modular input creation. On save of Modular input, the Key is encrypted and stored at the /storage/password entity of Splunk.
API Secret	Yes	Used when making API calls. Finding your API Secret The Secret in clear text at the time of new modular input creation. On save of Modular input, Secret key is encrypted and stored at the /storage/password entity of Splunk.
Date (UTC in "YYYY-MM-DD hh:mm:ss" format)	Optional	Submission date/timestamp for the oldest Inte Report you want to import into Splunk.  The default (blank) will import data from all Enclaves you specify for the past 90 days.
SSL Certificate Path	Optional	Path of SSL Certificate that will be used while executing any API request to TruSTAR. Leave this parameter blank if you are using a CA signed certificate.
Enable Data Collection	Yes	Signals the Add-On to begin importing data from the TruSTAR Enclaves specified in the Enclave IDs field as soon as the configuration changes are saved.
Enclave IDs	Yes	The Enclave(s) to import data from. Specify the Enclave ID (alphanumeric id next to enclave name in TruSTAR Station). To import data from multiple Enclaves, separate each enclave ID with a comma and no spaces: Retrieving your Enclave IDs Best Practices Avoid importing from more Enclaves than you need to as each one takes time to process. To import data from Enclaves whose data quality/reliability is unknown, consider setting up the TruSTAR TA on an a different Splunk Heavy Forwarder and use a secondary Add-On to import data from those Enclaves into the same index as your primary heavy forwarder, but using a different set of API credentials than your primary Add-On.  TruSTAR limits the number of API calls a set of API credentials can make each minute. If you need to reach further back in time for certain Enclaves, set up additional Add-Ons on other heavy forwarders and configure each Add-On to import from a unique set of Enclaves and time periods. Make sure that all of the Add-Ons import the data into the same index so the TruSTAR App can view and search all the data.
HTTPS Proxy Address	Optional	Proxy address to use for communication with TruSTAR, e.g. http://10.10.1.10 Note: If you are using a ZScaler proxy and have issues communicating with TruSTAR, contact TruSTAR support.
HTTPS Proxy Port	Optional	Proxy port to use for communication with TruSTAR, e.g. 3128
HTTPS Proxy Username	Optional	Proxy username. Check with your system administrator for this information.
HTTPS Proxy Password	Optional	Proxy password. Check with your system administrator for this information.
Enclave types for fetching Priority Score	Optional	Type of Enclaves being accessed. Values are INTERNAL (default), OPEN, CLOSED, or blank.   If you specify multiple types, use commas to separate the values (no spaces are allowed). Note: On-premises installations should leave this field blank. If you cannot save the configuration settings with this field left blank, set the value to OPEN and restrict the TruSTAR Web App user account access to only those Enclaves that you want to import into Splunk.   Best Practices Don't have the Add-On fetch priority scores, as this will significantly increase the amount of time it takes to import Indicators into the Splunk index.  Do not have the Add-On import data from Open Source Enclaves into your Splunk index. Display Enclave Types Ensure that the TruSTAR Web App user account whose API credentials you are using in the Splunk REST input has read-only permission in TruSTAR to the Enclaves you want to import.
Interval	Optional	Polling interval in seconds. This is the amount of time (in seconds) that the Add-On will wait before polling the TruSTAR Enclaves whose IDs you entered in the "Enclave IDs" box. Best Practices Set the value to 86400 (once/day) initially. After it has completed the initial download, you can lower the interval to 3600 (once/hr).  Avoid importing data from TruSTAR far back in time. The further back in time you go, the longer the import process takes before the indicators actually post to your index).
Set sourcetype	Optional	Standard Splunk field. Options are AUTOMATIC (default) or MANUAL.
Index	Optional	The index to be used for TruSTAR data. You should see the trustar index in the drop-down menu. If you do not, the Heavy Forwarder may not be correctly configured (see the FAQ - Splunk Integration file), or it may not be communicating properly with your indexers/indexer cluster.   You must also change the macro definition. See the Changing Macro Definition instructions below.

Changing the Macro Definition

After configuring the parameters, follow these steps to ensure the destination index is correctly specified:

1. Open the Splunk UI on the the Splunk Search Head.
2. Go to Settings-> Advanced search-> Search macros.
3. Select TruStar App for Splunk in App Context dropdown.
4. Modify the trustar_get_index macro definition with index=trustar.

   

Configuring the TruSTAR App

Have this information ready:

• Which Splunk indexes contain which types of IOCs.
• Which indexes the TruSTAR App will monitor and for which types of IOCs.
• Which Station enclaves to corroborate against the indexes.

Configuration Parameters

You can configure the attributes for Matching the events like:

1. Index : Index to consider to matching the TruStar events.
2. Timerange (in days) : Time range for the data to be matched. For example, if you want to use the last two day, set the value to 2.
3. Enclaves: Enclaves to consider for matching against TruStar events. Submit Enclaves Configuration:Enclaves to which the TruStar submission should happen while using AR and workflow action.

   

Configuring Splunk Enterprise Security

The TruSTAR TA contains parameters specifically for the Splunk Enterprise Security component. To enable these parameters, use the table below.

In addition, ensure that the Heavy Forwarder can view and search data in the Notables index.