Splunk v1.0.9 Installation
- Article Overview / Contents:
- TruSTAR Terms
- Splunk Terms
- TruSTAR Components
- Hardware Requirements
- Related Documents
- Installation Options
- Before You Install
- Installing the TruSTAR Files
- Configuring the TruSTAR TA
- Configuring the TruSTAR App
- Configuring Splunk Enterprise Security
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.
- 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.
- 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
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.
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.
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.
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.
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: firstname.lastname@example.org.
- 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.
- 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 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 email@example.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:
- 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 - Splunk Integration file.
- 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
- 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 TA Configuration Parameters below).
- Click the Next button at the top of the screen after you have entered all configuration parameters into the form.
- Select Enable Data Collection to begin ingesting data from the TruSTAR enclaves specified in the Enclave IDs box.
TA 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. 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.
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)
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
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
Signals TA 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 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
Proxy port to use for communication with the TruSTAR station e.g. 3128
HTTPS Proxy Username
Proxy username. Check with your system administrator or helpdesk for this information.
HTTPS Proxy Password
Proxy password. Check with your system administrator or helpdesk 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 Station user account access to only those open-source enclaves that you want to import into Splunk.
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.
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