Install: TruSTAR for Resilient

Updated 2 weeks ago by Elvis Hovor

This document explains how to install and configure the TruSTAR Workflow App for IBM Resilient.

This app enables you to access TruSTAR Intel Reports and Indicators and incidents within the Resilient workflow. You can automatically send Resilient incidents as TruSTAR Intel Reports, enriching them with correlated intelligence from TruSTAR. The app can automatically update the TruSTar Intel Report when the Resilient incident is updated.

You can use the TruSTAR Workflow App to:

  • Speed incident investigations: TruSTARs Integration with Resilient improves incident response time by ingesting correlated intelligence from TruSTAR into Resilient tickets in near real-time.
  • Identify high priority indicators: Identify indicators that have a high risk score in TruSTAR, providing a quick visual prioritization of indicators.
  • Automate Workflows: TruSTAR's workflows automate incident enrichment and threat intelligence gathering, accelerating your incident triage for faster and more complete responses to emerging threats.
The installation and configuration of this Workflow App is a complicated process and may take up to two hours to complete. TruSTAR recommends that installation be done by an experienced Resilient engineer.

Installation Options

You can choose to install the TruSTAR Workflow App on a Resilient appliance or on a separate integration server.

If you choose to use a separate integration server, you must install Python version 2.7.10 or later, or version 3.6 or later, and “pip”. (The Resilient appliance is preconfigured with a suitable version of Python.)

Requirements

Administrator

The installation process assumes that you are a Resilient Server administrator who is familiar with these concepts:

  • SSH / PuTTY to remotely connect to hosts.
  • "scp" to copy files from your computer to the Resilient host.
  • navigate the command-line.
  • create Linux user accounts at the command-line.
  • edit config files using a command-line text editor such as Vim, Vi, Nano, or Emacs.
  • Python and its package-manager Pip.
  • Install Python packages from both the PyPi service and a local directory using "pip".
  • Familiar with the Resilient application and knows their way around its web u/i.

Infrastructure

  • Follow IBM's compute-resource requirements for the Resilient appliance.
  • The Integrations Server can be a fairly small machine. 2 cores, 4GB RAM, 20GB harddrive should be plenty.
  • Resilient appliance needs to accept incoming traffic on:
    • HTTPS requests incoming on port 443.
    • HTTP on port 80.
    • STOMP on port 65001.
  • Integrations appliance needs to accept incoming traffic on:
    • HTTP/HTTPS requests on port 9000. This port number can be changed in the [webserver] stanza of the app.config file created later in this process.

Software

  • IBM Resilient version 30 to 33.
  • IBM Resilient Circuits. This can be a local installation on the Resilient appliance or installed on a separate integration server.
  • Python version 2.7.10 or higher, or version 3.6 or higher (only when using a separate integration server)
  • The TruSTAR App for IBM Resilient. You can download this tar file from the IBM X-Force Exchange. The file contains the following packages:
    • trustar_cts
    • trustar_resilient_action_module
    • util
    • setup.py
  • Additionally, it will automatically install these Python libraries if they're not already present in your python environment:
    • resilient_circuits
    • trustar
    • circuits
What is Resilient Circuits?
Resilient Circuits is an application that passes messages between a Resilient server and Resilient integrations/extensions such as the TruSTAR integration you're installing now. It reads messages that the Resilient application publishes to a STOMP message queue that continually keeps the TruSTAR integration informed of events that have taken place on the Resilient server and enables the integration to take real-time action on events when appropriate.
What is a Resilient Integration Server?
A Resilient integration's code can reside and run either on the Resilient appliance itself or on a separate host. If you elect to run integrations on a host other than the host that the Resilient server resides on, you are using an Integration Server. See the Resilient Integration Server documentation for more details.

For a list of the advantages to using an integration server, see Resilient Integration Server Architecture Guide.

User Accounts

  • Linux Install Account: Command-line access to a Linux user account with 'sudo' privileges on the host on which you will install and run the TruSTAR integration (Resilient appliance or "integration server"). You will use this account to install and configure Resilient Circuits and the TruSTAR integration.
  • Linux Integration Account: Command-line access to an unprivileged Linux user account named "integration" on the same host the Install account. This account will run Resilient Circuits and the TruSTAR integration after they have been installed and configured.
  • Resilient Integration Account: An IBM Resilient user account specifically for integrations. This account should have the "Administrator" Global Role assigned to it. This user account should have the "Administrator" Global Role assigned to it. This account provides the API credentials to authenticate to and communicate with the Resilient server, whether the integration is running on the main Resilient appliance or a separate integration server.
    • In your Resilients Circuits config file, do not use Resilient credentials tied to a user account that belongs to a human. Create a Resilient user account specifically for integrations.
    • For assistance with Resilient user account creation / permissioning, see the Resilient user account documentation.
  • TruSTAR User Account, with access to TruSTAR Station and to the api_key, api_secret, and enclave ids for report submission and query.

Installing the TruSTAR Package

  1. Login/SSH to a user account on the Resilient (or integrations server) appliance that has sudo privileges.
  2. Ensure that the host's "pip" application is updated.
sudo pip install --upgrade pip
sudo pip install --upgrade resilient_circuits
sudo pip install --upgrade rc-cts
sudo pip install --upgrade rc-webserver
sudo pip install --upgrade trustar_resilient
For information on how to install IBM Resilient Circuits, use this link. You can also reference the IBM Resilient Circuits Guides at this github link.
  1. Install the TruSTAR package by unzipping it unzip it and then executing this command:

sudo pip install --upgrade trustar_resilient

Next up is changing the config file:

  • If this is the first integration you've installed on this host, you must create a new config file.

or

  • if the host has other integrations, you can modify the existing config file.

Creating the Config File

  1. Login to the sudo-privileged Linux user account.
  2. Create / update the Resilient Circuits config file by executing this command>
    sudo resilient-circuits config -c

The command's output will tell you the location of the config file. By default, the file is stored at /home/your_username/.resilient/app.config .

The config file will now have sections named "[resilient]", "[trustar]", "[trustar_threat_source]", and "[trustar_account_n]".

Updating the Config File

  1. If this host has other Resilient Circuits integrations installed, then you will need to add the TruSTAR config stanzas to the existing config file by executing this command:

sudo resilient-circuits config -u

If the config file is in the default location (/home/your_username/.resilient/app.config), you should be able to open it with a text editor and see the new "[trustar]", "[trustar_threat_source]", and "[trustar_account_n]" stanzas.

If you've moved your config file to a custom location and neither the -c or -u command is adding the TruSTAR config stanzas to your config file, copy/paste the TruSTAR config stanzas into it.

Editing the Config File

  1. Locate the resilient-circuits configuration file. Its default path on a RHEL host is: /home/your_privileged_user_account_name/.resilient/app.config
  2. In the [resilient] section, provide the information needed to connect to the Resilient platform. See Resilient integration config file documentation for details.
  3. In the [trustar] section, locate the field named queue, which contains the name of the message destination for this integration. The TruSTAR integration ships with a message queue definition, and it will create the message queue in a later step.
Make sure that the user specified in the [resilient] section has access to this message destination. Do this after "Deploy TruSTAR App Configurations" step below.
  1. If the integration is running on a machine that uses a proxy for internet connectivity, add that proxy-related configuration in the [trustar] section as shown below:
[trustar]
# Name of the message destination.
queue = trustar

# Set the value true if proxy is enabled on the machine where this utility is running.
proxy = false

# Set below property as true if secured proxy is in use.
secure_proxy = false

# URL of proxy server in ip:port(8.8.8.8:1111) format
proxy_url =

# Username of secure proxy
proxy_username =

# Password of secure proxy
proxy_password =
  1. In the [trustar_threat_source] section update the values as explained in the table below.
[trustar_threat_source]

# URL of TruSTAR platform.
# DO NOT CHANGE THIS.
url = https://api.trustar.co

# TruSTAR Station API key.
user_api_key =

# TruSTAR Station API secret.
user_api_secret =

# Comma-separated list of enclave IDs to query when checking Artifacts for Hits.
# DO NOT PUT SPACES AFTER COMMAS.
enclave_ids_for_search =

Field

Required

Notes

TruSTAR Station API key

Yes

Used to make API calls. Finding your API Key

TruSTAR Station API secret

Yes

Used when making API calls. Finding your API Secret Key

Enclave IDs to query

Yes

TruSTAR generally users include premium intel enclaves, sharing-group enclaves, and enclave inbox or phishing inbox enclave. Discuss your use-cases & workflows with your TruSTAR account manager for recommendations.

  1. In the [trustar_account_n] section, update the values. When entering multiple values on a line, use commas to separate each value.
[trustar_account_n]
# URL of TruSTAR platform.
# DO NOT CHANGE.
url = https://api.trustar.co

# TruSTAR Station API key.
user_api_key =

# TruSTAR Station API secret.
user_api_secret =

# Comma-separated list of enclave IDs that this workspace's tickets should be
# submitted to.
# DO NOT PUT SPACES AFTER COMMAS.
enclave_ids_for_submission =

# Comma-separated list of enclave IDs.
# DO NOT PUT SPACES AFTER COMMAS.
enclave_ids_for_query =

# Auto Submission parameter. Possible values - enable|disable
auto_submission = enable

# Enter parameters to submit with report to TruSTAR. Possible values:
# summary|notes|breach|artifacts.
submit_data_to_trustar = summary,notes,breach,artifacts

# Incident Types to exclude for report submission to TruSTAR.
incident_types_to_exclude =

# List of workspaces for which this TruSTAR account will be used. (Not API name)
workspace =

# TAG to assign to the report submitted to TruSTAR
tag =

Field

Required

Notes

TruSTAR_account_n

Yes

Change the ‘n’ to any integer.

TruSTAR Station API key

Yes

Used to make API calls. Finding your API Key

TruSTAR Station API secret

Yes

Used when making API calls. Finding your API Secret Key

Enclave IDs to submit to

Yes

TruSTAR recommends submitting Resilient tickets to an enclave specifically for Resilient tickets. Contact your TruSTAR account manager to set up a Resilient Tickets enclave.

Enclave IDs to query

Yes

TruSTAR generally users include premium intel enclaves, sharing-group enclaves, and enclave inbox or phishing inbox enclave. Discuss your use-cases & workflows with your TruSTAR account manager for recommendations.

Auto-submission

Yes

Values are enable or disable.

Report submission parameters

Yes

You can choose any, all, or a combination of these values: Summary, Notes, Breach, Artifact.

Incident types to exclude

No

Types of incidents you do not want to submit to TruSTAR.

List of workspaces

Yes

You can find the correct name of the Resilient workspace(s) on the Workspaces screen in Administrator Settings. Use the value in the Name of Workspace field, not the value in the API Name field.

Tags

No

Any text you want to add to the report in TruSTAR.

You can add other TruSTAR accounts for different workspaces. Append a new section named [trustar_account_n] with some other value of ‘n’ and repeat the step above. Most users do not need more than one account, but MSSPs may find multiple accounts useful.

Configuring the Threat Service

If you want to use the Threat Service feature, you can edit the app.config file.

Ignore if you have already installed rc-cts and rc-webserver packages and added configuration for both into app.config file
  1. In the [webserver] section, update following fields:
[webserver]
server=172.30.45.223
port=9000
secure=0
cafile=

This section tells the Threat Service web server which IP/port it should bind to, whether to use HTTP or HTTPS, and what certificate to use as its public key (if requiring HTTPS).

"server" should be:

- "localhost" if running Resilient Circuits on the same host as the Resilient application

- LAN IP of the integration server if running Resilient Circuits on a separate integration server.

  1. Add a [custom_threat_service] section in app.config file
  2. In that new section, add the fields and values listed below.
[custom_threat_service]
urlbase=/cts
first_retry_secs= 60
later_retry_secs=60
max_retries=60
cache_size=1000000
cache_ttl=600000
Most users should use these settings. Only Resilient administrators/engineers who know what they're doing should modify them. TruSTAR does not provide support for modifying these settings.

Registering the Custom Threat Service

When Resilient Circuits starts, it launches a lightweight HTTP server (rc-webserver) that the Resilient application can query for "Hits" on Artifacts. You have to tell Resilient how to reach this HTTP server.

  1. Your appliance's threat service URL is based on the app.config file's [webserver] and [custom_threat_source] stanzas. If those stanzas in the config file look like this:
.....

[webserver]
server = localhost
port = 9000
secure = 0

[custom_threat_service]
urlbase=/cts
#first_retry_secs= 5
#later_retry_secs=60
#max_retries=60
#cache_size=10000
#cache_ttl=600000

then the appliance's threat service URL will be:

http://localhost:9000/cts/trustar

If "secure" = 0, then use "http". If "secure" = 1, use "https".

  1. Start the Threat Service

While ssh'ed into the Resiliient appliance (not the integration server) as a user with sudo privileges, enter this command at the command line:

sudo resutil threatserviceedit -name "TruSTAR" -resturl "{url}/cts/trustar"
  1. Replace {url} with the URL calculated above. Example:
 sudo resutil threatserviceedit -name "TruSTAR" -resturl "http://localhost:9000/cts/trustar"

Deploying Customizations

The TruSTAR App contains customized rules, message destination and function definitions.

  1. Deploy these customizations to the Resilient platform with the following command:
resilient-circuits customize
  1. Answer the prompts to deploy functions, message destinations, workflows and rules.

Running the Integration Framework

You will need to set up Resilient Circuits as a service. For instructions on how to do this, use this IBM Support documentation.

  1. To test that you have successfully set up the Resilient Circuits integration, run this command:
resilient-circuits run
  1. To start Resilient Circuits as a service, execute this command:
sudo systemctl start resilient-circuits

Configuring the TruSTAR App

You can configure these elements for the TruSTAR App:

  • Assign an Incident to a particular workspace
  • Set up automatic fetching of priority scores

Assigning an Incident to a Workspace

This feature lets you submit incident data to different TruSTAR accounts or enclaves based on the Resilient workspace in which the incident is assigned.

User needs to add TruSTAR credentials and other details in app.config for this feature.

To assign an incident to a particular workspace, perform the following steps.

  1. Navigate to Customization Settings
Resilient_Install_Figure2
  1. Click Layouts on the Customization Settings menu.
Resilient_Install_Figure3
  1. Click New Wizard on the left menu.
Resilient_Install_Figure4
  1. Add Workspace information from Fields to one of the blocks.
  2. Click Save to save the changes.
Resilient_Install_Figure5

Now you can select a specific workspace whenever you create a new incident.

Resilient_Install_Figure6

Fetching a Priority Score from TruSTAR

Whenever a new artifact is added to any incident, the Threat Service can fetch its priority score from TruSTAR and update that information in the artifact’s hits section. Values are displayed as LOW, MEDIUM, HIGH, or NOT_FOUND

To enable or disable this feature:

  1. Navigate to Administrator Settings.
Resilient_Install_Figure7
  1. Click Threat Sources on the Administrator Settings menu.
Resilient_Install_Figure8

  1. You can change the TruSTAR status by clicking it ON or OFF.
Resilient_Install_Figure9


How Did We Do?