Install: TruSTAR for Splunk v1.0.9
- TruSTAR Components
- Hardware Requirements
- Installation Options
- Before You Install
- Installing the TruSTAR Files
- Configuring the TruSTAR Add-On
- Configuring the TruSTAR App
- Configuring Splunk Enterprise Security
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, depending on complexity of your Splunk environment and whether it is standalone distributed environment.
- FAQ: TruSTAR for Splunk
- For Splunk ES users: TruSTAR Workflow App for Splunk Enterprise Security
- Improved Submission Options: Ingest not only TruSTAR Intel Reports but also Indicator lists using bulk uploading.
- Splunk App Dashboard Update: Offers a streamlined experience, making relevant information more visible, including the source Enclave for Indicators.
- Optimized Queries: Increased efficiency in data ingestion and optimization of Splunk queries.
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.
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
This section explains the three options for using the Splunk integration.
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.
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.
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.
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.
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.
Before You Install
Before you install TruSTAR App" and TA, you need to create two things:
- A TruSTAR Web App user account for use with your TA
- The Splunk indexes that the TruSTAR App will use to push data into
Setting Up Accounts
- Create an email account specifically for your Splunk integration; for example: email@example.com.
- 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.
- 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.
- Create two new indexes for your TruSTAR integration:
- Single Instance: Create the two indexes on your instance.
- 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.
- 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 firstname.lastname@example.org 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:
- Select Apps -> Manage Apps from the main menu bar.
- Choose how to reach the TruSTAR files:
- Click the Browse More Apps button to install from Splunkbase. This ensures you have the latest versions of the TruSTAR TA and App.
- 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.
- Install the TruSTAR App or Add-on, whichever is appropriate for the Splunk instance you’re logged in to.
Configuring the TruSTAR Add-On
- Login to the Splunk node with a user account that has the admin role assigned to it.
- Go to Settings -> Data -> Data Inputs to display the Inputs page
- Select TruSTAR Configuration in the Local Inputs section.
- Fill in the configuration details (see Add-On Configuration Parameters below).
- Click Next at the top of the screen after you have entered all configuration parameters into the form.
- Select Enable Data Collection to begin importing data from the TruSTAR Enclaves specified in the Enclave IDs box.
Add-On Configuration Parameters
Rest Input Name
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
The TruSTAR station URL from which data is collected by executing API calls. Set this parameter to https://station.trustar.co
API Authentication Key
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.
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)
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
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
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.
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:
HTTPS Proxy Address
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
Proxy port to use for communication with TruSTAR, e.g. 3128
HTTPS Proxy Username
Proxy username. Check with your system administrator for this information.
HTTPS Proxy Password
Proxy password. Check with your system administrator for this information.
Enclave types for fetching Priority Score
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.
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.
Standard Splunk field. Options are AUTOMATIC (default) or MANUAL.
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:
- Open the Splunk UI on the the Splunk Search Head.
- Go to Settings-> Advanced search-> Search macros.
- Select TruStar App for Splunk in App Context dropdown.
- 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.
You can configure the attributes for Matching the events like:
- Index : Index to consider to matching the TruStar events.
- 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.
- 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.
trustar_get_match_reports (Correlation Search)
Enable this to generate notable events from matched events. By default, it is disabled.
To access this parameter
Adaptive Response (AR) Actions
Need default, etc (see comment)
trustar_ioc_report.py (Match Report)
Need setting and description