Splunk v1.0.9 Installation

This article explains how to install and configure the TruSTAR integration with 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.

Article Overview / Contents:

• TruSTAR Terms: defines a few TruSTAR-specific terms used throughout this document.
• Splunk Terms: defines a few Splunk-specific terms used throughout this document.
• TruSTAR-Splunk Integration Components: describes/defines the 2 components that collectively make up the TruSTAR-Splunk integration.
• Hardware Requirements: outlines the hardware requirements for the Splunk instances on which you install the TruSTAR-Splunk integration components.
• Installation Options: helps you decide which of your Splunk instances you'll install each component of the TruSTAR-Splunk integration on.
• Before You Install: walks you through configuring the Station User Account that you will use with the TruSTAR TA for Splunk and the Splunk indexes to which TruSTAR data will be funneled.

TruSTAR Terms

• Station: The TruSTAR threat intelligence management SAAS platform.
• Station User: An individual human that uses the Station platform.
• Station User Account: An account on the Station platform assigned to one user.
• Enclaves: Data repositories in the Station platform. Each data source imported by Station resides in its own enclave. For more information on Enclaves, see "What is an enclave."
• Observable: Artifacts found on a network or operating system that indicate a likely intrusion. Typical observables are virus signatures, IP addresses, MD5 hashes of malware files, URLs, or domain names. 
• IOC: Indicator of Compromise. Another term for Observables.

Splunk Terms

• Heavy Forwarders: Heavy forwarders push data into Splunk Enterprise indexes or a third-party system. More info here.
• Indexers: Indexers house and organize the data sent from the heavy forwarder. More info here
• Search Heads: Search heads go through the data on indexers and return results. More info here

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 IOCs and reports from Station. The App monitors the indexes you specify for the presence of IOCs that the TruSTAR TA has copied from Station into the Splunk index you've chosen.
• Technology Add-on for TruSTAR (TA): The back-end component fetches reports and IOC data from selected enclaves in TruSTAR Station and indexes them for use with the Splunk search tool.

Hardware Requirements

Search Head: 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: The Heavy Forwarder on which the TA resides can be a fairly miniscule instance - TruSTAR runs these on AWS free-tier T2.Micro instances regularly.

Related Documents

• FAQ for Splunk Integration
• Release Notes for TruSTAR Splunk TA v1.0.9 and App v1.0.9

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.

Note: Please ignore the fact that this image instructs you to install both the TA and the App on search heads. That is incorrect. The TA should only be installed on a Heavy Forwarder.

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.

The data collection must take place on an on-premise Splunk Enterprise instance configured to function as a heavy forwarder. This heavy forwarder requires the TruSTAR TA.

Note: DO NOT INSTALL THE TRUSTAR "TA" ON A SPLUNKCLOUD INSTANCE. This configuration causes problems and TruSTAR will not provide technical support to customers who insist on installing the TA on a SplunkCloud instance.

Splunk Enterprise Security (ES)

TruSTAR App 1.0.9 does not have any special Splunk ES functionality. If you dig into its code, you will find some, but TruSTAR does not recommend it be activated or support its use. TruSTAR is in the process of developing an add-on that specifically integrates with Splunk's Enterprise Security add-on, and that should be released sometime in January 2020.

Before You Install

Before you install TruSTAR's "App" and "TA", you'll need to create a Station 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

• Create an email account specifically for your Splunk integration; for example: soc_trustar_splunk_integration@customercompany.com.
• Create a TruSTAR Station 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 Station user account “view” (read-only) access to the enclaves whose data you want to copy into the Splunk index that houses Station data.
  • ES users: Give this Station user account “submission” (write, but not delete) access to the enclaves you want it to send your Splunk ES Notable events to, if you have a separate enclave for them (contact your TruSTAR Account Executive for more information).
• 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.
• 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

• 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 enclaves in Station 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 IP addresses supporting traffic to Station are whitelisted in your firewall or proxy rules. The current list of IP addresses are listed near the bottom of this support page: https://support.trustar.co/article/n2h2ylhiqo-faq
• Check TruSTAR API limits.
• Splunk Enterprise Security Users only: Create a Notables enclave in TruSTAR.
  • Ask your account executive or account manager how to set this up.
  • After the Notables enclave is set up:
    • Add that enclave to the list of enclaves imported to Splunk.
    • Add access to that enclave to the Station user account.
    • Check that the Heavy Forwarder can view and search the Notables index.

Installing the TruSTAR Files

This section explains how to install the TruSTAR TA and App.

Splunk Cloud Installation

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

• Install the TruSTAR TA 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 TA 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 TA.

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 (TA):
  • Single: Install the TA on that instance.
  • Distributed: Install the TA on one Heavy Forwarder.
• TruSTAR App
  • Single: Install on to 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 - Splunk Integration file.
3. Install the Technology Add-on for TruSTAR file or the TruSTAR App for Splunk file, whichever is appropriate for the Splunk instance you’re logged in to.

Configuring the TruSTAR TA

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 TA Configuration Parameters below).

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

TA 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. You can find this Key in the TruSTAR Station web interface under Settings-> API. How to find 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. Available under Settings-> API on TruSTAR Station. How to find 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 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 station. Leave this parameter blank if you are using a CA signed certificate.
Enable Data Collection	Yes	Signals TA 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 secondary TA to import data from those enclaves into the same index as your primary heavy forwarder/TA, but using a different set of API credentials than your primary TA.  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 TAs on other heavy forwarders and configure each TA to import from a unique set of enclaves and time windows. Make sure that all of the TAs 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 the TruSTAR station, e.g. http://10.10.1.10 Note: If you are using a ZScaler proxy and have issues communicating with Station, contact TruSTAR support.
HTTPS Proxy Port	Optional	Proxy port to use for communication with the TruSTAR station e.g. 3128
HTTPS Proxy Username	Optional	Proxy username. Check with your system administrator or helpdesk for this information.
HTTPS Proxy Password	Optional	Proxy password. Check with your system administrator or helpdesk 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 Station user account access to only those open-source enclaves that you want to import into Splunk.   Best Practices Don't have the TA fetch any priority scores, as this will drastically increase the amount of time it takes to get indicators into your index.  Do not have the TA not import any data from Open Sources enclaves into your Splunk index. You can see the types of enclaves being accessed in the Web user interface where you view reports.  Ensure that the Station user account whose API credentials you are using in the Splunk rest input has read-only permission in Station to the enclaves you want to import to your Splunk index.
Interval	Optional	Polling interval in seconds. This is the amount of time (in seconds) that the TA will wait before polling the TruSTAR enclaves whose IDs you entered in the "Enclave IDs" box for new indicators or reports to import into Splunk. 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.