TruSTAR App for IBM Resilient Install

Updated 2 weeks ago by Elvis Hovor

This document explains how to install and configure the TruSTAR integration with IBM Resilient.

The TruSTAR App for IBM Resilient enables you to access TruSTAR's IOCs and incidents within the Resilient workflow. You can automatically send Resilient incidents as TruSTAR reports, enriching them with correlated intelligence from TruSTAR and then automatically update the report when the incident is updated.

You can use the TruSTAR App with Resilient 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.

Installation Options

You can choose to install the TruSTAR 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

Time Requirements

Resilient integrations take a long time to install / configure. This should take an experienced Resilient engineer/administrator 2 hours to complete.

Knowledge/skill Requirements

This installation guide assumes that the user installing this integration is a Resilient Server administrator 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 Requirements

  • 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 Requirements

  • 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 a Resilient "Integration Server"?
See Resilient's Integration Server documentation for more details. 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". For a list of the advantages to using an integration server, see Resilient Integration Server Architecture Guide.

User Account Requirements

  • Your IBM Resilient user account that has "Master Administrator" Global Role assigned to it.
  • An IBM Resilient user account specifically for integrations. This account should have the "Administrator" Global Role assigned to it. For assistance with Resilient user account creation / permissioning, see the Resilient user account documentation.
  • 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'll use this account to install and configure Resilient Circuits and the TruSTAR integration.
  • Command-line access to an unprivileged Linux user account named "integration" on the same host as previous bullet. This user account will run Resilient Circuits and the TruSTAR integration after they have been installed and configured.
  • Access to TruSTAR Station and to the api_key, api_secret, and enclave ids for report submission and query.

Overview

This documentation will walk you through the following steps and refer you to IBM documentation when appropriate:

  • Login/SSH to a user account on the Resilient (or integrations server) appliance that has sudo privileges.
  • Create "integrations" Resilient user account if it doesn't yet exist.
  • Pip-install the TruSTAR integration.
  • Creating or Updating the Resilient Circuits Configuration File
  • Editing the Resilient Circuits Configuration File
  • Configuring the Threat Service (if not already configured for another integration)
  • Executing the 'keyring' Command
  • Deploy TruSTAR App customizations using the 'customize' Command
  • Running the integration framework.
  • Setup a Resilient Circuits service that will be managed by "systemd"
    • Create "integrations" Linux user account if it doesn't yet exist.

Create "integrations" Resilient User Account

The Resilient Circuits needs a set of 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".

As is recommended best-practice with TruSTAR API credentials, Resilient also recommends that users create a user account specifically for this purpose. Do not, in your Resilient Circuits config file, use Resilient credentials tied to a user account that belongs to a human. Create a Resilient user account specifically for integrations. See the "email" row of the table on Resilient's integrations config file documentation page for more details.

See Resilient user account documentation for assistance creating a Resilient user account.

This user account should have the "Administrator" Global Role assigned to it.

Install the TruSTAR integration.

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 TruSTAR integration to take immediate real-time action on events when appropriate. Had IBM not kindly put this in place, Resilient integrations would have to periodically query/poll the Resilient server for events the integration is interested in and then take appropriate action. Applications of that nature are more-taxing on the Resilient server, so, thanks, IBM.

While logged into the Resilient (or Integration Server) appliance's privileged user account (the one that can "sudo"), ensure that the host's "pip" application is updated, then install the TruSTAR package.

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.

To install the TruSTAR App package, unzip it and then install it using the following command:

sudo pip install --upgrade trustar_resilient

Creating or Updating the Resilient Circuits Configuration File

  1. Login to the sudo-privileged Linux user account.
  2. Create / update the Resilient Circuits config file.
    If this is the first integration you've installed on this host, then have the Resilient Circuits app create a new config file template for you by running this command:
    sudo resilient-circuits config -c
    ...the command's output will tell you where it put the config file. By default it will place the file at /home/your_username/.resilient/app.config .
    The config file will have sections named "[resilient]", "[trustar]", "[trustar_threat_source]", and "[trustar_account_n]". If you run the command before pip-installing the trustar_resilient package, then it will only have a "[resilient]" section.
    OR....
    If you have previously installed other Resilient Circuits integrations on this host, then after pip-installing the "trustar_resilient" package, run this command to direct Resilient Circuits to add the TruSTAR integration's config stanzas to your config file.
    sudo resilient-circuits config -u
    If your 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 "[trustar]", "[trustar_threat_source]", and "[trustar_account_n]" stanzas added to it.
    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 Configuration 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 all 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 following fields:
    What enclaves should I use in the 'enclave_ids_for_search' field?
    As a starting point, TruSTAR generally users include their 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 custom to your needs.
[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 =
  1. In the [trustar_account_n] section:
  • Change the ‘n’ with some integer number
  • Update the following fields. When entering multiple values on a line, use commas to separate each value.
    What enclave(s) should I submit to?
    TruSTAR recommends submitting Resilient tickets to an enclave specifically for Resilient tickets. TruSTAR recommends against submitting them to enclaves that contain other data. Your TruSTAR account manager can make you a Resilient Tickets enclave.
    What enclaves should I query from?
    This feature creates additional artifacts on a ticket from IOCs found in TruSTAR Station that correlate to the ticket's original artifacts that can be used in subsequent SOAR actions. TruSTAR recommends as a starting point that you include your premium intel, sharing group, and phishing enclaves here.
[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 =
You can find the correct name of the Resilient workspace(s) on the Workspaces screen in Administrator Settings. Be sure to use the value in the Name of Workspace field, not the API name field.
Resilient_Install_Figure1
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 won't need to do this; it is intended for MSSPs.

Configuring the Threat Service

If you want to use the Threat Service feature, add the following sections to 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 = localhost
port = 9000
secure = 0
cafile =

This section tells Resilient Circuits where it can reach the threat-service's web server. The only configuration TruSTAR supports and gives documentation for is to have the web server running on the same host as Resilient Circuits. Some enterprises may elect to deploy a separate standalone web server host specifically for a threat service - that is not needed for this integration.

  1. Add a [custom_threat_service] section in app.config file
  2. In that new section, add the fields and values listed below.
  • 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.
[custom_threat_service]
urlbase=/cts
first_retry_secs= 60
later_retry_secs=60
max_retries=60
cache_size=1000000
cache_ttl=600000

Deploy TruSTAR App customizations

The TruSTAR App package contains 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.

To test that you have successfully set up the Resilient Circuits integration, run this command:

resilient-circuits run

This is an example of terminal output on successful startup using the above command:

[schamales@resilient ~]$ resilient-circuits run
2020-06-11 14:31:08,770 INFO [app] Configuration file: /home/schamales/.resilient/app.config
2020-06-11 14:31:08,770 INFO [app] Resilient server: localhost
2020-06-11 14:31:08,771 INFO [app] Resilient user: schamales+dev_resilient_integration@trustar.co
2020-06-11 14:31:08,771 INFO [app] Resilient org: TruSTAR Technology
2020-06-11 14:31:08,772 INFO [app] Logging Level: INFO
2020-06-11 14:31:08,773 WARNING [co3] Unverified HTTPS requests (cafile=false).
2020-06-11 14:31:08,783 INFO [connectionpool] Starting new HTTPS connection (1): localhost
2020-06-11 14:31:10,171 INFO [app] Components auto-load directory: (none)
2020-06-11 14:31:10,496 - INFO - resilient_circuits.component_loader:98 - Loading 6 components
2020-06-11 14:31:10,496 - INFO - resilient_circuits.component_loader:100 - 'trustar_cts.components.searcher.TruSTARThreatSearcher' loading
2020-06-11 14:31:10,497 - INFO - resilient_circuits.component_loader:100 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' loading
2020-06-11 14:31:10,499 - INFO - resilient_circuits.component_loader:100 - 'rc_webserver.components.webroot.WebRoot' loading
2020-06-11 14:31:10,500 - INFO - resilient_circuits.component_loader:100 - 'rc_webserver.components.webservice.WebService' loading
2020-06-11 14:31:10,503 - INFO - rc_webserver.components.webservice:55 - WebService listen address: http://127.0.0.1
2020-06-11 14:31:10,503 - INFO - resilient_circuits.component_loader:100 - 'rc_cts.components.threat_webservice.CustomThreatService' loading
2020-06-11 14:31:10,506 - INFO - rc_cts.components.threat_webservice:195 - Web handler for /cts/POST, /cts/OPTIONS, /cts/GET
2020-06-11 14:31:10,507 - INFO - resilient_circuits.component_loader:100 - 'rc_cts.components.searcher_example.SearcherExample' loading
2020-06-11 14:31:10,508 - WARNING - resilient_circuits.actions_component:472 - Unverified STOMP TLS certificate (cafile=false)
2020-06-11 14:31:10,516 - INFO - resilient_circuits.stomp_component:54 - Connect to localhost:65001
2020-06-11 14:31:10,517 - INFO - resilient_circuits.actions_component:580 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' function 'get_correlated_indicators_from_trustar' registered to 'trustar'
2020-06-11 14:31:10,517 - INFO - resilient_circuits.actions_component:568 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' actions registered to 'trustar'
2020-06-11 14:31:10,517 - INFO - resilient_circuits.actions_component:580 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' function 'delete_report_in_trustar' registered to 'trustar'
2020-06-11 14:31:10,517 - INFO - resilient_circuits.actions_component:580 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' function 'get_priority_score_of_indicator' registered to 'trustar'
2020-06-11 14:31:10,517 - INFO - resilient_circuits.actions_component:580 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' function 'submit_report_to_trustar' registered to 'trustar'
2020-06-11 14:31:10,518 - INFO - resilient_circuits.actions_component:580 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' function 'undo_whitelist_in_trustar' registered to 'trustar'
2020-06-11 14:31:10,518 - INFO - resilient_circuits.actions_component:580 - 'trustar_resilient_action_module.components.trustar_handler.TruSTARHandler' function 'whitelist_in_trustar' registered to 'trustar'
2020-06-11 14:31:10,520 - INFO - resilient_circuits.app:300 - App Started
2020-06-11 14:31:10,522 - INFO - resilient_circuits.actions_component:688 - STOMP attempting to connect
2020-06-11 14:31:10,523 - INFO - resilient_circuits.app:272 - Components loaded
circuits.web/3.2 ready! Listening on: http://127.0.0.1
2020-06-11 14:31:10,526 - INFO - resilient_circuits.stomp_component:167 - Connect to Stomp...
2020-06-11 14:31:10,527 - INFO - stompest.sync.client:121 - Connecting to localhost:65001 ...
2020-06-11 14:31:10,607 - INFO - stompest.sync.client:127 - Connection established
2020-06-11 14:31:11,078 - INFO - stompest.sync.client:143 - Connected to stomp broker [session=ID:resilient.trudevs.com-38885-1591285264621-4:5, version=1.2]
2020-06-11 14:31:11,078 - INFO - resilient_circuits.stomp_component:176 - Connected to failover:(ssl://localhost:65001)?maxReconnectAttempts=1,startupMaxReconnectAttempts=1
2020-06-11 14:31:11,078 - INFO - resilient_circuits.stomp_component:137 - Client HB: 0 Server HB: 15000
2020-06-11 14:31:11,078 - INFO - resilient_circuits.stomp_component:149 - No Client heartbeats will be sent
2020-06-11 14:31:11,078 - INFO - resilient_circuits.stomp_component:156 - Requested heartbeats from server.
2020-06-11 14:31:11,080 - INFO - resilient_circuits.actions_component:605 - resilient-circuits has started successfully and is now running...
2020-06-11 14:31:11,080 - INFO - resilient_circuits.actions_component:650 - Subscribe to message destination 'trustar'
2020-06-11 14:31:11,080 - INFO - resilient_circuits.actions_component:346 - STOMP connected.
2020-06-11 14:31:11,081 - INFO - resilient_circuits.stomp_component:246 - Subscribe to message destination actions.201.trustar

To start Resilient Circuits as a service, execute this command:

sudo systemctl start resilient-circuits

Registering the custom threat service with the Resilient application.

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. This section walks you through that process.

Calculate the threat service URL.

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".

It is possible to run a

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"

Replace {url} with the URL calculated above. Example:

 sudo resutil threatserviceedit -name "TruSTAR" -resturl "http://localhost:9000/cts/trustar"

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?