Content

Downloadable version at bottom of this article

Licensed Materials – Property of IBM

© Copyright IBM Corp. 2010, 2017. All Rights Reserved.

US Government Users Restricted Rights: Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Resilient Incident Response Platform On-Premises Installation Guide

Table of Contents

1. Introduction. 5

1.1. Installation Requirements. 5

1.2. Installation Overview.. 5

1.3. Getting Started. 6

2. Deployment 7

2.1. Deploying the Appliance. 7

2.2. Performing First Boot Configuration. 10

3. Connection and Notifications. 12

3.1. Importing the Resilient License. 12

3.2. Updating the Resilient Appliance Software. 14

3.3. Configuring Email 15

3.4. Setting the Time Zone. 16

4. SSL Certificate. 17

4.1. Creating and Submitting the Certificate Request 17

4.2. Importing the Signed Certificate. 18

4.3. Testing the New Certificate. 19

5. Accounts and Additional Configuration. 19

5.1. Creating the Initial Resilient User Account 19

5.2. Add Additional User Accounts. 20

5.3. Security Updates. 20

5.4. Network Configuration. 20

5.5. Log File Configuration. 21

6. Authentication. 22

6.1. LDAP Authentication. 22

6.2. SAML Authentication. 26

6.2.1. Create a SAML Federation. 26

6.2.2. Import the SAML Metadata Into Your Identity Provider 27

6.2.3. Test the Configuration. 28

6.3. Two-Factor Authentication. 28

6.3.1. How to Set Up Two-Factor authentication. 28

6.3.2. Enabling Your Authentication Domain. 30

6.3.3. Registering Users. 30

6.3.4. Two-Factor Authentication and User Experience. 31

7. KeyVaults. 32

7.1. Storage Format, Location and Key. 32

7.2. Configuration Options. 32

7.3. KeyVault Backup. 33

7.4. Secrets. 33

8. Backup and Restore. 34
9. Upgrade Procedure. 36

1. Introduction

Based on a knowledgebase of incident response best practices, industry standard frameworks, and regulatory requirements, the Resilient Incident Response Platform makes incident response efficient and compliant.

If your organization experiences a malware outbreak, system intrusion, or advanced blended attack, the Resilient platform instantly generates detailed dynamic playbooks and provides a platform for team member investigation, collaboration, and reporting. The Resilient platform turns a privacy breach response from a lengthy, tedious, expensive, and stressful process to one that is easily monitored and always up-to-date. Based on an industry-leading knowledgebase of privacy-related regulations with breach notification requirements, the Resilient platform instantly gives you a platform for breach preparation, assessment, and management.

1.1. Installation Requirements

To begin, you must download the Resilient appliance from the web site. The Resilient appliance is a VMware virtual application (vApp) in Open Virtualization format (.ova file). The Resilient appliance runs only on VMware vSphere Hypervisor (ESXi). The VMware image is based on the Turnkey Linux project, which is a Debian Linux derivative.

The Resilient appliance is a self-contained server that runs the Resilient platform. The server contains Tomcat and PostgreSQL. By default, the Resilient appliance has two CPUs, eight gigabytes (GBs) of memory, and a 100GB thin provision disk after deployment. These are the minimum recommended settings; however, you can change these settings during deployment.

1.2. Installation Overview

This document guides you through the following steps to install the Resilient platform:

1. Deploy the appliance and performing first boot configuration.
2. Connect through PuTTY/ssh.
3. Install the Resilient license.
4. Perform system updates.
5. Configure email notifications.
6. Configure a Secure Socket Layer (SSL) certificate.
7. Create an initial user account.
8. Add additional Resilient user accounts.
9. Test the system configuration by connecting to the Resilient platform.
10. Add security updates.
11. Configure the appliance to access specific URLs on the Internet.
12. Configure authentication.

The entire installation should take about an hour to complete.

1.3. Getting Started

Before you start the installation, make sure that you have the following:

• VMware ESXi and the credentials required to create virtual instances.
• VMware vSphere client.
• An IP address for the Resilient appliance only if you want to use a static IP address.
• An SSH client, such as PuTTY, to connect to the Resilient appliance.
• Certificate authority (CA) that signs the Resilient appliance SSL certificate. This may be an internal CA used within your company or a third party CA such as Verisign or Thawte.
• SMTP server and credentials that the Resilient appliance can use to send email notifications.
• Resilient license.

2. Deployment

Before you connect to the Resilient platform, you must deploy the appliance and perform first boot configuration.

2.1. Deploying the Appliance

Before you can deploy the Resilient appliance, you must download an .ova file from the web site and obtain a license file. The .ova file is a template. After you deploy the template, you have installed the appliance. To install the Resilient appliance:

1. Open the VMware vSphere client.
2. Select File>Deploy OVF Template.
3. Browse to the location of the .ova file you downloaded from the Resilient web site and select the .ova file.
4. Click Next. The OVF Template Details screen appears:
5. Click Next then click Accept to accept the End User License Agreement.
6. Click Next.
7. Enter a name for the deployed template and click Next. The Disk Format screen appears:
8. Select the Thick Provision Lazy Zeroed, Thick Provision Eager Zeroed, or Thin Provision option. If you choose one of the thick provisions, the appliance initially begins using 100 gigabytes of storage. If you choose Thin Provision, the appliance initially begins using a small amount of gigabytes and grows over time. Click Next.

The Ready to Complete screen appears.

9. Select the Power on after Deployment option and click Finish. A status bar appears during deployment. VMware notifies you when the appliance successfully deploys.
10. Click Close in the Deployment Completed Successfully dialog box.

You have successfully installed the Resilient appliance.

2.2. Performing First Boot Configuration

After you install the Resilient appliance, you must perform first boot configuration. During first boot configuration, you establish system account passwords and configure your network for the appliance. The first part of first boot configuration involves creating a root password. This password is for emergency use only. Then you must create a password for your resadmin account. You use the resadmin account for general system configuration and maintenance. Next, you must configure your network with the IP address of the Resilient appliance. You perform first boot configuration using the VMware console. You perform subsequent configuration using PuTTY/ssh.

Perform the following procedure to create a root password, a resadmin password, and set an IP address:

1. Select the name of the appliance in the left tree pane of the VMware client.
2. Select the Console tab. The First boot configuration screen appears:
3. Place your cursor in the screen and enter a root password.
4. Press the Enter key on your keyboard to select OK.
5. Re-enter your password to confirm it, and press Enter to select OK.
6. Enter a password for the resadmin account and press Enter.
7. Re-enter your password to confirm it and press Enter.
8. If your organization uses Dynamic Host Configuration Protocol (DHCP), you can use it to obtain an IP address. This IP address automatically appears in the console screen in VMware, and you have completed this procedure. You can press the CTRL key and then the ALT key to remove your cursor from VMware.
9. If your network does not support DHCP or you do not want to use DHCP to obtain an IP address, click in the Console window in VMware, press the Enter key to select the Advanced Menu, and complete the remaining steps in this section.
10. Select Networking by pressing Enter again. The console appears, as follows:
11. Press the down arrow to select Static IP and press Enter.
12. Enter the IP address you want to use in the IP address field, press the Tab key, and press Enter to select Apply. Make sure that the host name resolves to that IP address. The Resilient appliance does not automatically register the IP address in DNS.
13. Enter the IP address in your Domain Name Server (DNS). When you complete this procedure, you can press the CTRL key and then the ALT key to remove your cursor from

3. Connection and Notifications

This section provides the procedures to import the Resilient license, connect to the Resilient appliance, and set up email notifications.

3.1. Importing the Resilient License

Before you can start the Resilient platform, you must import the license that you obtained from IBM Resilient. To import the license, you must log in to the appliance using an SSH client, such a PuTTY. To import the license:

1. Open the license file that you received from IBM Resilient using a text editor.
2. Select the contents of the file and copy it to the clipboard. You must select and paste in everything beginning with the -----BEGIN LICENSE----- and ending with the -----END LICENSE-----. For example:

-----BEGIN LICENSE-----

AB+LCAAAAAAAAACFkMFOwzAMhl9l8rlibZOlazzkDnBAGpyAe+q4WqU0qeJUMCHenYyd6GUnW7/t77f9DckGF2cw8PxxfONRu422uYcKcOUcZ0qvdqZLNXC23ts8xbB7jLg7TkiBqXQy4ZqmfHxq5vDkwIzWM1VAX8uU/gbAhNX7ClamFK48rFvdKdeRalSj5TA6aQ/NoJxqsR01Fu5imT9jKkAYBAmUkg5ClBR139QdWuz7vu61chqddAZTV5Boie/Jl7FTzgub/f6WmbnFf7gw7zAKPnDFs5FSFE+72PKEzdXrVimbbRS0/5WfX6edayyHAQAA:MCwCFEkEbS/Z1yvEDH6Au7GWBLPWQpRgAhRcLySrqiGiEe8BhnwHZRz2/B+nGA==

-----END LICENSE-----

3. Open PuTTY and connect to the address that appears in the VMware console window as follows:
4. Log in using the resadmin account you created in the previous section.
5. To import the license, enter the following command:

sudo license-import

The system prompts you:

Please enter or paste in the license:

6. Right-click in the PuTTY to paste the contents of the license file. If the license is successfully imported, then a message appears on the screen along with the license features. For example:

Successfully imported license

Customer name: <customer>

Expiration: No expiration

US regulators enabled: true

CA regulators enabled: true

EU regulators enabled: true

APAC regulators enabled: true

Security module enabled: true

Users: Unlimited

If the license import fails and the error message reports an Invalid License Signature, the license file is invalid because the signature is not valid. If the license import fails and the error message reports an Expired License, the license is valid but expired.

To display information about the currently installed license, enter the following command:

sudo resutil license

The system displays the following information:

• Customer name, which is the name of your company.
• Expiration, which is the expiration date of the license, or no expiration if the license does not expire.
• US regulators enabled, which displays true or false.
• CA regulators enabled, which displays true or false.
• EU regulators enabled, which displays true or false.
• APAC regulators enabled, which displays true or false.
• Security module enabled, which displays true or false.
• Users, which displays the number of users the license allows, or Unlimited if there are an unlimited number of users allowed.

If you do not have an installed license when you run this command, the system informs you that no license is installed.

3.2. Updating the Resilient Appliance Software

Next, you must connect to the Resilient appliance and perform system updates. Enter the following command in your SSH client:

wget --trust-server-names https://repo.co3sys.com/public/77a78a07d35ab3a8c46b17c88ac37ac1/latest.php

The command downloads a resilient-<version>.run file. Use the following command to install the file using the actual version number (typically in the format x.x.x) in the file name.

sudo bash resilient-<version>.run

Reenter the resadmin password when the system prompts you.

The Resilient appliance is now installed and running.

NOTE: Under some circumstances, the Resilient services may not start correctly. You should verify that the services are started.

3.3. Configuring Email

The Resilient platform sends email messages to users for notifications, such as when a new user becomes a member or when the platform assigns a user a task. Therefore, the Resilient platform must use an SMTP server to send these messages. After you install the platform, stay in the SSH client you use and enter the following command with the options you want to use to edit the SMTP configuration:

sudo resutil smtpedit

This command has the following options and defaults:

• -help prints the SMTP edit configuration help. The default is false.
• -email provides the email address in the From field of the email message.
• -host provides the hostname of the mail server.
• -name provides the name in the From field of the email message.
• -port provides the port of the mail server.
• -user provides the user of the mail server. The system prompts you for the password if you use this option.

The following is an example that shows how to configure the system so that email messages sent from the Resilient platform appear to be from Resilient Incident Management <user@example.com>. In this example, the SMTP server is <smtp.example.com> and the port is 2525. The SMTP server requires authentication in this example and the account used is the Resilient account. If your SMTP server does not require authentication, you can omit the –user option.

sudo resutil smtpedit -email user@example.com -name "Resilient Incident Management" -host smtp.example.com -port 2525 -user resilient

Enter the password for the user: <SMTPpassword>

Confirm the password for the user: <SMTPpassword>

Successfully edited the SMTP configuration

SMTP Host: smtp.example.com

SMTP Port: 2525

SMTP User: resilient

SMTP Password: hidden

SMTP From Email: user@example.com

SMTP From Name: Resilient Incident Management

After you configure email, you can test the configuration by entering the following command with the options you want to use:

sudo resutil smtptest

This command has the following options and defaults:

• -help prints the SMTP edit configuration help. The default is false.
• -email provides the email address where you want to send the test email message.
• -wlhost allows you to specify the hostname when it is different from the certificate common name to avoid certificate name mismatch errors.

The following is an example:

sudo resutil smtptest -email joe@example.com

Successfully sent the test email to joe@example.com

If the host you specified was not running an SMTP server, the following error message appears:

An error occurred while running the command line utility: Sending the email to the following server failed : badhost:25

Could not connect to SMTP host: badhost, port: 25

Connection refused

If you specified an invalid user or password, the following error message appears:

An error occurred while running the command line utility: Sending the email to the following server failed : mailtrap.io:25

535 invalid authentication

3.4. Setting the Time Zone

The Resilient platform uses dates for different purposes and therefore needs to know the time zone of your location. To set the Resilient appliance's time zone:

1. Enter the following command in the SSH client:

sudo dpkg-reconfigure tzdata

The following screen appears:

2. Click in the screen then use the up and down arrows on your keyboard to select the general geographic area of your location. Press the Enter key to select OK.
3. Use the up and down arrows to select the time zone of your location, and press the Enter key to select OK, as follows:
4. Restart the Resilient service by entering the following command:

sudo service resilient restart

4. SSL Certificate

The Resilient appliance comes with a self-signed Secure Socket Layer (SSL) certificate. We recommend that you use an SSL certificate with the Resilient platform. However, we do not recommend that you use the certificate that comes with the appliance in a production environment. For optimal security, we recommend that you obtain a certificate from a certificate authority (CA).

To obtain and use the SSL certificate, follow these steps, which are outlined in more detail in the following sections:

1. If you do not have a signed certificate, you can create a certificate request then submit it to a CA, such as Thawte or Verisign, for signing.
2. Import the signed certificate into the Resilient platform then restart the Resilient service so that it recognizes the new certificate.
3. Test the new certificate.

4.1. Creating and Submitting the Certificate Request

To create a certificate request:

1. Enter the following command in your SSH client:

sudo cert-req

The system prompts you:

Enter the fully qualified domain name of this host (e.g. resilient.example.com)

2. Enter the qualified domain name of the host, for example: resilient.example.com

The system prompts you:

Enter your company name

3. Enter the name of your company, for example: My Company, Inc.

The system prompts you:

Enter your organizational unit (group within the company)

4. Enter the name of your group in the company, for example: Incident Response

The system prompts you:

Enter the name of the city or locality where this host is located

5. Enter your city, for example: Cambridge

The system prompts you:

Enter the name of the state or province where this host is located

6. Enter your state. Most CAs do not accept your request if you use a state abbreviation. For example, enter Massachusetts. The system prompts you:

Enter your 2 letter country code

7. Enter the abbreviation for your country; for example, US.

You can locate the certificate request in /crypt/certs/certreq.pem directory and it appears on the screen, as follows:

-----BEGIN NEW CERTIFICATE REQUEST-----

MIIDAjCCAeoCAQAwgYwxCzAJBgNVB...

-----END NEW CERTIFICATE REQUEST-----

8. Copy the content of the certificate request to the clipboard, starting with the "-----BEGIN NEW CERTIFICATE REQUEST-----" and ending with the "-----END NEW CERTIFICATE REQUEST-----".

In PuTTY, you use the left mouse button to select text. The act of selection automatically copies the text to the clipboard. You do not need to press any other key. The only thing you need to do to copy text to the clipboard is to select it.

Once you have the request, you need to have it signed. The procedure for getting your certificate signed depends on which certificate authority (CA) you use. If you choose a CA such as Verisign (http://www.verisign.com) or Thawte (http://www.thawte.com), go to their web site to obtain a signed certificate. You can submit the certificate request you generated in the previous section to your CA through their web site. If the CA asks for the server platform that the certificate applies to, you should choose Tomcat. They then contact you with information on how to obtain your signed certificate. After you obtain a signed certificate, you can import it into the Resilient platform.

4.2. Importing the Signed Certificate

To import the signed certificate, copy the certificate file to your Resilient appliance and enter the following command in your SSH client:

sudo cert-import <cert>

Where <cert> can be an end user certificate, such as cert.cer, or a certificate chain, such as ca-chain.p7b.

After you import the signed certificate, restart the Resilient service by entering the following command:

sudo service resilient restart

4.3. Testing the New Certificate

You can now test that the certificate works by connecting to the Resilient platform from a browser. Open a browser and enter the following location:

https://<hostnameforRESILIENTplatform>

If you do not know the IP address of the Resilient platform, open VMware and view the IP address in the left tree pane. If you enter the IP address in a browser and https appears crossed out, click the icon beside it to obtain more information on the error.

5. Accounts and Additional Configuration

5.1. Creating the Initial Resilient User Account

Before you can use the Resilient platform, you must configure an initial user account in the platform and an organization to which this user belongs. This initial user is the platform's system administrator. After you create the system administrator account, you can use the account to create other users in the Resilient platform. Enter the following command in your SSH client to create the platform’s system administrator account and the organization to which the administrator belongs:

sudo resutil newuser

This command has the following options and defaults:

• -createorg creates the organization that contains the system administrator.
• -email provides an email address for the user. This is a required option.
• -first provides the first name of the system user.
• -last provides the last name of the system user.
• -org provides an organization for the user. This is a required option.

This command prompts you to enter and confirm the password for this user (no keystrokes appear on the screen). The following is an example of the command:

sudo resutil newuser -createorg -email "jsmith@example.com" -first "John" -last "Smith" -org "My Company, Inc."

Enter the password for the user:

Confirm the password for the user:

Creating a new user John Smith <jsmith@example.com

Creating a new organization My Company, Inc.

Adding the user John Smith <jsmith@example.com> to the organization My Company, Inc.

Upon successful completion of this command, you will be able to login to the application and finish setup.

You can create multiple organizations in your system by running the above command multiple times. You only need to provide the -first and -last options the first time the user is created.

5.2. Add Additional User Accounts

Now that you have successfully installed and set up the Resilient platform, you can open it and begin adding additional user accounts for the users you want to have access to the platform. See the Resilient Incident Response Platform Master Administrator Guide, included in the Resilient platform, for more information on adding additional Resilient user accounts.

5.3. Security Updates

The Resilient appliance automatically performs security updates over the network every night at 4:00 a.m. local time. These updates come directly from the Turnkey Linux and Debian projects. IBM Resilient monitors security fixes to ensure that they do not interfere with the operation of the Resilient appliance. Automatic updates can introduce some risk because they can occasionally, compromise existing functionality. However, the Turnkey and Debian projects mitigate this risk by carefully separating out security fixes and only accepting the minimum possible fix required to resolve security issues.

If you wish to disable automatic security updates, you can do so by entering the following command from the Resilient appliance console:

sudo rm /etc/cron.d/cron-apt

To perform the equivalent update manually, enter the following command:

sudo /usr/sbin/cron-apt

5.4. Network Configuration

In order for some Resilient appliance functions to operate properly, the system requires access to services on the Internet. Work with your network administrators to ensure the appliance has access to the following URLs to support the corresponding services.

5.5. Log File Configuration

The Resilient platform logs various client and server activity in log files, located in the following directory:

/usr/share/co3/logs/

Log files in this directory include:

• out. Tomcat Catalina output file.
• log. Main Resilient platform log file.
• log. Tomcat-based log that keeps track of all HTTP request made to the Resilient platform server.
• log. Resilient platform log file containing timing-related information.

PostgreSQL logs database access in log files located in the following directory:

/var/lib/postgresql/9.1/main/pg_log/

Most logs roll daily and the rolled file is named with the date that it was rolled. The daily folder contains the rolled client.log and monitoring.log files.

By default, the Resilient client log files (client.log and monitoring.log) use a timestamp that includes only the current time of day. This is because the logs roll over daily and the date of the log is included in the filename. However, you can change the date format in order to keep it consistent across all of your logs. To do this, create a file named logback-custom-pre.xml in the /crypt folder of the Resilient appliance and add the following:

<included>

<property name="customTimeStamp" value=MyFormat/>

</included>

where MyFormat is a valid logback time/date stamp format. For example, "%d{yyyy-MM-dd HH:mm:ss.SSS}" generates log messages with the following date format:

2016-01-14 16:34:39.218 [main] INFO ...

This file must be readable by the co3 group, so you may need to change the group associated with the file using:

$ sudo chgrp co3 /crypt/logback-custom-pre.xml

To implement your changes immediately, restart the Resilient service using the following command:

$ sudo service resilient restart

6. Authentication

You can configure the Resilient platform to use LDAP, SAML, or two-factor authentication. You can use either SAML authentication or LDAP authentication, but not both. Two-factor authentication is a second layer authentication and you can use it with LDAP or SAML.

6.1. LDAP Authentication

To configure the Resilient platform to use LDAP authentication, you must have an Active Directory Server. The Resilient platform supports Active Directory only.

You should also have at least one master administrator per organization whose email address is not managed by the Active Directory. Once LDAP authentication is enabled, any email address managed by the Active Directory (based on your configuration) has its authentication and authorization to organizations determined by LDAP.

The Resilient platform primary LDAP configuration points to a single LDAP tree. By default, all LDAP queries are sent to this tree. If you have an LDAP configuration with multiple trees, you can configure the platform to have a search in this LDAP tree point to a different tree. This is called an LDAP search reference, and it is usually in the form of an LDAP URL, ldap://<domainname>:<port>/<optional parameters>. To do this, you need to provide one or more domain names with the host and port. When there is an LDAP reference to ldap://<domainname>, the platform searches for a sub-configuration that has that domain name. If there is a match, the platform sends the LDAP query to that sub-configuration’s host and port.

NOTE: The LDAP domain name is the name the platform matches when it receives an LDAP search reference. The LDAP domain name does not have to be the same as the host name of that LDAP server.

The basic procedure to configure LDAP is to obtain the LDAP configuration values, use the ldapedit command to enter the values, enter the user password, import the certificate if using an SSL port, and configure a Resilient organization to use LDAP authentication.

1. Make sure that you have the following values available before configuring the Resilient platform. You may need to consult with your LDAP administrator to get the appropriate values for your setup.

2. Use the ldapedit command to enter the LDAP values. For example, using the values in the previous table the command would be:

$ sudo resutil ldapedit -name myLDAP -bindname "cn=John Smith,cn=Users,dc=Example,dc=com" -host myldap.example.com -port 389

If using port 636, you need to add the -usessl argument. For example:

$ sudo resutil ldapedit -name myLDAP -bindname "cn=John Smith,cn=Users,dc=Example,dc=com" -host myldap.example.com -port 636 -usessl

3. When prompted, enter the password of the user to complete the setup.
4. If you wish to search additional LDAP trees, create an additional LDAP configuration, called a sub-configuration, for each tree. The following example shows how to create three sub-configurations. The bindname can be different for each sub-configuration.

$ sudo resutil ldapedit -name salesSub -bindname "cn=John Smith,cn=Users,dc=Example,dc=com" -domainname sales.division.company.com –subdomainof myLDAP -host host1.sales.division.company.com –port 389

$ sudo resutil ldapedit -name marketingSub -bindname "cn=John Smith,cn=Users,dc=Example,dc=com" -domainname sales.division.company.com –subdomainof myLDAP -host host2.marketing.division.company.com –port 389

$ sudo resutil ldapedit -name execSub -bindname "cn=John Smith,cn=Users,dc=Example,dc=com" -domainname sales.division.company.com –subdomainof myLDAP -host host3.executive.division.company.com –port 389

If prompted, enter the password of the user to complete the setup.

NOTE: Using the examples in steps 2 and 4, you now have four LDAP configurations. The configuration defined in step 2 is the primary configuration.

5. If using an SSL port, perform the following:
   1. Obtain the certificate (e.g., myLDAPcert.crt) from your LDAP administrator and copy it to the custcerts keystore (/crypt/certs/custcerts) on the Resilient appliance.
   2. Import the certificate as follows:

$ sudo reskeytool -import -alias myLDAP -file myLDAPCert.pem -keystore /crypt/certs/custcerts

You must trust the certificate to add it to the keystore.

1. If you want to use a different password, you need to update it in the Resilient database after adding the certificate using the following command:

$ sudo resutil keyvaultset -name "custcerts" -value "<New_Password>"

NOTE: The following command reverts the password to the default “changeit”:

sudo resutil keyvaultset -name "custcerts" -value "changeit"

1. As a security precaution, make sure that the hostname of the Active Directory server matches the name in the certificate.

6. If you have a hostname that is different from the certificate common name, enter the hostname to prevent certificate name mismatch errors:

$ sudo resutil ldapedit –wlhost <hostname>

7. Test the configuration.

$ sudo resutil ldaptest

8. After completing the configuration, you must enable it in your Resilient organization as follows:
   1. Log in to your organization as a Master Administrator.
   2. Click on Administrator settings (from the menu by your username).
   3. Click on the Organization
   4. Locate the LDAP Authentication section, under Settings.
   5. Switch the indicator to On.
   6. Select the LDAP group that you wish to have access to the Resilient organization.

NOTE: The information in the last step is also in the Resilient Incident Response Platform Master Administrator Guide.

The following lists other helpful ldapedit commands:

• View the command help:

$ sudo resutil –help

• View your configuration:

$ sudo resutil ldapshow

• Delete your configuration:

$ sudo resutil ldapdel -name myLDAP

• Determine the number of external references a single LDAP search can perform. For example, a search on ldap1 could reference ldap2, which in turn could reference ldap1. The default is 3.

$ sudo resutil configset -key ldap.ref_limit -ivalue <VALUE>

Troubleshooting tip: If you cannot log in after enabling LDAP, check the following:

• If you are unable to log in as an LDAP user, verify that you can use the same account to login using an LDAP browser, such as JXPLORER.
• The master administrator account has an email address managed by Active Directory. Accounts tied to email addresses with Active Directory must be authorized by authorizing a desired LDAP group. Until a group is authorized, no email address tied to an Active Directory can access the organization. Add a new master administrator account to the desired organization using the following command line. Make sure that the email address is not tied to LDAP; in fact, you can use a fake address. (Consider keeping this user for one off circumstances.)

sudo resutil newuser -email "jsmith@example.com" -first "John"
-last "Smith" -org "My orgname"

Once you confirm that this user can log in and access the Administrator settings, then enable LDAP again as before, to authorize your desired LDAP group.

6.2. SAML Authentication

SAML authentication allows users to use their organization’s login credentials to authenticate to the Resilient platform. The SAML specification identifies two different types of endpoints that are relevant to the Resilient platform:

• Identity Providers
• Service Providers

The Resilient platform serves as a SAML Service Provider. An authentication and identification system that you provide (such as Microsoft Active Directory Federation Services) serves as the Identity Provider.

To configure the Resilient platform to function as a SAML Service Provider, follow these steps, which are outlined in more detail in the following sections:

1. Create a SAML federation.
2. Import the SAML metadata into your Identity Provider.
3. Test the configuration.

IMPORTANT: For users who had a previously configured Resilient account, logging into the platform using SAML authentication clears the password for that account. If a user does not log in using SAML, the account is still valid.

6.2.1. Create a SAML Federation

SAML federations are created in the Resilient platform using the resutil tool. In order to create the SAML federation, you need the following information from your Identity Provider:

• Identity Provider Authentication URL
• Identity Provider public certificate

Additionally, you need the organization name on the Resilient platform to which this federation applies. You also need to assign an “alias” for this federation. The alias appears in the URL to users when initially connecting to the Resilient platform through SAML.

The instructions in this section assume that:

• The authentication URL for your identity provider is https://adfs.example.com/adfs/ls/
• You have copied the Identity Provider’s certificate file to the appliance using a tool such as scp and the file name of the certificate file is idp.cer in the current working directory.
• The “alias” for the SAML federation is “resilient”.
• The organization name on the Resilient platform is “My Test Org”.

sudo resutil samledit -alias resilient -certfile idp.cer -org "My Test Org" -createusers -url https://adfs.example.com/adfs/ls/

This command prints out the SAML federation to the console. It also writes out the following files:

• alias-metadata.xml - this is the SAML XML metadata that can be imported into the Identity Provider to complete the configuration.
• alias-sp-cert.pem - this is the Service Provider certificate that was automatically generated.

A federation can be associated with multiple organizations. Consider the situation where your Resilient platform is configured to have two organizations: Production and Development. You can create a single federation that allows access to both organizations. For example:

sudo resutil samledit -alias resilient -org "Production" -org "Development" –certfile idp.cer -url https://adfs.example.com/adfs/ls/

By default, users are only granted access to the organization via the federation if they already exist in that organization. Consequently, in the above example, users would have to exist in both "Production" and "Development" organizations, in order to access them. If, however, you want users to be automatically be added to the “Production” organization then you would specify –createusers for just that organization. For example:

sudo resutil samledit –alias resilient –org "Production" -createusers

If the –createusers argument is specified for both organizations then users who authenticate via the federation are automatically created in both organizations.

You can unlink the federation from an organization by using the -clearorgs flag.

6.2.2. Import the SAML Metadata Into Your Identity Provider

The SAML metadata written out in the previous step can now be imported into your SAML Identity Provider. The specific instructions vary by product. Please consult the documentation for your Identity Provider for instructions on how to create a federation (also called a “relying party”).

The Resilient platform requires that the Identity Provider provide the following attributes:

• E-mail address
• First name (given name)
• Last name (surname)

The Resilient platform does not function if the above attributes are missing.

The Resilient platform utilizes the following attributes if they are present (they are not required for proper operation):

• Phone number
• Mobile phone
• Title
• Groups

Consult your Identity Provider documentation for details on configuring which attributes are sent during authentication.

Authenticated users are added to the groups listed by the Identity Provider in the SAML response. For example, if the user is a member of the “IT” group and it is sent then the user is added to the “IT” group in the Resilient platform, if it exists. Groups that are in the SAML response that do not already exist in the Resilient platform are not automatically created.

6.2.3. Test the Configuration

Once you import the SAML metadata into your Identity Provider, you can test the authentication by using the following URL:

https://<server>/saml2/<alias>

For example, if your server is resilient.example.com and the alias you used to create the federation is resilient, your authentication URL would be:

https://resilient.example/saml2/resilient

Using this URL redirects you to the Identity Provider for authentication. After you have authenticated, you are redirected to the Resilient platform and logged in to the platform. Note that authentication may be done without prompting (single sign-on).

You can send the above URL to users who you wish to grant access to the Resilient platform. Note that all users who are authorized to use the Identity Provider are granted access to the Resilient platform. If you wish to restrict access, you must do so through the Identity Provider configuration.

The Resilient platform evaluates assertions using rules defined by SAML2 Core Specification. This includes verifying the NotBefore and NotOnOrAfter attributes. In some deployments, there may be a clock skew between the Resilient appliance and the Identity Provider, resulting in login failure. To prevent such errors, you can either adjust the Identity Provider’s skew value or set an allowable skew using the resutil tool. For example, to set it to 30 seconds:

sudo resutil configset –key saml.allowed_clock_skew_millis –ivalue 30000

You can increase this value if desired. However, that may increase your security risk. We recommend that you use NTP to ensure that the clocks are synchronized.

6.3. Two-Factor Authentication

Two-factor authentication provides unambiguous identification of users by means of the combination of two different components. These components may be something that the user knows, something that the user possesses or something that is inseparable from the user. Combining two components as a means of identification adds a second layer of security to your accounts. Verifying your identity using a second factor (like your phone or other mobile device) prevents anyone but you from logging in, even if they know your password.

The Resilient platform uses Duo Security, a third-party vendor, as its two-factor authentication provider. When you enable two-factor authentication, users can still log in with their email address and password but are also presented with a challenge - an additional second layer of security provided by Duo Security - to verify their identity. This challenge appears anytime a user, who has not been previously authenticated via two-factor, tries to access an organization.

6.3.1. How to Set Up Two-Factor authentication

1. Sign-up for a Duo Account at https://www.duosecurity.com/pricing.
2. Create and configure a Duo application to use with the Resilient platform.

During this stage, you receive an Integration Key, Secret Key, and API hostname. You need these items to configure two-factor authentication on the Resilient platform.

When prompted for the application type, select Web SDK.

3. If you are a SAAS customer, contact support@resilientsystems.com to complete your setup. Afterwards, proceed to Enabling your authentication domain.
4. For an on-premises deployment, follow the instructions below to configure two-factor authentication with the Resilient platform.
5. Locate the Integration Key, Secret Key, and API hostname from your Duo application.
6. Determine the names of one or more Resilient organizations that can enable the two-factor domain. (When this procedure is completed, a master administrator can then choose to enable the two-factor domain for each of those organizations.)
7. Create a two-factor domain:

$ sudo resutil -twofactoredit -name <domain_name> -org <org_name> -integrationkey <duo_integration_key> -host <duo_api_hostname> -integrationsecret <duo_integration secret>

Where:

<domain_name> is the name of the two-factor authentication domain. This name is presented to your Organization Administrator in a drop down.

<duo_integration_key>, <duo_api_hostname>, and <duo_integration secret> are values obtained from Duo Security after completing their configuration.

<org_name> is the name of an organization in the Resilient platform that may utilize the two-factor domain. Multiple -org <org_name> arguments can be provided.

You can also use the twofactoredit to change the name of an existing domain and clear any orgs associated with it.

To display the details of an existing two-factor domain:

$ sudo resutil -twofactorshow -name <domain_name>

NOTE: If the -name is not specified, all the organizations with two-factor authentication are displayed.

To delete a two-factor domain:

$ sudo resutil -twofactordel -name <domain_name>

In some cases, you may want to exclude a specific user belonging to an organization configured for two-factor authentication; for example, you want to programmatically access the Resilient REST API with a system account. This can be done by using the twofactorexcluser command:

$ sudo twofactorexcluser -email user@example.com

This enables user@example.com to access the two-factor org without providing the Duo authentication.

You can re-enable two-factor authentication by using the -clearemail flag. For example:

$ sudo twofactorexcluser -clearemail user@example.com

6.3.2. Enabling Your Authentication Domain

While logged in as a master administrator, you can enable a two-factor authentication domain under organizational settings on the administrator's settings page. If you have set up multiple two-factor authentication domains, you can select which domain you would like to authenticate your users against here. On this page, you can also set the cookie lifetime, which sets an expiration in days for when a user needs to re-authenticate via two-factor authentication.

NOTE: Authentication domains are set at the organizational level. You can use the same authentication domain for multiple organizations or set a different domain for each organization. This means that a user who authenticates against an organization under one domain, who then tries to access an organization under another domain, needs to separately authenticate for the other organization.

6.3.3. Registering Users

Once two-factor authentication has been configured, users need an account on the Resilient platform and a corresponding account in your Duo Security account.

Management of user registration with Duo security is handled in the Policy settings of your Duo Security application. The "New user policy" allows you to select:

• Require Enrollment - users who are not already registered with Duo security are provided a self-enrollment process that makes it easy for users to register their devices and install the Duo mobile app (if necessary). When a user logs into the Resilient platform for the first time after two-factor authentication is enabled, Duo Security begins this self-enrollment process.
• Allow Access - users who are not already registered with Duo security are not challenged. We recommend AGAINST using this option.
• Deny Access - only users who are already configured with the Duo account are allowed access. This means that you need to configure your users using your Duo account in the "Users" tab.

The email address of the Resilient platform must match the Duo account username. In the Duo application settings, "Username normalization" allows you to specify whether or not "DOMAIN\username", "username@example.com" and "username" are all treated as the same user.

6.3.4. Two-Factor Authentication and User Experience

When two-factor authentication is enabled, if a user has not been "previously authenticated" via two-factor authentication, they are presented with a two-factor challenge whenever they try to access an organization.

A user is considered as being "previously authenticated" under the following circumstances:

• They have successfully passed the challenge presented via two-factor authentication in their current session.
• They have successfully passed the challenge presented via two-factor authentication in a session then started a new session within the number of days set by the cookie lifetime value. In this situation, the user authenticates as normal (email and password) when starting the new session, but is not presented with the challenge. The master administrator sets the cookie lifetime value in the administrator settings organization page.

7. KeyVaults

In previous versions, the secrets were stored in various locations. The KeyVault feature combines all relevant application “secrets” into a single Java keystore.

Combining the secrets into a single place provides the following benefits:

• Provides cryptographic protection for all application secrets.
• Simplifies access control to application secrets.
• Provides a single master key that unlocks all secrets.

7.1. Storage Format, Location and Key

The application secrets are stored in a Java JCEKS KeyStore. The following files are relevant, which are in the /crypt/keyvault directory by default.

7.2. Configuration Options

KeyVault configuration settings are stored in the /crypt/keyvault/keys.properties file. The file is a standard Java properties file, where each line contains a key and value separated by an ‘=’.

The following table contains the KeyVault configuration options.

The following is an example that does not backup the password file and changes its location:

should_backup_password=false

passwordfile=/some/other/directory/mykeyvaultpassword

7.3. KeyVault Backup

The KeyVault stores very important data that, if lost, would cause a considerable loss of data. For that reason, it must be backed up. The default installation of the Resilient platform writes a backup of the KeyVault files to the system database any time the KeyVault changes and after each system upgrade.

The default installation includes the KeyVault password in this backup.

The net result of this approach is that if you are currently backing up your database, it includes your KeyVault backup. If you choose to NOT backup your KeyVault password (should_backup_password is set to false in keys.properties), then you must ensure that the KeyVault files are backed up separately.

To restore the most recent backup, use the following command:

sudo resutil keyvaultrestore -dir <directory>

The –dir specifies where to restore the backup.

To restore a different backup, you need to supply the -date argument, which is specified in this format, yyyy-MM-ddThh:mm:ss. For example:

sudo resutil keyvaultrestore -dir somedir -date 2016-09-26T11:00:00

To view the list of backups, perform the following SQL query:

sudo -u postgres -i psql -c 'select kvb_date, kvb_reason from monapp.keyvault_backups' co3

7.4. Secrets

Secrets in the KeyVault can be retrieved using the following command:

sudo resutil keyvaultget -name <secret name>

Similarly, secrets can be saved to the KeyVault using the following command:

sudo resutil keyvaultset -name <secret name> -value <secret value>

The following table lists the secrets that you can retrieve from or save to the KeyVault.

8. Backup and Restore

You can back up the Resilient platform, which consists of the database, keyvault and attachments. You can restore the backup to another virtual appliance running the same version.

In order to back up the platform, you must ssh to the virtual appliance and run this command:

sudo resSystemBackup

This creates a backup in the /crypt/backups/ folder in the form of a gz file; for example, resilient-backup-20170426201138.tar.gz. The timestamp is appended to the filename for uniqueness. You can rename this file for clarity, and move it to a secure location.

You can encrypt the backup by using the –encrypt option as follows:

sudo resSystemBackup --encrypt

To view all the options:

sudo resSystemBackup --help

Usage: resSystemBackup [OPTIONS]

Backs up a resilient appliance.

-f, --file File to backup to, defaults to

/crypt/backups/resilient-backup-TIMESTAMP.tar.gz

-k, --keysize GPG keysize, defaults to 64 bytes

(128 characters in hex)

-g, --gpgalgo GPG algorithm to use, defaults to AES-256

-p, --passfile Specify a GPG passfile, defaults to

/usr/share/co3/conf/backup_passphrase (which will be
created if

it does not exist)

-e, --encrypt Encrypt the resulting backup

-a, --exclude-attachments Do not backup the attachments folder

-q, --quiet Suppress output

-v, --verbose Output everything

In order to restore a backup, use this command:

sudo resSystemRestore -f /crypt/backups/resilient-backup-20170426201138.tar.gz

**** POTENTIALLY DESTRUCTIVE BEHAVIOR ****

The existing database will be dropped

Are you sure? YES/NO: YES

[ ok ] Stopping Resilient Application: resilient.

[ ok ] Stopping Resilient Scripting Application: resilient-scripting.

To view all the options, use this command:

sudo resSystemRestore –help

Usage: resSystemRestore [OPTIONS] -f BACKUP

Restores a resilient appliance from a backup generated by resSystemBackup.

-c, --no-version-check Do not validate appliance versions

-f, --file Specify the backup file

-p, --passfile Specify a file containing a GPG password.

This option must be set if the file was encrypted

(the default for resSystemBackup)

-v, --verbose Output everything

-q, --quiet Minimal output, will not prompt for confirmation

9. Upgrade Procedure

You can upgrade from a V27.x platform. If you are using an older version of the Resilent platform, you must first to upgrade to version 27.

IMPORTANT: Before you upgrade, make sure that your appliance has a minimum of 8 gigabytes of memory. Previous releases required only 4 gigabytes.

If your appliance has internet access, run the following command from the Resilient appliance.

wget --trust-server-names https://repo.co3sys.com/public/d0dfd285cfd91d4722ec67f98dc148e9/latest.php

The command downloads a resilient-<version>.run file. Use the following command to install the file using the actual version number (typically in the format x.x.x) in the file name.

sudo bash resilient-<version>.run

If your appliance does not have internet access, run the wget command above from another system then copy the downloaded file to your appliance and run the following command using the actual version number in the file name:

sudo bash resilient-<version>.run

Depending on the amount of data, you may experience longer upgrade times. You can monitor the progress by examining the update_database_x.log as follows. The x represents the build number of the new version.

$ sudo tail -f /usr/share/co3/logs/ update_database_x.log

After the upgrade completes and if you have the Security Module, you should convert your built-in "Security Rules" for your existing organization into the new rules-based format for easy customization. You do not need to perform this procedure for organizations created in V27. To do this, use the following command:

$ sudo resutil migratetasks

Options:

• -allorgs, --allorgs: Indicates that all organizations on this server are to be migrated. Default is false.
• -help, --help: Prints the migratetasks help. Default is false.
• -orgname, --orgname: Name of the organization to be migrated.

If you have any questions regarding this update, please contact our support team at support@resilientsystems.com.