Splunk v1.0.9 Installation
- TruSTAR Terms
- Splunk Terms
- TruSTAR Components
- Related Documents
- Installation Options
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.
- 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.
A self-managed, single server Splunk deployment requires at a mininum 8 cores and 16 GB RAM. For example, you can use a single EC2 instance (size C5N.2XL as of May 2019) in Amazon Web Services (AWS).
This section explains the three options for using the Splunk integration.
Single Instance Splunk Enterprise
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 FAQ - Splunk Integration file.
Distributed Splunk Enterprise
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: If you are using multiple search heads, you can arrange them as a cluster or as multiple parallel search heads.
- Clustered search heads only require one search head to have the TruSTAR App installed; the installation and configuration from that one search head populates to the rest of the cluster.
- Parallel search heads require you to install and configure the TruSTAR App on each separate search head.
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.
The data collection can take place on an on-premise Splunk Enterprise instance used as a heavy forwarder. This heavy forwarder requires the TruSTAR TA.
TruSTAR recommends using a separate instance for the Heavy Forwarder. If you don’t have one and don’t want to create one just for TruStar, you can install the TruSTAR TA on your cloud instance. If you do this, TruSTAR recommends also asking SplunkCloud to configure a Directory Monitor input that monitors the $SPLUNK_HOME/var/log/trustar/ directory and imports those logs into an index of your choice.
Splunk Enterprise Security (ES)
If you have purchased Splunk Enterprise Security as an add-on to Splunk Enterprise or SplunkCloud, you do not need to install any additional components. You will need to configure the ES component after you finish configuring the TruStar TA and App components.
Before You Install
To ensure a successful installation, work through the items in this section before beginning the installation.
Setting Up Accounts
- Create an email account specifically for your Splunk integration; for example: email@example.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.
- 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 for each search head.
- 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 2GB.
- 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 firstname.lastname@example.org 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
Follow these instructions for the TruSTAR TA you installed.
- 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